Giới thiệu
Tingting
Verification API cho phép bạn tích hợp tính năng xác thực số điện thoại vào website hoặc mobile app của bạn một cách dễ dàng và nhanh chóng. Tingting
verification api hỗ trợ gửi mã OTP thông qua các kênh như: SMS, Voice, Zalo giúp bạn tối ưu chi phí. Bạn có thể tích hợp với Verification API bằng nhiều ngôn ngữ lập trình khác nhau như: PHP, .Net, Java, NodeJS, Python,…
Tingting Verification 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
Verification 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:
curl -H “Content-type: application/json” -H “apikey: ” -X POST -d ‘{“to”: “8491xxxxxx”, “content”: “test”, “sender”: “TingTing”}’ “https://v1.tingting.im/api/sms”
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 |
| 12 |
Configuration ID not found |
| 13 |
Configuration ID was inactivate |
| 14 |
Configuration channels not found |
| 15 |
Message ID not found |
| 16 |
Message ID was expired |
| 17 |
SMS content too long |
| 18 |
Invalid phone number format |
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
REST API
Để tích hợp với Verification rest api đầu tiên bạn phải tạo một verify configuration, bạn đăng nhập vào dashboard sau đó vào menu: Verify chọ Add Configuration và làm theo hướng dẫn.
Create PIN API
Để tạo mã PIN và gửi tới số điện thoại của khách hàng, bạn tạo một HTTP request tới địac hỉ URL sau:
https://v1.tingting.im/api/pin
Điều kiện tiên quyết
1. api key
2. Configuration ID
3. to (số điện thoại nhận mã otp)
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ố |
Mô tả |
Giá trị |
| 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 |
| config_id |
Là ID của verify configuration |
mã configuration id đã được tạo |
| to |
Là số điện thoại nhận mã OTP |
Đị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 |
| channel |
Là kênh để gửi mã OTP |
Tingting hỗ trợ các kênh sau:
1. SMS: gửi mã OTP thông qua kênh SMS
2. VOICE: gửi mã OTP thông qua kênh Voice |
Các tham số tuỳ chọn
Các tham số tuỳ trọn trong API được lập bảng bên dưới:
Gọi API với CURL
POST method
curl -H “Content-type: application/json” -H “apikey: Your api key” -X POST -d ‘{“to”: “8491xxxxxxx”, “config_id”: “Configuration ID”, “channel”: “SMS”}’ “https://v1.tingting.im/api/pin”
GET method
curl -H “Content-type: application/json” “https://v1.tingting.im/api/pin?apikey=apikey&to=8491xxxxxxx&config_id=configid&channel=SMS”
API response
Success response
Định dạng JSON: {“status”: “success”, “data”: {“msg_id”: “message id”, “count_down”: “timer count down”, “validity”: “OTP validity time”}} Trong đó:
| Tham số |
Mô tả |
Giá trị |
| status |
Cho biết trạng thái gọi api là thành công hay thất bại |
success |
| msg_id |
Là message id |
message id sử dụng để verify trạng thái của OTP |
| count_down |
Thời gian đếm ngược tính bằng giây |
Là khoảng thời gian cho phép gửi lại mã OTP mới |
| validity |
Là thời gian hiệu lực của mã OTP |
Nếu hết hiệu lực, người dùng cần tạo mã OTP mới |
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 |
Gía trị từ 1-1000 vui lòng xem chi tiết trong bảng mã lỗi. |
| message |
Mô tả lỗi |
|
Widget API
Cho phép bạn tích hợp Verification widget vào website hoặc ứng dụng mobile (iOS, Android) mà không cần phải xây dựng verification UI, giúp tiết kiệm thời gian phát triển.
Tingting hỗ trợ tích hợp verification widget vào các nền tảng như: website (HTML & JS), iOS, Android
HTML & JavaScript
Để nhúng verification widget vào website, bạn chỉ cần dán đoạn mã code sau vào cuối phần HTML ngay trước thẻ đóng:
Tiếp theo bạn thêm đoạn mã code HTML sau vào vị trí hoặc trang nơi mà bạn muốn hiển thị verification widget:
Để show verification widget trước tiên bạn cần tạo một widget session. Để tạo widget session bạn cần gọi tới api sau:
https://widgetapiv1.tingting.im/api/session. API widget session cần phải được gọi trên backend của bạn.
Điều kiện tiên quyết:
- api key
- config_id
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ố |
Mô tả |
Giá trị |
| 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 |
| config_id |
Là ID của verify configuration |
mã configuration id đã được tạo |
Các tham số tuỳ chọn
Các tham số tuỳ trọn trong API được lập bảng bên dưới:
| Tham số |
Mô tả |
Giá trị |
| to |
Trong trường hợp hệ thống của bạn đã lưu sđt của user trước đó, và bạn muốn user không cần phải nhập lại sđt trên giao diện widget, bạn có thể set giá trị cho tham số to. |
Đị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 |
Gọi API với CURL
POST method
curl -H “Content-type: application/json” -H “apikey: Your api key” -X POST -d ‘{“to”: “8491xxxxxxx”, “config_id”: “Configuration ID”}’ “https://widgetapiv1.tingting.im/api/session”
GET method
curl -H “Content-type: application/json” “https://widgetapiv1.tingting.im/api/session?apikey=apikey&to=8491xxxxxxx&config_id=ConfigurationID”
API response
Success response
Định dạng JSON: {“status”: “success”, “session”: “widget session key”, “name”: “Configuration name”, “default”: “default channel”, “allows”: “allow channels”, “to”: “phone number”} Trong đó:
| Tham số |
Mô tả |
Giá trị |
| session |
Widget session key |
Mỗi session có giá trị trong vòng 10 phút |
| name |
Tên của configuration |
|
| default |
Kênh mặc định để gửi mã OTP |
Giá trị là: SMS hoặc VOICE |
| allows |
Danh sách các kênh cho phép gửi mã OTP |
Danh sách kênh phụ thuộc vào lúc bạn thêm channel khi tạo verify configuration. Nếu bạn thêm cả 2 kênh SMS và VOICE thì giá trị là: SMS,VOICE trong trường hợp bạn chỉ thêm một kênh SMS hoặc VOICE thì giá trị có thể là: SMS hoặc VOICE |
| to |
Số điện thoại nhận mã OTP |
Trong trường hợp bạn không truyền tham số to khi gọi session api, trường to sẽ có giá trị là giỗng |
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 |
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 |
|
Hiển thị widget
Sau khi tạo widget session, bạn gọi hàm javascript sau để hiển thị widget, ở bước này bạn thực hiện bên phía frontend
VerificationWidget.show(params, function(result) {});
Trong đó params là một json object với các tham số như sau:
{“session”: “widget session”, “default”: “default channel”, “allows”: “allow channels”, “lang”: “widget language”, “logo”: “logo url”, “display_name”: “widget title”, “to”: “phon number”}
Trong đó, các tham số bắt buộc bao gồm:
| Tham số |
Mô tả |
Giá trị |
| session |
Là widget session bạn đã tạo trước đó |
|
| default |
Là kênh mặc định để gửi mã OTP |
Giá trị được gửi về từ backend |
| allows |
danh sách kênh cho phép gửi mã OTP |
Giá trị gửi về từ backend |
Cá tham số tuỳ trọn bao gồm:
| Tham số |
Mô tả |
Giá trị |
| logo |
Logo hiển thị trên widget |
logo url, kích thước 50x50px |
| display_name |
Title của widget |
|
| lang |
Ngôn ngữ của widget |
Hỗ trợ tiếng anh và việt, giá trị là: vi hoặc en |
| to |
Số điện thoại nhận OTP |
Số điện thoại được gửi về từ phía backend |
Sau khi user đã thực hiện thao tác nhận và nhập mã OTP trên widget thành công, bạn sẽ nhận được kết quả trả về trong callback như sau:
VerificationWidget.show(params, function(result) {
if (!result) {
//user press the x button to close widget.
}
else {
//process to verify pin code
}
});
trong đó result là một json object với các tham số như sau:
{“msg_id”: “verification message id”, “pin_code”: “mã otp mà user nhận được”}
Sau khi đã nhận được kết quả trả về từ widget, bạn sẽ cần phải verify lại kết quả một lần nữa với hệ thống của tingting, ở bước này bạn thực hiện gọi api để verify từ phía backend.
Để verify kết quả, bạn gọi api sau: https://widgetapiv1.tingting.im/api/status
Điều kiện tiên quyết:
1. api key
2. msg_id: message id nhận được từ widget
3. pin_code: mã otp nhận được từ widget
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ố |
Mô tả |
Giá trị |
| 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 |
| msg_id |
Là message ID nhận được từ widget trả về |
|
| pin_code |
Là mã OTP user đã nhập vào verification widget |
|
Gọi API với CURL
POST method
curl -H “Content-type: application/json” -H “apikey: Your api key” -X POST -d ‘{“msg_id”: “Message id”, “pin_code”: “OTP code”}’ “https://widgetapiv1.tingting.im/api/status”
GET method
curl -H “Content-type: application/json” “https://widgetapiv1.tingting.im/api/status?apikey=apikey&msg_id=messageId&pin_code=OTPcode”
API Response
Success Response
Định dạng JSON: {“status”: “success”, “data”: {“msg_id”: “messaid”, “pin_code”: “otp code”, “verified”: “verify status”, “phone”: “user phone number”}} Trong đó:
| Tham số |
Mô tả |
Giá trị |
| status |
Cho biết trạng thái gọi API |
success |
| msg_id |
Là message id bạn truyền lên trong request |
|
| pin_code |
Là mã OTP bạn truyền lên trong request |
|
| phone |
Là số điện thoại của user nhận mã OTP |
|
| verified |
Cho biết trạng thái user xác thực sđt thành công hay chưa |
Có 2 giá trị:
1: User đã xác thực sđt thành công
0: User chưa xác thực sđt thành công |
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 |
error |
| code |
Mã lỗi |
Xem chi tiết trong bảng mã lỗi |
| message |
Mô tả lỗi |
|
Vietnamese 
English