Giới thiệu
SpeedSMS Voice API cho phép bạn tích hợp tính năng tạo cuộc gọi tự động vào trong ứng dụng của bạn. Bạn có thể tích hợp Voice API vào Website, ứng dụng desktop, hay các ứng dụng di động. SpeedSMS Voice API tương thích với tất cả các ngôn ngữ lập trình phổ biến hiện nay như: C#, ASP.NET, PHP, Java,... SpeedSMS Voice API đảm bảo tính nhanh, đơn giản, tin cậy và dễ dàng tích hợp vào bất kỳ hệ thống nào.
Hiện tại SpeedSMS chỉ hỗ trợ Voice OTP API (gửi mã xác thực/OTP bằng cuộc gọi), các tính năng khác sẽ được hỗ trợ trong thời gian tới.
API URL
Tất cả các API sẽ được bắt đầu bằng địa chỉ url:
http://api.speedsms.vn/index.php/
Hoặc
https://api.speedsms.vn/index.php/
Các bạn nên sử dụng địa chỉ HTTPS để đảm bảo tính bảo mật.
Authentication
Để sử dụng Voice API bạn cần phải đăng ký một tài khoản tại địa chỉ https://connect.speedsms.vn. Mỗi tài khoản đăng ký sẽ được cấp một API access token. Ứng dụng của bạn sẽ sử dụng API access token này để xác thực (authenticate) với SpeedSMS.
API access token được gửi kèm với bản tin HTTP request thông qua cơ chế xác thực HTTP Basic Authentication. Trong đó API access token sẽ đóng vai trò như là một username.
Ví dụ: để gọi API thông qua curl:
curl -i -u "{API access token}:x" "http://api.speedsms.vn/index.php/user/info"
Để lấy API access token, bạn vui lòng đăng nhập tại địa chỉ https://connect.speedsms.vn, sau đó click vào menu "Settings" -> "Profile" để lấy thông tin API access token
Rate limit
SpeedSMS Voice API cho phép ưng dụng của bạn gọi tối đa 60 requests trong vòng 60 giây. Nếu bạn gọi quá số lần requests. Bạn sẽ nhận được response:
{"name":"Too Many Requests","message":"Rate limit exceeded.","code":0,"status":429}
Lúc này bạn cần phải kiểm tra tham số X-Rate-Limit-Reset trong header của bản tin HTTP để lấy số giây cần phải đợi và thực hiện cơ chế sleep trước khi tiếp tục thực hiện requests.Trong trường hợp bạn cần nhiều hơn 60 requests vui lòng liên hệ để chúng tôi nâng hạn mức cho bạn.
Error codes
- 007: IP locked
- 008: Account blocked
- 009: Account not allow to call the API
- 101: Invalid or missing parameters
- 105: Phone number invalid
- 300: Your account balance not enough
- 500: Internal error, please try again
- 601: OTP number is not valid
API tạo cuộc gọi OTP
POST /voice/otp API cho phép bạn tạo cuộc gọi tới một số thuê bao di động.
Gọi API thông qua curl:
curl -i -u "{Access token}" -H "Content-Type: application/json" -X POST -d '{"to": "phone number", "content": "mã OTP"}' http://api.speedsms.vn/index.php/voice/otp
- to: Số điện thoại của người nhận cuộc gọi (lưu ý: số điện thoại ở dạng: 09x, 01x)
- content: Chứa mã xác nhận/mã OTP, lưu ý: Hiện tại hệ thống chỉ hỗ trợ mã OTP dạng numeric (chỉ chứa chữ số từ 0 - 9)
ví dụ: {"to": "0912345678", "content": "1234"}
Gọi API sử dụng GET method: GET /voice/otp?to=0912345678&content=1234
Success response:
{ "status": "success", "code": "00", "data": { "tranId": "transaction id", "totalPrice": total price } }
- tranId: được sử dụng để tra cứu trạng thái của cuộc gọi vừa tạo
- totalPrice: Tổng chi phí để gửi tin nhắn
Error response:
{ "status": "error", "code": "error code", "message": "error description" }