Tingting SMS API

Giới thiệu

Tingting SMS API cho phép bạn gửi tin nhắn tới số điện thoại của khách hàng thông qua kênh SMS Brandname. Bạn có thể tích hợp với SMS API bằng nhiều ngôn ngữ lập trình khác nhau như: PHP, .Net, Java, NodeJS, Python,… Tingting SMS API hoạt động trong cả hai phương thức GET và POST. Tất cả các API đều bắt đầu với URL: https://v1.tingting.im/api/

Authentication

Để tích hợp với Tingting SMS API trước tiên bạn phải đăng ký một tài khoản tại địa chỉ: https://app.tingting.im Tingting API sử dụng tham số apikey để xác thực người dùng. Để tạo apikey bạn đăng nhập vào website và vào menu: Developers Mỗi apikey cần whitelist địa chỉ IP của server gọi API, bạn có thể điền nhiều địa chỉ IP, mỗi địa chỉ IP cách nhau bởi dấu phẩy. Mỗi lần gọi API bạn cần truyền tham số apikey này trong URL query string hoặc HTTP Header với tên tham số là: apikey Ví dụ: Truyền tham số apikey trên URL query string Curl -H “Content-type: application/json” -X POST -d ‘{“to”: “8491xxxxxx”, “content”: “test”, “sender”: “TingTing”}’ “https://v1.tingting.im/api/sms?apikey=apikey” Truyền tham số apikey trong HTTP header:

Error code

Bảng mã lỗi

Code	Description
1	Unauthorized
2	IP not whitelist
3	Missing requirements parameters
4	Invalid date/timezone format
5	Sender not found
6	Balance not enough
7	Not support send sms or call to the destination
8	Invalid template data
9	template not found or inactivate
10	Invalid timeout value
11	Invalid failover value

Webhook

Là tính năng cho phép bạn nhận các thông báo về các sự kiện như: người dùng đã nhận được tin nhắn, người dùng đã trả lời cuộc gọi,…. thông qua một callback url của bạn. Để nhận được các sự kiện từ Tingting bạn cần phải thiết lập một callback url của bạn. Để thiết lập callback url bạn đăng nhập vào dashboard sau đó vào menu: Settings -> Callback profile Hệ thống của Tingting sau khi nhận được các sự kiện từ nhà mạng hoặc đối tác sẽ tạo một HTTP Request tới địa chỉ callback url của bạn với các tham số như sau:

Tham số	Mô tả	Giá trị
channel	cho biết sự kiện thuộc channel nào	SMS
tranId	Là transaction id bạn nhận được khi gọi api send sms	string
delivery	là giá trị cho biết trạng thái của sms đã được gửi thành công hay chưa	0: unknown 1: delivered (đã gửi thành công) 2: undelivered (gửi thất bại)
phone	là số điện thoại	số điện thoại người nhận sms
delivery_time	Thời gian của sự kiện	dữ liệu dạng timestamp

các tham số trên được truyền thông qua callack url. Ví dụ: https://yourcallbackurl.com?channel=SMS&tranId=123456&delivery=1&phone=8491xxxxxxx&delivery_time=1636304215

Download code mẫu

Để download code mẫu và hướng dẫn sử dụng cho các ngôn ngữ lập trình khác nhau, bạn có thể truy cập github của Tingting theo đường dẫn sau: https://github.com/tingtingcomms

SMS API

Điều kiện tiên quyết

1. api key
2. SenderID (Brandname)
3. ‘to’ Số điện thoại người nhận
4. Nội dung tin nhắn

Thông số kỹ thuật tham số API

Các thông số kỹ thuật của tham số API được mô tả trong bảng sau. Các thông số bắt buộc nghĩa là bạn phải truyền vào khi gọi API, trong khi các thông số tùy chọn được xác định theo yêu cầu của người dùng.

Các tham số bắt buộc

Các tham số bắt buộc trong API được lập bảng bên dưới:

Tham số	Sự miêu tả	Gia trị được ki vọng
apikey	Là api key để xác thực, vui lòng xem mục Authentication để tìm hiểu cách tạo api key.	mã api key tương ứng với mỗi tài khoản
to	Là số điện thoại của người nhận tin nhắn, để gửi tới nhiều sđt cùng lúc vui lòng thêm dấu phẩy “,” giữa các sđt. Bạn có thể gửi tối đa tới 100 sđt cùng lúc.	Định dạng số điện thoại phải có mã quốc gia ở đầu, ví dụ: 8491xxxxxxx trong đó 84 là mã quốc gia Việt nam
content	Là nội dung tin nhắn cần gửi, vui lòng xem mục Quy định độ dài tin nhắn để biết cách tính độ dài 1 tin nhắn.	Nội dung có thể là tiếng anh hoặc tiếng việt có dấu, độ dài tối da là 3 sms
sender	Là tên thương hiệu, tên thương hiệu sẽ hiển thị ở phần người gửi trên điện thoại của khách hàng.	Tên thương hiệu cần được đăng ký trước, có độ dài tối đa 11 ký tự.

Các tham số tùy chọn

Các tham số tuỳ trọn trong API được lập bảng bên dưới:

Tham số	Sự miêu tả	Gia trị được ki vọng
send_time	Trong trường hợp bạn muốn thiết lập thời gian gửi sms	Định dạng yyyy-mm-dd H:i:s Ví dụ: 2021-11-10 16:30:00
timezone	Là time zone của giá trị ngày tháng của tham số send_time. Ví dụ: Asia/Ho_Chi_Minh	Giá trị mặc định là UTC trong trường hợp bạn không set giá trị cho tham số timezone