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:

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

Đ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