Để 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"
Sau đây là hướng dẫn cách sử dụng SpeedSMSAPI để tích hợp vào code của bạn:
/*
* Đầ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"]
]
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 đó:
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 đó: