API Voice OTP

Dịch vụ gọi thoại đến khách hàng để cung cấp mật khẩu sử dụng một lần. Với mục đích xác thực giao dịch trực tuyến.

Tiền điều kiện:

1. Đã tạo ứng dụng trên hệ thống AICall Cloud (xem cách tạo)

2. Đối với tài khoản trả trước: Số dư khả dụng còn đủ để thực hiện cuộc gọi (bảng giá dịch vụ)

3. Đã tạo ACCESS_TOKEN với mã OTP_CODE (xem thêm)

NodeJS

const ACCESS_TOKEN = jwt.sign({ apiKey: API_KEY, otpCode: OTP_CODE }, API_SECRET);

Python

ACCESS_TOKEN = jwt.encode({ apiKey: API_KEY, otpCode: OTP_CODE }, API_SECRET)

Java

String ACCESS_TOKEN = JWT.create()
        .withClaim("apiKey", API_KEY)
        .withClaim("otpCode", OTP_CODE)
        .withIssuedAt(new Date(currentTimeMillis)) // Include "iat" claim
        .sign(algorithm);

PHP

$ACCESS_TOKEN = JWT::encode([ "apiKey" => $API_KEY, "otpCode" => $OTP_CODE ], $API_SECRET, 'HS256');

Chi tiết API:

Thực hiện cuộc gọi xác thực OTP

POST https://aicall.vbee.ai/api/v1/public-api/voice-otp

(*) Trường bắt buộc

Headers

Name	Type	Description
Authorization*	String	Bearer <ACCESS_TOKEN>

Request Body

Name	Type	Description
phone_number*	String	Số điện thoại cần gửi mã xác thực OTP
voice*	String	Mã giọng đọc (Xem danh sách mã giọng)
rate	Number	Tốc độ đọc, mặc định: 1.0

200: OK Thành công

{
  "message": "success",
  "result": {
    "contact_id": "8b740f88-3e93-48b7-98d4-e1dc28d08cbb"
  },
  "status": 1
}

Nếu bạn có kích hoạt webhook, xem định dạng dữ liệu trả về ở mục Webhook API

Danh sách mã giọng

Mã giọng	Vùng miền	Giới tính
hn_female_ngochuyen_full_48k-fhg	Miền Bắc	Nữ
hue_female_huonggiang_full_48k-fhg	Miền Trung	Nữ
sg_female_thaotrinh_full_48k-fhg	Miền Nam	Nữ

Code mẫu

Java

package org.example;


import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;
import com.google.gson.Gson;


import java.io.IOException;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;


public class Main {
   public static void main(String[] args) {
       OkHttpClient client = new OkHttpClient();
       String API_KEY = "<API_KEY>";
       String API_SECRET = "<API_SECRET>";
       String OTP_CODE = "<MÃ_OTP_CODE>";
       String PHONE_NUMBER = "<PHONE_NUMBER>";
       String URL = "https://aicall.vbee.ai/api/v1/public-api/voice-otp";


       Map<String, Object> data = new HashMap<>();
       data.put("phoneNumber", PHONE_NUMBER);
       data.put("voice", "hn_female_ngochuyen_full_48k-fhg");
       data.put("rate", 1);


       String ACCESS_TOKEN = generateJWT(API_KEY, OTP_CODE, API_SECRET);


       Gson gson = new Gson();


       RequestBody requestBody = RequestBody.create(MediaType.parse("application/json"), gson.toJson(data));
       Request request = new Request.Builder()
               .url(URL)
               .header("Authorization", "Bearer " + ACCESS_TOKEN)
               .post(requestBody)
               .build();


       try {
           Response response = client.newCall(request).execute();
       } catch (IOException e) {
           e.printStackTrace();
       }
   }


   private static String generateJWT(String apiKey, String otpCode, String apiSecret) {
       Algorithm algorithm = Algorithm.HMAC256(apiSecret);


       // Include the "iat" claim with the current timestamp
       long currentTimeMillis = System.currentTimeMillis();


       String token = JWT.create()
               .withClaim("apiKey", apiKey)
               .withClaim("otpCode", otpCode)
               .withIssuedAt(new Date(currentTimeMillis)) // Include "iat" claim
               .sign(algorithm);
       return token;
   }
}

PHP

<?php
use \Firebase\JWT\JWT;
$API_KEY = '<API_KEY>';
$API_SECRET = '<API_SECRET>';
$OTP_CODE = '<MÃ_OTP_CODE>';
$PHONE_NUMBER = '<PHONE_NUMBER>';
$URL = 'https://aicall.vbee.ai/api/v1/public-api/voice-otp';


$payload = array(
   "apiKey" => $API_KEY,
   "otpCode" => $OTP_CODE
);


$ACCESS_TOKEN = JWT::encode($payload, $API_SECRET, 'HS256');


$data = array(
   "phoneNumber" => $PHONE_NUMBER,
   "voice" => 'hn_female_ngochuyen_full_48k-fhg',
   "rate" => 1
);


$ch = curl_init($URL);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
   'Authorization: Bearer ' . $ACCESS_TOKEN,
   'Content-Type: application/json'
));


$response = curl_exec($ch);
curl_close($ch);


echo $response;

Nội dung lỗi trả về có thuộc tính status luôn là 0. Ví dụ:

{
  "status": 0,
  "code": 401,
  "message": "Unauthorized"
}

Danh sách mã lỗi:

Code	Mesage	Ý nghĩa
401	Unauthorized	ACCESS_TOKEN không hợp lệ
500		Lỗi hệ thống
1104	Portal wallet is expired	Ví hết hạn sử dụng (đối với tài khoản trả trước)
1201	Application is not found	Không tìm thấy ứng dụng (kiểm tra lại thông tin API_KEY)
1204	OTP content is not found	Không tìm thấy nội dung thông báo OTP_CODE (xem cách tạo ứng dụng)
1501	Hotline is empty or inactive	Nhóm đầu số gọi ra không có hoặc không hoạt động
1603	Portal wallet is out of money	Số dư không đủ để thực hiện cuộc gọi (đối với tài khoản trả trước)
2301	Pool hotline do not exist	Không tìm thấy nhóm đầu số gọi ra
2302	Pool hotline is inactive	Nhóm đầu số gọi ra không hoạt động