Send an OTP Call

POST/v1/otp-call

Place a call to a Bangladeshi mobile number and read a 4–8 digit OTP aloud. Choose the built-in Bangla or English OTP voice, or your own approved introduction recording. Omit voiceId to use the system default (initially Bangla). OTP requests are prioritized ahead of broadcast calls.

Headers

Header	Required	Description
X-API-Key	Yes	Your customer API key.
Content-Type	Yes	application/json.
Idempotency-Key	Recommended	A unique identifier for this logical request. Reuse it only when retrying the same request.

Request body

Field	Type	Required	Description
phone	string	Yes	Valid Bangladeshi mobile number. Local 01712345678 and E.164 +8801712345678 formats are accepted. Maximum 32 characters.
otp	string	Yes	Exactly 4–8 numeric digits. Use a string, including for values like 004821.
repeatCount	integer	No	Read the code 1–3 times. Default: 2.
voiceId	string	No	Optional. Copy the Bangla or English OTP voice ID from Dashboard → Voices, or use your own approved recording. When omitted, the system default OTP voice is used (initially Bangla).
senderId	string	No	An active sender available to your account. Without this field, an owned sender is selected first, with shared-sender fallback when available.

Only the documented body properties are accepted. repeatCount must be a JSON number, not a numeric string.

Built-in OTP voices

Dashboard → Voices → OTP voices contains two ready-to-use recordings: বাংলা OTP and English OTP. Copy either full voice ID and pass it as voiceId. The selected built-in voice determines both the introduction and the language of the OTP digits.

{ "phone": "01712345678", "otp": "004821", "voiceId": "1002" }

The built-in IDs are 1001 (Bangla) and 1002 (English). To use the default, omit voiceId entirely:

{ "phone": "01712345678", "otp": "004821" }

Bangla is the initial default. Administrators can replace either recording and select the system default in Voice Library → System OTP voices. Recording replacements keep these IDs unchanged. Your own approved recording uses the system’s configured digit language.

Request examples

Replace the sample phone number before running. These examples place real calls when executed with a valid key.

cURL

curl -X POST 'https://api.kokilcloud.com/v1/otp-call' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: verification-example-001' \
  -d '{"phone":"01712345678","otp":"482913","repeatCount":2}'

Node.js

// Run on your server, not in browser JavaScript.
const response = await fetch('https://api.kokilcloud.com/v1/otp-call', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.KOKILCLOUD_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'verification-example-001',
  },
  body: JSON.stringify({ phone: '01712345678', otp: '482913', repeatCount: 2 }),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result.callId);

Python

import os
import requests

response = requests.post(
    'https://api.kokilcloud.com/v1/otp-call',
    headers={
        'X-API-Key': os.environ['KOKILCLOUD_API_KEY'],
        'Idempotency-Key': 'verification-example-001',
    },
    json={'phone': '01712345678', 'otp': '482913', 'repeatCount': 2},
    timeout=30,
)
response.raise_for_status()
print(response.json()['callId'])

PHP

<?php
$ch = curl_init('https://api.kokilcloud.com/v1/otp-call');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('KOKILCLOUD_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: verification-example-001',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phone' => '01712345678', 'otp' => '482913', 'repeatCount' => 2,
    ]),
]);
$body = curl_exec($ch);
if ($body === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException($body);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
echo $result['callId'];

Response

HTTP 202 Accepted — example:

{
  "callId": "YOUR_CALL_ID",
  "status": "queued",
  "queuePosition": 1
}

Save callId and use Get Call Status to track the result. The response confirms acceptance, not successful delivery. On an idempotent replay, callId is the existing request and status can already have advanced.

Errors

Invalid input or insufficient balance returns 400. Invalid keys return 401. An inactive account, disallowed package, or unavailable sender returns 403. Conflicting use of an idempotency key can return 409. See Error Responses.