Voice API

Tingting Voice API

Giới thiệu

Tingting Voice API cho phép bạn gửi nội dung thông báo, mã OTP, hoặc các thông tin khác tới số điện thoại của khách hàng thông qua kênh thoại Voice. Bạn có thể tích hợp với Voice API bằng nhiều ngôn ngữ lập trình khác nhau như: PHP, .Net, Java, NodeJS, Python,…

Tingting Voice 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 Voice 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/call?apikey=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/call”

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 VOICE
tranId Là transaction id bạn nhận được khi gọi call api string
delivery là giá trị cho biết trạng thái của cuộc gọi đã được gọi thành công hay chưa

0: unknown

1: answered (đã gọi thành công)

2: call failed (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=VOICE&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

CALL API

Để gửi nội dung thông báo hoặc mã OTP tới một hoặc nhiều số điện thoại thông qua kênh thoại Voice. Để gọi CALL 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/call

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

  1. api key
  2. CallerID (số điện thoại gọi đi)
  3. ‘to’ Số điện thoại người nhận
  4. Nội dung thông báo

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 cuộc gọi, để 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 thông báo, nội dung sẽ được hệ thống tự động chuyển thành file âm thanh bằng công nghệ text-to-speech. Nội dung có thể là tiếng anh hoặc tiếng việt có dấu, độ dài tối đa không quá 60 giây khi chuyển thành file âm thanh.
sender Là số điện thoại được dùng để gọi đi Khách hàng cần phải đăng ký trước một số điện thoại dạng SIP trunk với Tingting.

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
lang Cho biết nội dung thông báo thuộc ngôn ngữ nào, ví dụ tiếng anh hoặc tiếng việt.

Hiện tại Tingting hỗ trợ 2 loại ngôn ngữ là tiếng anh, và tiếng việt. Tham số lang có 2 giá trị như sau:

vi: tiếng việt

en: tiếng anh

speech_rate Là tốc độ đọc nội dung thông báo Giá trị mặc định là 1, bạn có thể truyền giá trị từ 0.5 – 1.5
gender Cho biết giọng đọc nội dung thông báo là nam hay nữ Giá trị mặc định là female, bạn có thể truyền các giá trị sau:
female: giọng đọc nữ
male: giọng đọc nam
send_time Trong trường hợp bạn muốn thiết lập thời gian gọi đi

Đị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

Gọi API với CURL

POST method

curl -H “Content-type: application/json” -H “apikey: Your api key” -X POST -d ‘{“to”: “8491xxxxxxx”, “content”: “Your verification code is 1 1 2 1”, “sender”: “0904262830”}’ “https://v1.tingting.im/api/call”

GET method

curl -H “Content-type: application/json”  “https://v1.tingting.im/api/call?apikey=apikey&to=8491xxxxxxx&content=test&sender=0904262830”

API response

Success response

Định dạng JSON:

{“status”: “success”, “duration”: “audio duration”, “cost”: “total cost”, “tranId”: “call 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

duration Là độ dài của file âm thanh khi chuyển thành từ văn bản, tính theo giây integer, ví dụ: 10
cost Chi phí cho cuộc gọi.

float

Ví dụ: 500

tranId Là transaction id của cuộc gọi, mỗi cuộc gọi 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.

en_USEnglish