# Direct TTS Broadcast

`POST /api/broadcasts/direct-tts`

Send a broadcast from plain text — the text is converted to speech (AI TTS) and played to each recipient. Processing is asynchronous: the API accepts the request, generates the audio in the background, then queues the calls.

:::caution[Permission required]
This endpoint requires both the direct-broadcast and AI TTS permissions on your account. Contact support to enable them. Requests without them receive `403`.
:::

## 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. |
| sender | string | Yes | Your active caller sender number (1-20 chars) |
| phone_numbers | array | Yes | Array of Bangladeshi phone numbers (01XXXXXXXXX format, 1-999 numbers). No duplicates allowed. |
| texts | array | Yes | Text strings (1-10, max 5000 chars each by default), converted to speech and played in order. |
| voice | string | No | `male` or `female` (default: provider default voice) |
| language_code | string | No | Language code, e.g. `bn-BD` (max 10 chars; default: account/provider default) |
| metadata | object | No | Custom data to associate with the broadcast. |

## Request Example

```bash
curl -X POST https://api.awajdigital.com/api/broadcasts/direct-tts \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "unique_direct_tts_001",
    "sender": "8801234567890",
    "phone_numbers": ["019XXXXXXXX", "018XXXXXXXX"],
    "texts": ["আসসালামু আলাইকুম। আগামীকাল আমাদের অফিস বন্ধ থাকবে।"],
    "voice": "female",
    "language_code": "bn-BD",
    "metadata": { "campaign_id": "tts_broadcast_2026" }
  }'
```

```javascript
// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/broadcasts/direct-tts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    request_id: 'unique_direct_tts_001',
    sender: '8801234567890',
    phone_numbers: ['019XXXXXXXX', '018XXXXXXXX'],
    texts: ['আসসালামু আলাইকুম। আগামীকাল আমাদের অফিস বন্ধ থাকবে।'],
    voice: 'female',
    language_code: 'bn-BD',
    metadata: { campaign_id: 'tts_broadcast_2026' }
  })
});

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

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

async function sendDirectTtsBroadcast() {
  try {
    const response = await axios.post('https://api.awajdigital.com/api/broadcasts/direct-tts', {
      request_id: 'unique_direct_tts_001',
      sender: '8801234567890',
      phone_numbers: ['019XXXXXXXX', '018XXXXXXXX'],
      texts: ['আসসালামু আলাইকুম। আগামীকাল আমাদের অফিস বন্ধ থাকবে।'],
      voice: 'female',
      language_code: 'bn-BD',
      metadata: { campaign_id: 'tts_broadcast_2026' }
    }, {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      }
    });

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

sendDirectTtsBroadcast();
```

```python
# Python with requests
import requests

def send_direct_tts_broadcast():
    url = 'https://api.awajdigital.com/api/broadcasts/direct-tts'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
    data = {
        'request_id': 'unique_direct_tts_001',
        'sender': '8801234567890',
        'phone_numbers': ['019XXXXXXXX', '018XXXXXXXX'],
        'texts': ['আসসালামু আলাইকুম। আগামীকাল আমাদের অফিস বন্ধ থাকবে।'],
        'voice': 'female',
        'language_code': 'bn-BD',
        'metadata': { 'campaign_id': 'tts_broadcast_2026' }
    }

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

send_direct_tts_broadcast()
```

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

$data = [
    'request_id' => 'unique_direct_tts_001',
    'sender' => '8801234567890',
    'phone_numbers' => ['019XXXXXXXX', '018XXXXXXXX'],
    'texts' => ['আসসালামু আলাইকুম। আগামীকাল আমাদের অফিস বন্ধ থাকবে।'],
    'voice' => 'female',
    'language_code' => 'bn-BD',
    'metadata' => ['campaign_id' => 'tts_broadcast_2026']
];

$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,
    'Accept: application/json',
    '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

```json
{
  "success": true,
  "message": "TTS broadcast request accepted, processing started",
  "data": {
    "request_id": "unique_direct_tts_001"
  }
}
```

The `202` response means the request was accepted, not that calls have started. Poll [Get Direct TTS Broadcast Status](/api-docs/broadcasts/direct-tts-status) with the same `request_id` until it is `completed`, then poll [Get Broadcast Result](/api-docs/broadcasts/result) for per-number call outcomes.

## Error Responses

| Status | Description |
| --- | --- |
| 400 | Duplicate phone numbers in request |
| 402 | Insufficient account balance |
| 403 | Required permissions not enabled, or sender not found / not active |
| 422 | Invalid request parameters (`request_id` length, phone format, array size, text length) |
| 429 | Rate limited — max 1 request per second per account |

:::note
Re-sending the same `request_id` returns `202` with the original result (idempotent). If the stored request failed, the retry returns `500` — use a new `request_id` instead.

Call minutes are billed per your pulse rate, same as any broadcast. TTS generation cost is tracked internally and is not charged separately.
:::