Zalo ZNS

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

CodeDescription
1Unauthorized
2IP not whitelist
3Missing requirements parameters
4Invalid date/timezone format
5Sender not found
6Balance not enough
7Not support send sms or call to the destination
8Invalid template data
9template not found or inactive
10invalid timeout value
11invalid 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ị
channelcho biết sự kiện thuộc channel nàoZALO
tranIdLà transaction id bạn nhận được khi gọi api send znsstring
deliverylà 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)

phonelà số điện thoạisố điện thoại người nhận zns
delivery_timeThời gian của sự kiệndữ 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

  1. api key
  2. Sender (Zalo official account ID)
  3. ‘to’ Số điện thoại người nhận
  4. ‘tempid’ template id
  5. ‘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 trị được ki vọng
apikeyLà 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
toLà 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
senderLà 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ự.
tempidlà template id của nội dung tin nhắn đã được đăng ký 
temp_datalà 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 trị được ki vọng
send_timeTrong 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

timezoneLà time zone của giá trị ngày tháng của tham số send_time. Ví dụ: Asia/Ho_Chi_MinhGiá trị mặc định là UTC trong trường hợp bạn không set giá trị cho tham số timezone
failoverlà 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ị
statuscho 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

smsSố tin đã được gửi, được tính dựa trên số người nhậninteger, ví dụ: 1
costChi 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

tranIdLà 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ị
statusCho biết trạng thái gọi api

string

error

codemã lỗi

integer

Gía trị từ 1-1000 vui lòng xem chi tiết trong bảng mã lỗi.

messageMô 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”}

Trong đó:

Tham sốMô tảGiá trị
senderLà brandname đã được đăng ký 
contentLà nội dung của tin nhắn cần gửi. 
viVietnamese