Verification API

Verification API

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:
Tham số Mô tả Giá trị

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:
  1. api key
  2. 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
viVietnamese