AmarVoice API Documentation

Authentication

All API requests require authentication using a Bearer token. You can obtain your API token from your dashboard account settings.

Important: Keep your API token secure and never share it publicly.

Example Request Header

Authorization: Bearer your_api_token_here

Download Postman Collection Import into Postman to test the API

POST /api/broadcasts/otp

Voice OTP Broadcast

Send OTP (One-Time Password) voice messages to a single phone number. The voice must contain at least one dynamic part with digit mode to read the OTP code.

Request Parameters

Parameter	Type	Required	Description
request_id	string	Yes	Unique request identifier (16-64 chars) to prevent duplicate requests. Use UUID or random string.
voice	string	Yes	Name of your approved voice with digit mode
sender	string	Yes	Your active caller sender number
phone_number	string	Yes	Single Bangladeshi phone number (01XXXXXXXXX format)
otp_code	string	Yes	OTP code (4-6 digits)

Request Example

curl -X POST https://api.awajdigital.com/api/broadcasts/otp \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "unique_request_id_123",
    "voice": "your_voice_name",
    "sender": "8801234567890",
    "phone_number": "019XXXXXXXX",
    "otp_code": "1234"
  }'

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/broadcasts/otp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    request_id: 'unique_request_id_123',
    voice: 'your_voice_name',
    sender: '8801234567890',
    phone_number: '019XXXXXXXX',
    otp_code: '1234'
  })
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function sendOtpBroadcast() {
  try {
    const response = await axios.post('https://api.awajdigital.com/api/broadcasts/otp', {
      request_id: 'unique_request_id_123',
      voice: 'your_voice_name',
      sender: '8801234567890',
      phone_number: '019XXXXXXXX',
      otp_code: '1234'
    }, {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Content-Type': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

sendOtpBroadcast();

# Python with requests
import requests

def send_otp_broadcast():
    url = 'https://api.awajdigital.com/api/broadcasts/otp'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Content-Type': 'application/json'
    }
    data = {
        'request_id': 'unique_request_id_123',
        'voice': 'your_voice_name',
        'sender': '8801234567890',
        'phone_number': '019XXXXXXXX',
        'otp_code': '1234'
    }

    try:
        response = requests.post(url, json=data, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

send_otp_broadcast()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/broadcasts/otp';
$token = 'your_api_token_here';

$data = [
    'request_id' => 'unique_request_id_123',
    'voice' => 'your_voice_name',
    'sender' => '8801234567890',
    'phone_number' => '019XXXXXXXX',
    'otp_code' => '1234'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "broadcast": {
    "id": 123,
    "name": "otp_api_1_your_voice_019XXXXXXXX",
    "status": "broadcasting",
    "createdAt": "2025-12-29T10:30:00.000Z"
  }
}

Note: Use a unique request_id for each request to prevent duplicate processing. Requests with the same request_id within 15 minutes will be rejected.

GET /api/broadcasts/:id/result

Get Broadcast Result

Retrieve the result of a broadcast. If the broadcast is still in progress, only status information is returned. If the broadcast is complete, detailed results for each phone number are included.

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The broadcast ID returned from broadcast creation

Request Example

curl -X GET https://api.awajdigital.com/api/broadcasts/123/result \
  -H "Authorization: Bearer your_api_token_here"

// Browser JavaScript (Fetch API)
const broadcastId = 123;
const response = await fetch(`https://api.awajdigital.com/api/broadcasts/${broadcastId}/result`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_token_here'
  }
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function getBroadcastResult(broadcastId) {
  try {
    const response = await axios.get(
      `https://api.awajdigital.com/api/broadcasts/${broadcastId}/result`,
      {
        headers: {
          'Authorization': 'Bearer your_api_token_here'
        }
      }
    );

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getBroadcastResult(123);

# Python with requests
import requests

def get_broadcast_result(broadcast_id):
    url = f'https://api.awajdigital.com/api/broadcasts/{broadcast_id}/result'
    headers = {
        'Authorization': 'Bearer your_api_token_here'
    }

    try:
        response = requests.get(url, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

get_broadcast_result(123)

<?php
// PHP with cURL
$broadcastId = 123;
$url = "https://api.awajdigital.com/api/broadcasts/{$broadcastId}/result";
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

$result = json_decode($response, true);
print_r($result);
?>

Running Broadcast Response

{
  "success": true,
  "broadcast": {
    "id": 123,
    "name": "api_1_voice_3",
    "status": "broadcasting",
    "listenerCount": 3,
    "completeCount": 1,
    "createdAt": "2025-12-30T10:00:00.000Z"
  },
  "isComplete": false,
  "message": "Broadcast is still in progress"
}

Completed Broadcast Response

{
  "success": true,
  "broadcast": {
    "id": 123,
    "name": "api_1_voice_3",
    "status": "completed",
    "listenerCount": 3,
    "completeCount": 3,
    "createdAt": "2025-12-30T10:00:00.000Z"
  },
  "isComplete": true,
  "statusDistribution": {
    "pending": 0,
    "answered": 2,
    "notAnswered": 1,
    "rejected": 0,
    "busy": 0,
    "failed": 0,
    "unknown": 0
  },
  "results": [
    {
      "phoneNumber": "019XXXXXXXX",
      "status": "answered",
      "duration": 45
    },
    {
      "phoneNumber": "018XXXXXXXX",
      "status": "not_answered",
      "duration": null
    },
    {
      "phoneNumber": "017XXXXXXXX",
      "status": "answered",
      "duration": 30
    }
  ]
}

Note: The isComplete field indicates whether the broadcast has finished. Only when isComplete is true will the results array and statusDistribution be included in the response.

POST /api/broadcasts

Broadcast to Multiple Numbers

Send voice messages to multiple phone numbers in a single API call. Perfect for bulk announcements, notifications, or marketing campaigns.

Request Parameters

Parameter	Type	Required	Description
request_id	string	Yes	Unique request identifier (16-64 chars) to prevent duplicate requests. Use UUID or random string.
voice	string	Yes	Name of your approved voice
sender	string	Yes	Your active caller sender number
phone_numbers	array	Yes	Array of Bangladeshi phone numbers (01XXXXXXXXX format, max 999 numbers)

Request Example

curl -X POST https://api.awajdigital.com/api/broadcasts \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "unique_request_id_456",
    "voice": "your_voice_name",
    "sender": "8801234567890",
    "phone_numbers": ["019XXXXXXXX", "018XXXXXXXX", "017XXXXXXXX"]
  }'

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/broadcasts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    request_id: 'unique_request_id_456',
    voice: 'your_voice_name',
    sender: '8801234567890',
    phone_numbers: ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX']
  })
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function sendBroadcast() {
  try {
    const response = await axios.post('https://api.awajdigital.com/api/broadcasts', {
      request_id: 'unique_request_id_456',
      voice: 'your_voice_name',
      sender: '8801234567890',
      phone_numbers: ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX']
    }, {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Content-Type': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

sendBroadcast();

# Python with requests
import requests

def send_broadcast():
    url = 'https://api.awajdigital.com/api/broadcasts'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Content-Type': 'application/json'
    }
    data = {
        'request_id': 'unique_request_id_456',
        'voice': 'your_voice_name',
        'sender': '8801234567890',
        'phone_numbers': ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX']
    }

    try:
        response = requests.post(url, json=data, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

send_broadcast()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/broadcasts';
$token = 'your_api_token_here';

$data = [
    'request_id' => 'unique_request_id_456',
    'voice' => 'your_voice_name',
    'sender' => '8801234567890',
    'phone_numbers' => ['019XXXXXXXX', '018XXXXXXXX', '017XXXXXXXX']
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "broadcast": {
    "id": 123,
    "name": "api_1_your_voice_3",
    "status": "broadcasting",
    "createdAt": "2025-12-29T10:30:00.000Z"
  }
}

GET /api/voices

List Voices

Retrieve a list of all voices created by the authenticated user along with their approval status.

Request Example

curl -X GET https://api.awajdigital.com/api/voices \
  -H "Authorization: Bearer your_api_token_here"

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/voices', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_token_here'
  }
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function getVoices() {
  try {
    const response = await axios.get('https://api.awajdigital.com/api/voices', {
      headers: {
        'Authorization': 'Bearer your_api_token_here'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getVoices();

# Python with requests
import requests

def get_voices():
    url = 'https://api.awajdigital.com/api/voices'
    headers = {
        'Authorization': 'Bearer your_api_token_here'
    }

    try:
        response = requests.get(url, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

get_voices()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/voices';
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "voices": [
    {
      "id": 1,
      "name": "welcome_message",
      "status": "approved",
      "createdAt": "2025-12-01T10:00:00.000Z"
    },
    {
      "id": 2,
      "name": "otp_voice",
      "status": "pending",
      "createdAt": "2025-12-15T14:30:00.000Z"
    },
    {
      "id": 3,
      "name": "promo_announcement",
      "status": "rejected",
      "createdAt": "2025-12-20T09:15:00.000Z"
    }
  ]
}

Voice Status: Voices can have one of the following statuses: pending (under review), approved (ready to use), or rejected (not approved).

GET /api/senders

List Senders

Retrieve a list of all caller sender numbers associated with the authenticated user's account along with their status.

Request Example

curl -X GET https://api.awajdigital.com/api/senders \
  -H "Authorization: Bearer your_api_token_here"

// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/senders', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_token_here'
  }
});

const data = await response.json();
console.log(data);

// Node.js with axios
const axios = require('axios');

async function getSenders() {
  try {
    const response = await axios.get('https://api.awajdigital.com/api/senders', {
      headers: {
        'Authorization': 'Bearer your_api_token_here'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getSenders();

# Python with requests
import requests

def get_senders():
    url = 'https://api.awajdigital.com/api/senders'
    headers = {
        'Authorization': 'Bearer your_api_token_here'
    }

    try:
        response = requests.get(url, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

get_senders()

<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/senders';
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

$result = json_decode($response, true);
print_r($result);
?>

Success Response Example

{
  "success": true,
  "senders": [
    {
      "id": 1,
      "callingNumber": "8801234567890",
      "status": "active"
    },
    {
      "id": 2,
      "callingNumber": "8809876543210",
      "status": "active"
    },
    {
      "id": 3,
      "callingNumber": "8805555555555",
      "status": "inactive"
    }
  ]
}

Sender Status: Senders can have one of the following statuses: active (ready to use) or inactive (temporarily disabled). Only active senders can be used for broadcasts.

Error Responses

The API uses standard HTTP status codes and returns error details in JSON format.

401 Unauthorized

Invalid or missing API token

{
  "success": false,
  "message": "Unauthorized"
}

400 Bad Request - OTP Validation

Voice must have at least one dynamic part with digit mode

{
  "success": false,
  "message": "Voice must have at least one dynamic part with digit mode for OTP broadcast"
}

400 Bad Request - Duplicate Numbers

Duplicate phone numbers found in the request

{
  "success": false,
  "message": "Duplicate phone number found",
  "duplicated_number": "019XXXXXXXX"
}

402 Payment Required

Insufficient balance to process the broadcast

{
  "success": false,
  "message": "Insufficient balance"
}

403 Forbidden

Voice not found, not approved, or sender not active

{
  "success": false,
  "message": "Voice not found or not approved"
}

409 Conflict

Duplicate request - request_id already used within 15 minutes

{
  "success": false,
  "message": "Request already processed"
}

404 Not Found

Broadcast not found or access denied

{
  "success": false,
  "message": "Broadcast not found"
}

500 Internal Server Error

Server error occurred while processing the request

{
  "success": false,
  "message": "Failed to create OTP broadcast"
}