Send Voice Campaign

Endpoint

POST https://wa20.nuke.co.in/v6/api/v1/voice/send

Authentication

Required. Send a JWT in the header:

Authorization: Bearer <jwt_token>

Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer <jwt_token>`

Body Parameters

Parameter	Type	Required	Description
`broadcast_name`	string	Yes	Any label for this campaign.
`message`	string	Yes	The text to be converted to speech and played on the call. Max 5000 characters.
`language`	string	No	Language for TTS. Accepts `"hindi"`, `"hi"`, `"english"`, `"en"`, or any 2-letter language code. Defaults to English if not recognized.
`contacts`	array of strings	Yes	Phone numbers to call, 10–16 digits each (no country-code symbols like `+`). Duplicates are removed automatically; invalid numbers are silently dropped.
`dtmf_flow`	object	No	IVR configuration for call transfers. Use this to map keypad digits (`1`, `2`, etc.) to target forwarding numbers.
`retries`	number	No	Number of retry attempts if a call isn't answered.
`retry_interval`	number	No	Seconds to wait between retries. Must be one of: `5, 10, 30, 60, 180, 300`.

Note: caller_id is currently fixed to a single hardcoded number on the backend — it isn't a parameter you need to send.

Payload Examples

1. Simple Call (Standard TTS)

A normal voice blast campaign where the recipient hears your message.

JSON Payload

{
  "broadcast_name": "test",
  "message": "नमस्कार! यह आपके लिए एक महत्वपूर्ण सूचना है। कृपया इस संदेश को अंत तक ध्यानपूर्वक सुनें।",
  "language": "hindi",
  "contacts": ["91xyz", "91abc"],
  "retries": 1,
  "retry_interval": 10
}

cURL Example

curl --location 'https://wa20.nuke.co.in/v6/api/v1/voice/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...' \
--data '{
  "broadcast_name": "test",
  "message": "नमस्कार! यह आपके लिए एक महत्वपूर्ण सूचना है।",
  "language": "hindi",
  "contacts": ["91xyz", "91abc"],
  "retries": 1,
  "retry_interval": 10
}'

2. Call Forwarding (DTMF / IVR)

Enable call forwarding by specifying a dtmf_flow object. The user will hear the message, and pressing a matching digit on their keypad will forward the call to the specified number.

JSON Payload

{
  "broadcast_name": "ivr_campaign",
  "message": "Welcome. Press 1 to speak to our sales team. Press 2 for support.",
  "language": "english",
  "contacts": ["91xyz", "91abc"],
  "dtmf_flow": {
    "rows": [
      {
        "digit": "1",
        "number": "91sales123",
        "fallback_numbers": ["91sales456","91demo234"] //upto 3max
      },
      {
        "digit": "2",
        "number": "91support123"
      }
    ]
  }
}

Note: fallback_numbers is optional and is used if the primary number does not answer.

cURL Example

curl --location 'https://wa20.nuke.co.in/v6/api/v1/voice/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...' \
--data '{
  "broadcast_name": "ivr_campaign",
  "message": "Welcome. Press 1 to speak to our sales team. Press 2 for support.",
  "language": "english",
  "contacts": ["91xyz", "91abc"],
  "dtmf_flow": {
    "rows": [
      {
        "digit": "1",
        "number": "91sales123",
        "fallback_numbers": ["91sales456","91demo234"]
      },
      {
        "digit": "2",
        "number": "91support123"
      }
    ]
  }
}'

Example Response — 200 OK

{
  "request_id": "VCAMP_20260728_9F3A21B0",
  "campaign_name": "test",
  "contacts": 1,
  "counts_per_contact": 3,
  "credits_deducted": 3,
  "ivr_enabled": true,
  "status": "Pending for Verification",
  "audio_url": "https://wa20.nuke.co.in/v6/api/uploads/2026/07/28/audio/9f3a21b0....mp3"
}

Response Fields

Field	Description
`request_id`	Unique campaign ID, in the format `VCAMP_YYYYMMDD_XXXXXXXX`. Use this to track the campaign.
`campaign_name`	Same as the `broadcast_name` you sent.
`contacts`	Number of valid, deduplicated phone numbers the call was queued for.
`counts_per_contact`	Credits charged per contact — calculated from audio duration (1 credit per 15 seconds, rounded up).
`credits_deducted`	Total `voice_credits` deducted (`counts_per_contact` × `contacts`).
`ivr_enabled`	`true` if a DTMF/callback flow was attached to this campaign.
`status`	Initial campaign status — always `"Pending for Verification"` right after submission.
`audio_url`	converted your message into audio.

How Credits Are Calculated

Credits are charged in 15-second blocks per contact — any part of a block counts as a full block (rounded up).

Audio Duration	Credits per contact
Up to 0:15	1
0:16 – 0:30	2
0:31 – 0:45	3
0:46 – 1:00	4
1:01 – 1:15	5
1:16 – 1:30	6
1:31 – 1:45	7
Up to 2:00 (max)	8

Maximum audio duration is 120 seconds (2:00) — longer messages are rejected.
credits_deducted = counts_per_contact × number of valid contacts, taken from your voice_credits balance.
If your balance is insufficient, the request fails before any calls are queued.

Validation Rules

broadcast_name is required.
message is required and cannot exceed 5000 characters.
contacts must be a non-empty array; each number must be 10–16 digits (after removing symbols), duplicates are removed automatically.
retry_interval, if given, must be one of 5, 10, 30, 60, 180, 300 seconds.
dtmf_flow (if provided) must be a valid object containing a rows array with digit and number properties.

Error Responses

These are returned as validation/processing errors before a call is queued:

Message	Reason
`broadcast_name is required`	Missing broadcast name.
`Either audio_file_id or message is required`	`message` missing.
`Text for voice message cannot exceed 5000 characters.`	`message` too long.
`Provide an array of phone numbers in 'contacts'`	`contacts` missing or empty.
`retry_interval must be one of: 5, 10, 30, 60, 180, 300`	Invalid `retry_interval` value.
`No valid numbers were found in contacts.`	None of the given numbers passed the 10–16 digit format check.
`Audio duration cannot exceed 120 seconds`	The generated speech audio is longer than the 120-second limit — shorten your message.
`Insufficient credits. Required: X, Available: Y`	Not enough `voice_credits` balance.
`dtmf_flow is not valid JSON`	The provided `dtmf_flow` data was structured incorrectly.

Notes

The text you send in message is converted to speech automatically, and the generated audio URL is returned as audio_url.
For Hindi/English messages, long text is automatically split at sentence boundaries and reassembled to keep the audio natural — no action needed on your end besides sending the full message.
Campaign status starts as "Pending" — check back or use your delivery report for the final per-contact call outcome.