Giới thiệu
SpeedSMS API cho phép bạn tích hợp tính năng gửi tin nhắn vào trong ứng dụng của bạn. Bạn có thể tích hợp SMS API vào Website, ứng dụng desktop, hay các ứng dụng di động. SpeedSMS 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 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.
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 SMS API bạn cần phải đăng ký một tài khoản tại địa chỉ http://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.
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ỉ http://connect.speedsms.vn, sau đó click vào menu "Tài khoản". Một dialog sẽ hiện lên chứa thông tin về API access token
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
- 110: Not support sms content encoding
- 113: Sms content too long
- 300: Your account balance not enough to send sms
- 500: Internal error, please try again
API lấy thông tin tài khoản
GET /user/info là API cho phép bạn lấy thông tin về tài khoản hiện tại bao gồm địa chỉ email và số dư tài khoản.
Gọi API thông qua curl:
curl -i -u "{API access token}:x" "http://api.speedsms.vn/index.php/user/info"
Success response:
{ "status": "success", "code": "00", "data": { "email": "your email address", "balance": "balance number", "currency": "VND" } }
Error response:
{ "status": "error", "code": "error code", "message": "error description" }
API gửi tin nhắn
POST /sms/send API cho phép bạn gửi tin nhắn tới một hoặc nhiều số thuê bao di động (tối đa 100 số).
Gọi API thông qua curl:
curl -i -u "{Access token}" -H "Content-Type: application/json" -X POST -d '{"to": ["phone number1", "phone number2"], "content": "noi dung sms", "sms_type": "loại tin nhắn (quảng cáo, CSKH, brand name,Notify,android app)", "sender": "tên thương hiệu hoặc deviceId"}' https://api.speedsms.vn/index.php/sms/send
- to: mảng chứa danh sách các số điện thoại. SpeedSMS hiện đang cung cấp dịch vụ gửi tin nhắn tới hơn 200 Quốc gia trên thế giới, để gửi tin nhắn đi Quốc tế bạn chỉ cần thêm mã quốc gia vào trước số điện thoại, ví dụ: +12089464415, +4915224730470, +33755882189, +447453805430,...
- content: Nội dung của tin nhắn, hỗ trợ cả nội dung tiếng việt có dấu. 160 ký tự/1sms đối với nội dung tiếng anh hoặc tiếng việt không dấu, 70ký tự/1sms đối với nội dung tiếng việt có dấu (unicode). Nếu nội dung tin nhắn của bạn dài hơn 160 ký tự (đối với nội dung tiếng anh hoặc tiếng việt không dấu) hoặc 70 ký tự (dối với nội dung tiếng việt có dấu) thì tin nhắn sẽ được tự động gửi dưới dạng long sms. Tổng độ dài nội dung tin nhắn không được vượt quá 3 sms. Hiện chưa hỗ trợ tiếng việt có dấu đối với tin nhắn brandname và đầu số cố định.
-
sms_type: Loại tin nhắn muốn gửi tới, trong đó:
- 2: là tin nhắn dạng cskh
- 3: là tin nhắn dạng brand name
- 4: là tin sử dụng brandname mặc định: Notify
- 5: là tin nhắn gửi bằng app android sử dụng số di động cá nhân
- 6: là tin nhắn gửi bằng đầu số cố định
- sender: tên thương hiệu đã được đăng ký hoặc deviceId của app android, tham số này bắt buộc phải được set nếu sms_type = 3 hoặc 5
ví dụ: {"to": ["0912345678"], "content": "test sms", "sms_type": 2, "sender": ""}
Success response:
{ "status": "success", "code": "00", "data": { "tranId": transaction id number, "totalSMS": total sms number, "totalPrice": total price number, "invalidPhone": array of phone numbers } }
- tranId: được sử dụng để tra cứu trạng thái của sms vừa gửi
- totalSMS: Tổng số tin nhắn được gửi
- totalPrice: Tổng chi phí để gửi tin nhắn
- invalidPhone: Mảng chứa danh sách các số điện thoại không hợp lệ.
Error response:
{ "status": "error", "code": "error code", "message": "error description" }
API gửi tin nhắn quảng cáo Brandname
POST /campaign/send API cho phép bạn gửi chiến dịch quảng cáo qua tin nhắn Brandname.
Gọi API thông qua curl:
curl -i -u "{Access token}" -H "Content-Type: application/json" -X POST -d '{"to": ["phone number1", "phone number2"], "content1": "noi dung quang cao 1", "content2": "noi dung quang cao 2", "sender": "tên thương hiệu", "name": "Campaign name", "send_time": "thoi gian gui tin nhan"}' https://api.speedsms.vn/index.php/campaign/send
- to: mảng chứa danh sách các số điện thoại cần gửi tin nhắn tới (lưu ý: số điện thoại ở dạng: 09x, 01x), mỗi chiến dịch bạn phải gửi tối thiểu 100 số điện thoại.
- content1: Nội dung của tin nhắn gửi tới các thuê bao của mạng Viettel, Mobifone (160 ký tự tiếng việt không dấu 1 sms).
- content2: Nội dung của tin nhắn gửi tới các thuê bao của mạng Vinaphone, Vietnamobile, Gmobile (122 ký tự tiếng việt không dấu 1 sms)
- sender: tên thương hiệu đã được đăng ký
- name: tên chiến dịch
- send_time: thời gian mà bạn muốn gửi tin nhắn tới khách hàng (thời gian từ 8:00 AM tới 19:30 PM các ngày trong tuần). Lưu ý để đặt lịch gửi tin nhắn vào các ngày thứ 7 và CN bạn phải gửi chiến dịch trước 15:30 PM của ngày thứ 6.
ví dụ: {"to": ["0912345678"], "content1": "noi dung 1", "content2": "noi dung 2", "sender": "SPEEDSMS", "name": "saleoff", "send_time": "14-06-2018 16:00"}
Success response:
{ "status": "success", "code": "00", "data": { "campaignId": transaction id number, "totalSMS": total sms number, "totalPrice": total price number, "invalidPhone": array of phone numbers } }
- campaignId: được sử dụng để tra cứu trạng thái của sms vừa gửi
- totalSMS: Tổng số tin nhắn được gửi
- totalPrice: Tổng chi phí để gửi tin nhắn
- invalidPhone: Mảng chứa danh sách các số điện thoại không hợp lệ.
Error response:
{ "status": "error", "code": "error code", "message": "error description" }
API kiểm tra trạng thái tin nhắn
GET /sms/status/{tranId} API cho phép bạn kiểm tra trạng thái tin nhắn đã gửi
Gọi API thông qua curl:
curl -i -u '{Access token}' http://api.speedsms.vn/index.php/sms/status/{tranId}
Success response:
{ "status": "success", "code": "00", "data": [ {"phone": "phone number1", "status": status}, {"phone": "phone number2", "status": status} ] }
status = 0: trạng thái đang chờ gửi
status = -1: trạng thái đang gửi
status = 1: gửi thành công
status = 2: gửi lỗi
Error response:
{ "status": "error", "code": "error code", "message": "error description" }
Delivery status report (Thông báo tin nhắn đã tới máy người nhận hay chưa)
Hầu hết mọi người khi sử dụng dịch vụ SMS API thường có chung băn khoăn là tin nhắn có thực sự được gửi tới máy khách hàng hay không hoặc khách hàng đã nhận được tin nhắn hay chưa? Trong trường hợp chúng ta cần gửi thông tin quan trọng tới khách hàng mà không biết khách hàng đã nhận được tin nhắn hay chưa thì sẽ cảm thấy rất không an tâm. SpeedSMS sẽ giúp bạn giải quyết vấn đề này bằng tính năng Delivery status report. Khi tin nhắn được gửi thành công hoặc lỗi (trong trường hợp máy hết pin hoặc ngoài vùng phủ sóng) tới máy người nhận thì SpeedSMS sẽ thông báo cho bạn biết bằng cách SpeedSMS sẽ gửi một bản tin HTTP Post tới địa chỉ url mà bạn đã cung cấp cho SpeedSMS (cơ chế này còn được gọi là Webhook).
Để sử dụng tính năng delivery report trước tiên bạn cần đăng nhập vào trang dashboard tại địa chỉ http://connect.speedsms.vn vào menu Setting -> Webhook sau đó khai báo một địa chỉ url để nhận request từ SpeedSMS khi tin nhắn được gửi thành công tới máy người nhận.
Khi tin nhắn đã được gửi thành công tới máy người nhận SpeedSMS sẽ gửi một bản tin HTTP với dữ liệu như sau tới địa chỉ url mà bạn đã cung cấp:
{"type": "report", "tranId": "transaction id", "phone": "phone number", "status": "status success/failed"}
Trong đó:
- type: để phân biệt giữa bản tin thông báo delivery report với bản tin thông báo incoming sms
- tranId: là transaction id mà bạn nhận được sau khi gọi API /sms/send
- phone: là số điện thoại của khách hàng nhận được tin nhắn
- status: là trạng thái của tin nhắn đã gửi thành công/thất bại tới máy người nhận hay chưa status = 0: success
0 < status < 64 temporary fail
status >= 64: failed
ví dụ: {"type": "report", "tranId": 1234, "phone": "0912345678", "status": 0} // thành công
hoặc: {"type": "report", "tranId": 1234, "phone": "0912345678", "status": 69} // thất bại (trong trường hợp máy điện thoại hết pin hoặc ngoài vùng phủ sóng hoặc thuê bao bị blocked)
Incoming sms (nhận tin nhắn phản hồi)
Khi khách hàng nhận được tin nhắn từ dịch vụ của bạn, KH có thể trả lời lại tin nhắn này, khi đó bạn sẽ có thể nhận được tin phàn hồi của KH.
Tương tự như delivery report, bạn cũng cần phải khai báo một địa chỉ url để nhận request từ SpeedSMS khi có KH phản hồi lại tin nhắn cho bạn.
Khi có tin nhắn phàn hồi từ phía KH SpeedSMS sẽ gửi một bản tin HTTP với dữ liệu như sau tới địa chỉ url mà bạn đã cung cấp:
{"type": "sms", "phone": "phone number", "content": "sms content"}
Trong đó:
- type: để phân biệt giữa bản tin thông báo delivery report với bản tin thông báo incoming sms
- phone: là số điện thoại của khách hàng nhận được tin nhắn
- content: là nội dung tin nhắn
Gửi sms bằng android app sử dụng số di động cá nhân
Để gửi sms từ số di động của bạn, trước tiên bạn cần download ứng dụng cho hệ điều hành android từ Google play, bạn có thể download từ link này: download
Sau khi cài đặt app trên điện thoại, bạn đăng nhập bằng tài khoản đã đăng ký trên trang http://speedsms.vn hoặc nếu chưa có tài khoản bạn có thể đăng ký một tài khoản ngay trong app.
Sau khi đăng nhập thành công là bạn có thể bắt đầu gửi sms từ chính số di động của bạn. Trong quá trình gửi sms bạn không cần phải chạy app trên điện thoại, khi có tin nhắn cần gửi đi SpeedSMS sẽ gửi push notification tới app và app sẽ tự động kết nối tới SpeedSMS server để lấy thông tin và gửi sms đi cho bạn.
App android cũng hỗ trợ nhận thông báo delivery status report và incoming sms thông qua webhook, chi tiết bạn xem tại đây.