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 Access Token

Để sử dụng SMS 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.

Để lấy API access token, bạn vui lòng đăng nhập tại địa chỉ https://connect.speedsms.vn, sau đó vào menu: "Settings" chọn "Profile"

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

Tích hợp API (SMS & VOICE OTP)

SpeedSMS đã cung cấp sẵn code mẫu cho các ngôn ngữ lập trình PHP,  Java, C#, NodeJS, giúp bạn tiết kiệm thời gian và có thể bắt đầu tích hợp SMS API ngay. Vui lòng chọn ngôn ngữ tương ứng với ứng dụng của bạn bên dưới để download SpeedSMS code.
PHP

Code mẫu cho PHP

Bạn vui lòng click vào link bên dưới để download code mẫu

Download PHP Code

Java
C#
NodeJS

Sau đây là hướng dẫn cách sử dụng SpeedSMSAPI để tích hợp vào code của bạn:

PHP

/*
 * Đầu tiên bạn cần phải thêm thư viện của SpeedSMS bằng cách thêm dòng code sau:
*/
require("SpeedSMSAPI.php");

/**
 * Tiếp theo tạo một instance của class SpeedSMSAPI và truyền vào tham số là api access token của bạn.
 */
$smsAPI = new SpeedSMSAPI("Your access token");
/**
 * Để lấy thông tin về tài khoản như: email, số dư tài khoản bạn sử dụng hàm getUserInfo()
 */

$userInfo = $smsAPI->getUserInfo();
/* * Hàm getUserInfo() sẽ trả về một mảng như sau:
 * /
["email"=>"[email protected]", "balance" =>100000.0, "currency" => "VND"]

/** Để gửi SMS bạn sử dụng hàm sendSMS như sau:
*/
$phones = ["8491xxxxx", "8498xxxxxx"]; 
/* tối đa 100 số cho 1 lần gọi API */
$content = "test sms";
$type = sms_type
/**
sms_type có các giá trị như sau:
2: tin nhắn gửi bằng đầu số ngẫu nhiên
3: tin nhắn gửi bằng brandname
4: tin nhắn gửi bằng brandname mặc định (Verify hoặc Notify)
5: tin nhắn gửi bằng app android
*/
$sender = "brandname";
/**
brandname là tên thương hiệu hoặc số điện thoại đã đăng ký với SpeedSMS
*/

$response = $smsAPI->sendSMS($phones, $content, $type, $sender);

/**hàm sendSMS sẽ trả về một mảng như sau:*/
[
   "status"=>"success", "code"=> "00", 
   "data"=>[
    "tranId"=>123456, "totalSMS"=>2,     
     "totalPrice"=>500, "invalidPhone"=>[] 
      ]
]
*/
// Trong trường hợp gửi sms bị lỗi, hàm sendSMS sẽ trả về mảng như sau:
[
"status"=>"error", "code"=>"error code", "message" => "error description",
"invalidPhone"=>["danh sách sdt lỗi"]
]

/** Để gửi VOICE OTP bạn sử dụng hàm sendVoice như sau:
*/
$phone = "8491xxxxx"; 
$content = "xxxx";
/* nội dung chỉ chứa mã code, ví dụ: 1234 */
$response = $smsAPI->sendVoice($phone, $content);

/**hàm sendVoice sẽ trả về một mảng như sau:*/
[
   "status"=>"success", "code"=> "00", 
   "data"=>[
    "tranId"=>123456,     
     "totalPrice"=>400, "invalidPhone"=>[] 
      ]
]
*/
// Trong trường hợp gửi voice otp bị lỗi, hàm sẽ trả về mảng như sau:
[
"status"=>"error", "code"=>"error code", "message" => "error description",
"invalidPhone"=>["danh sách sdt lỗi"]
]
Java
C#
NodeJS
Curl

Delivery Status Report

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)

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