Hướng dẫn cách sử dụng tính năng gửi SMS qua API

phucnd
12/04/2020

Hướng dẫn cách sử dụng tính năng gửi SMS qua API

Tính năng gửi SMS qua API trên ứng dụng SMS Marketing Advanced sẽ giúp bạn có thể tích hợp gửi SMS từ chính điện thoại/số điện thoại của mình vào bất kỳ website hay ứng dụng bên thứ 3 nào (không cần đăng ký đầu số). Nhiều bạn sẽ thắc mắc không hiểu cách thức hoạt động của tính năng này là như thế nào? Bài viết này chúng tôi sẽ giải thích chi tiết để các bạn hiểu rõ và sử dụng nó.

*** Chúng tôi đã tích hợp tính năng gửi SMS qua API vào website: https://send.smsmarketing.vn/, bạn có thể vào website này để gửi SMS từ máy tính. Xem hướng dẫn chi tiết về cách cấu hình TẠI ĐÂY.

➡️ Đầu tiên bạn cần hiểu API là gì?

API là các phương thức, giao thức để kết nối với các thư viện và ứng dụng khác. Nó là viết tắt của Application Programming Interface – giao diện lập trình ứng dụng. API cung cấp khả năng truy xuất đến một tập các hàm hay dùng. Và từ đó có thể trao đổi dữ liệu giữa các ứng dụng.

➡️ Vậy gửi SMS qua API là như thế nào?

Gửi SMS qua API là cách thức gửi SMS thông qua hàm API do chúng tôi định nghĩa với các tham số chỉ định sẵn (secret key, số điện thoại, tên khách hàng,...). Khi hàm API này được gọi, nó sẽ kết nối và gửi các thông số nhận được đến ứng dụng SMS Marketing Advanced. Sau đó, ứng dụng sẽ lấy các thông số mà bạn đã cấu hình: nội dung gửi, SIM gửi,... để gửi SMS đến số điện thoại khách hàng mà bạn đã truyền vào ở trên. Để có thể tích hợp được tính năng này thì bạn cần:

- Có thiết bị (điện thoại/máy tính bảng chạy Android) đã cài đặt và kích hoạt bản quyền ứng dụng SMS Marketing Advanced.

- Hiểu biết một chút về kỹ thuật lập trình.

*** Với khách hàng không biết về lập trình thì việc tích hợp này cần nhờ bên phát triển hệ thống web / app để giúp tích hợp.

➡️ Kịch bản áp dụng

Kịch bản áp dụng phổ biến nhất đó là tích hợp vào form đăng ký/đặt hàng trên các website. Tức là, nếu website của bạn tích hợp tính năng gửi SMS qua API thì sau khi khách hàng đăng ký/đặt hàng thành công (có các thông tin như: số điện thoại, họ tên,...), họ sẽ nhận được một tin nhắn SMS thông báo (với nội dung gửi, SIM gửi được cấu hình trên ứng dụng SMS Marketing Advanced) một cách hoàn toàn tự động.

Ngoài ra, tính năng gửi SMS qua API cũng được khá nhiều khách hàng của chúng tôi sử dụng để tích hợp gửi mã OTP vào hệ thống của họ.

➡️ Chi tiết các tham số của hàm API chúng tôi cung cấp để gửi SMS như sau:

Api Url: https://api.smsmarketing.vn/campaign/sendone/

Method: POST

Post body: JSON object

{
"secretKey" : "[Lấy trong ứng dụng]", //bắt buộc
"customerPhone" : "[Số điện thoại của khách hàng muốn gửi tin nhắn]", //bắt buộc
"customerName" : "[Tên khách hàng]", //không bắt buộc
"customerGender" : "[Giới tính khách hàng (Nam/Nữ/Công Ty)]", //không bắt buộc
"customerInfo" : "[Thông tin khác của khách hàng]" //không bắt buộc, 👉 bắt buộc nếu truyền toàn bộ nội dung tin nhắn qua trường này
}

Kết quả trả về dạng JSON object như sau:

Gửi thành công

{

"errorCode": 0, // mã lỗi = 0

"hasError": false //không có lỗi

}

Gửi lỗi

{

"errorCode": [một trong các mã lỗi: 2111, 2112, 2113, 2114, 2115, 2116, 2117, 2118, 2222], //mã lỗi khác 0

"hasError": true //có lỗi

}

Chi tiết các mã lỗi:

2111: Secret Key hoặc Số điện thoại khách hàng trống.

2112: Secret Key không đúng.

2113: Không tìm thấy tài khoản.

2114: Tài khoản chưa được kích hoạt.

2115: Tài khoản không được phép gửi SMS qua API.

2116: Tính năng gửi SMS qua API đang bị TẮT.

2117: Secret Key đã hết hạn.

2118: Đã dùng hết số lượng API requests miễn phí cho tháng hiện tại (mỗi tháng miễn phí 5000 requests thành công).

2222: Lỗi hệ thống.

➡️ Code mẫu trên một số ngôn ngữ lập trình

.NET (C#)

      public async Task<ResponseView> SendSms(SendSmsModel sendSmsModel)
        {
           const string apiUrl= "https://api.smsmarketing.vn/campaign/sendone/";
            var responseInJsonString = await PostRequest(apiUrl, ToStringContent(sendSmsModel));
            return JsonConvert.DeserializeObject<ResponseView>(responseInJsonString);
        }

public StringContent ToStringContent(object o)
=> new StringContent(JsonConvert.SerializeObject(o), Encoding.UTF8, "application/json");

public async Task<string> PostRequest(string url, HttpContent httpContent)
{
var handler = new HttpClientHandler
{
ServerCertificateCustomValidationCallback = (message, xcert, chain, errors) =>
{
return true;
}
};
using (var webClient = new HttpClient(handler))
{
var result = await webClient.PostAsync(url, httpContent);
return await result.Content.ReadAsStringAsync();
}
}

public class SendSmsModel
{
public string SecretKey { get; set; }

public string CustomerPhone { get; set; }

public string CustomerName { get; set; }

public string CustomerGender { get; set; }

public string CustomerInfo { get; set; }
}

public class ResponseView
{
public int ErrorCode { get; set; }
public bool HasError { get; set; }
}

JAVASCRIPT/JQUERY

function sendSms(key, phone, name, gender, info) {
$.ajax({
url: "https://api.smsmarketing.vn/campaign/sendone/",
type: "POST",
data: JSON.stringify({ secretKey: key, customerPhone: phone, customerName: name, customerGender: gender, customerInfo: info }),
contentType: "application/json; charset=UTF-8",
success: function (data) {
if (data.hasError) {
//Có lỗi
} else {
//Gửi tin nhắn thành công
}
},
error: function () {
}
});
}

PHP

$url = 'https://api.smsmarketing.vn/campaign/sendone/';
$ch = curl_init($url);

$data = array(
'secretKey' => '[YOUR_KEY]',
   'customerPhone' => '[CUSTOMER_PHONE]',
   'customerName' => '[CUSTOMER_NAME]',
   'customerGender' => '[CUSTOMER_GENDER]',
'customerInfo' => '[CUSTOMER_INFO]'
);

$payload = json_encode($data);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

//Get response
$data = json_decode(file_get_contents('php://input'), true);

➡️ Cách lấy Secret Key và cấu hình các thông số để gửi SMS

B1: Mở ứng dụng SMS Marketing Advanced -> click vào Menu ở phía trên bên phải -> chọn Cấu hình gửi SMS qua API:

B2: Sau khi màn hình cấu hình gửi SMS qua API hiển thị, bạn click vào nút LẤY để lấy Secret Key và bật tính năng này. Sau đó bạn cấu hình các thông số như: Nội dung gửi (xem cách soạn nội dung tùy chỉnh TẠI ĐÂY), cấu hình giới tính, chọn SIM gửi mặc định, cấu hình SIM gửi theo đầu số, tùy chọn Chỉ hiển thị thông báo.

*** Chú ý: Nếu tùy chọn Chỉ hiển thị thông báo được BẬT thì ứng dụng sẽ không gửi tin nhắn SMS mà chỉ hiển thị thông báo trên thanh notification của điện thoại.

B3: Sau khi thiết lập các thông số, bạn nhấn vào nút LƯU LẠI để lưu các cấu hình vừa thiết lập. Khi tích hợp thì sao chép Secret Key này để truyền vào hàm API mà chúng tôi cung cấp.

*** Chú ý:

- Secret Key là rất quan trọng, chỉ chia sẻ với những ai thật sự cần thiết.

- Nếu muốn TẮT tính năng gửi SMS qua API thì hãy xóa Secret Key, bạn vẫn có thể lấy lại và BẬT tính năng này vào bất cứ lúc nào bạn muốn.