Tingting ZALO API

Giới thiệu

Tingting ZALO API cho phép bạn gửi thông báo tới số điện thoại của khách hàng thông qua kênh Zalo. Khách hàng sẽ nhận được thông báo trên ứng dụng Zalo của khách hàng. Bạn có thể tích hợp với Zalo API bằng nhiều ngôn ngữ lập trình khác nhau như: PHP, .Net, Java, NodeJS, Python,…

Tingting ZALO 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 ZALO 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/zns?apikey=

Truyền tham số apikey trong HTTP header:

curl -H “Content-type: application/json” -H “apikey: ” -X POST -d ‘{“to”: “8491xxxxxx”, “content”: “test”, “sender”: “TingTing”}’ “https://v1.tingting.im/api/zns

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 inactive
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	ZALO
tranId	Là transaction id bạn nhận được khi gọi api send zns	string
delivery	là giá trị cho biết trạng thái của zns đã đượ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 zns
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=ZALO&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

ZALO API

Để gửi nội dung tin nhắn chăm sóc khách hàng, hoặc mã OTP tới một hoặc nhiều số điện thoại thông qua kênh ZALO. Để gọi ZALO API bạn cần tạo một HTTP request (POST hoặc GET) tới địa chỉ URL sau:

https://v1.tingting.im/api/zns

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

api key
Sender (Zalo official account ID)
‘to’ Số điện thoại người nhận
‘tempid’ template id
‘temp_data’ giá trị các tham số của nội dung template

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 trị được ki vọ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
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ự.
tempid	là template id của nội dung tin nhắn đã được đăng ký
temp_data	là giá trị của các tham số có trong template

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 trị được ki vọ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
failover	là tham số để cho phép gửi lại tin nhắn thông qua kênh SMS trong trường hợp gửi qua kênh ZALO bị lỗi.	Định dạng JSON như sau: {“sender”: “brandname”, “content”: “sms content”}

Gọi API với CURL

POST method

curl -H “Content-type: application/json” -H “apikey: Your api key” -X POST -d ‘{“to”: “8491xxxxxxx”, “sender”: “4510641052409513869”, “tempid”: “dksh38dj”, “temp_data”: {“otp”: “1234”}}’ “https://v1.tingting.im/api/zns”

GET method

curl -H “Content-type: application/json” “https://v1.tingting.im/api/zns?apikey=apikey&to=8491xxxxxxx&sender=4510641052409513869&tempid=dksh38dj&temp_data={‘otp’:’1234′}”

ZALO API response

Success response

Định dạng JSON:

{“status”: “success”, “sms”: “sms count”, “cost”: “sms cost”, “tranId”: “sms transaction id”}

Trong đó:

Tham số	Mô tả	Giá trị
status	cho biết trạng thái khi gọi api là thành công hay thất bại	string success là đã gọi api thành công
sms	Số tin đã được gửi, được tính dựa trên số người nhận	integer, ví dụ: 1
cost	Chi phí cho tin nhắn đã được gửi. Chi phí được tính dựa trên số lượng tin nhắn và giá của 1 tin nhắn	float Ví dụ: 1000
tranId	Là transaction id của tin nhắn đã được gửi, mỗi tin nhắn sẽ có 1 transaction id duy nhất.	string

Error response

Định dạng JSON:

{“status”: “error”, “code”: “error code”, “message”: “error description”}

Trong đó:

Tham số	Mô tả	Giá trị
status	Cho biết trạng thái gọi api	string error
code	mã lỗi	integer Gía trị từ 1-1000 vui lòng xem chi tiết trong bảng mã lỗi.
message	Mô tả lỗi	string mô tả lỗi.

SMS Failover

Là tính năng cho phép gửi lại tin nhắn qua kênh SMS brandname mà không cần phải gọi lại API trong trường hợp tin nhắn gửi qua kênh ZaLo bị lỗi (ví dụ: số điện thoại người nhận ko đăng ký zalo).

Để sử dụng tính năng sms failover thì khi gọi zalo api bạn chỉ cần truyền thêm tham số: failover.

Tham số failover là 1 JSON object như sau:

{“sender”: “brandname”, “content”: “sms content”}