Voice Broadcast with Text to Speech

GET POST /api/voice/v1/broadcast/tts

Sends a broadcast whose audio is spoken from text. Two modes — send exactly one: (1) template_id + variables: an approved TTS template from your account, with a value for each of its variables; open to every voice.broadcast key. (2) text: free text; only for keys with audio auto-approval. Asynchronous: the response is 202 "preparing" — poll Broadcast with TTS Status. Every different message is a new audio: it costs TTS credits and takes a few seconds (up to about 30 for some voices) before dialling starts.

Parameters

Request example

curl -X POST "https://cpaas.studio/api/voice/v1/broadcast/tts" \
  -H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b1e0c4a-2f7d-4e59-9a61-3c5d2e7f9b10" \
  -d '{
    "did": "9876500000",
    "numbers": ["9876543210", "9876543211"],
    "template_id": "TPL7K2M9QX4WQ",
    "variables": {"customer_name": "Anil", "amount": "1500"},
    "gender": "female",
    "reference": "bill-4471"
  }'

<?php
$ch = curl_init('https://cpaas.studio/api/voice/v1/broadcast/tts');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Idempotency-Key: 8b1e0c4a-2f7d-4e59-9a61-3c5d2e7f9b10',
        'Content-Type: application/json',
    ],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'did' => '9876500000',
        'numbers' => ['9876543210', '9876543211'],
        'template_id' => 'TPL7K2M9QX4WQ',
        'variables' => ['customer_name' => 'Anil', 'amount' => '1500'],
        'gender' => 'female',
        'reference' => 'bill-4471',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

# One number, its own values — e.g. an OTP. Each different code is a new audio.
curl "https://cpaas.studio/api/voice/v1/broadcast/tts?did=9876500000&numbers=9876543210&template_id=TPL3OTP8K2M4Q&variables[code]=4%208%202%201&gender=female" \
  -H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Free text — keys with audio auto-approval only.
curl -X POST "https://cpaas.studio/api/voice/v1/broadcast/tts" \
  -H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d "did=9876500000" \
  -d "numbers=9876543210,9876543211" \
  -d "text=Your order 4471 has been shipped. Thank you for shopping with us." \
  -d "language=en" -d "gender=female" -d "speed=1" \
  -d "reference=order-4471"

Success response (data)

{
    "id": "TTB4M8Q2ZK7RX",
    "reference": "bill-4471",
    "status": "preparing",
    "tts": {
        "language": "en",
        "gender": "female",
        "speed": 1
    },
    "credits_estimated": {
        "voice.broadcast": 2,
        "voice.tts": 7
    },
    "template": {
        "id": "TPL7K2M9QX4WQ",
        "name": "Bill reminder"
    },
    "audio": null,
    "items": {
        "total": 1,
        "ready": 0,
        "failed": 0
    },
    "broadcast": null,
    "error": null,
    "created_at": "2026-10-05T13:10:00+00:00",
    "completed_at": null
}

Errors

Notes

• Asynchronous: 202 means accepted and preparing — the broadcast does not exist yet. Poll Broadcast with TTS Status with the returned id (or your reference).
• Every different message is a new audio: it costs TTS credits (per word) and takes a few seconds before dialling — about 1–2 s on hosted voices, up to about 30 s on some Indian-language voices. Sending exactly the same message again (same text/values, language, gender, speed) reuses the audio with no TTS charge.
• OTP and other per-number messages: send one request per number with its own variables. Every code is a new audio, so expect the TTS charge and the delay on each one.
• Template mode: template is {id, name} and audio is always null — the audio is internal. Free text: template is null and audio is {audio_uid, reused}; the audio stays in your Audio Library (type broadcast).
• Once status is "submitted", the response contains the broadcast (same shape as Voice Broadcast) — use its id with Voice Broadcast Number Status for per-number results. A number whose audio could not be prepared shows status no_audio there: not dialled, not charged.
• If preparation fails, status is "failed" with error.code: TTS_GENERATION_FAILED (no TTS credits charged), AUDIO_DELIVERY_FAILED, TTS_UNAVAILABLE, TTS_TEMPLATE_NOT_APPROVED (template edited while preparing), BILLING_INSUFFICIENT_CREDITS, BCAST_DID_INVALID, etc. Send a new request to try again.
• Credits are checked up front for both voice.tts (per word) and voice.broadcast (per number), and charged as they are used — TTS when the audio is made, broadcast per chunk as calls go out.