Launch a voice campaign

Start an outbound voice broadcast — plain voice, smart voice, IVR or AI bot.

POSThttps://nextgenpanelstaging.cloudshope.com/api/v1/voice/voiceCampaign

Launches an outbound voice campaign against a voice clip you have already uploaded (voice_file_id). call_type selects the kind of call:

obd_voice_call — a plain recorded message. obd_smartvoice — a message with dynamic, per-recipient variables. obd_ivr — an IVR menu with keypress routing. ai_bot — an AI voice agent.

Recipients come from number (comma-separated numbers; each may be 10 digits, or carry a 91 / +91 prefix or leading 0 — all are normalised to 10 digits, and spaces and hyphens are ignored), an uploaded CSV, or a saved group — chosen with sendTo. max_retry (1–3) with retry_after minutes controls redialling of unanswered calls.

Authentication

Send Authorization: Bearer <token>. An agent token needs the voice create permission; account-owner tokens skip this check.

Body parameters

Name	Type	Required	Description
`campaign_name`	string	Yes	Campaign name, up to 191 characters.
`voice_file_id`	string	Yes	Id of an uploaded voice clip, as a string of digits.
`call_type`	enum	Yes	`obd_voice_call`, `obd_smartvoice`, `obd_ivr` or `ai_bot`.
`sendTo`	enum	Yes	`Numbers`, `csv` or `Group`.
`number`	string	No	Comma-separated numbers (10 digits, optionally with `91` / `+91` / leading `0`). Required when `sendTo` is `Numbers`. Up to 100,000 numbers per campaign.
`groupId`	string	No	Saved group id. Required when `sendTo` is `Group`.
`file`	file	No	The CSV file. Required when `sendTo` is `csv`; multipart requests only.
`csv_number_column`	string	No	Name of the number column in the CSV. Required when `sendTo` is `csv` in a JSON request; defaults to `number` for multipart.
`max_retry`	integer (1–3)	No	How many times to redial an unanswered number.
`retry_after`	integer (minutes, ≤30)	No	Wait between retries. Required with `max_retry`.
`schedulled_at`	string	No	When to start, as IST date/time `YYYY-MM-DD HH:mm:ss`, e.g. `2026-09-25 09:00:00`. Omit to start now.
`cli_number`	string (10 digits)	No	Caller ID to present. Must be a verified number on the account.
`retry_did`	string	No	Caller ID to use for retries.
`callback_url`	string	No	Your endpoint for call-event callbacks.
`callback_event`	string	No	Which call events to send to `callback_url`.
`callback_method`	string	No	HTTP method for the callback.
`var_name`	string	No	Pipe-separated variable names. Used with `obd_smartvoice`.
`var_value`	string	No	Per-recipient values as rows `number,v1,v2\|number,v1,v2`. Used with `obd_smartvoice`.
`crm_entity_type`	enum	No	`lead` or `deal`, with `crm_status_id` and `crm_entity_ids`, to take recipients from CRM.
`crm_workspace_id`	string	No	Push call outcomes to this CRM workspace.

Request

Send as application/json, or as multipart/form-data when sendTo is csv (file in a file field).
retry_after is required whenever max_retry is set.
Night calling (20:00–09:00 IST at the start time) must be enabled on the account, or the campaign is rejected.
Send voice_file_id as a string (e.g. "3391").

curl -X POST https://nextgenpanelstaging.cloudshope.com/api/v1/voice/voiceCampaign \
  -H "Authorization: Bearer cs_live_9f2c…" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "Payment reminder",
    "voice_file_id": "3391",
    "call_type": "obd_voice_call",
    "sendTo": "Numbers",
    "number": "9876543210,9812345678",
    "max_retry": 2,
    "retry_after": 10
  }'

Response

{
  "success": true,
  "id": "cmp_48120",
  "campaignId": 48120,
  "userId": 1,
  "total": 2,
  "status": "Processing",
  "numbers": ["9876543210", "9812345678"],
  "truecaller_verified": false
}

201 — example response

Errors

Status	Type	When
400	`malformed-body`	The JSON body could not be parsed.
400	`campaign-rejected`	The campaign was refused; `detail` has the reason: night calling not enabled, insufficient credits, no valid numbers, more than 100,000 numbers, or an invalid / unverified `cli_number`.
403	`permission-denied`	The agent has no role or no permission to create voice campaigns, or the plan lacks a feature the request uses (scheduling, retry, CSV, groups, IVR, AI bot, smart voice, callbacks).
422	`validation-failed`	A field failed validation. See `errors`. Includes `max_retry` outside 1–3 and `retry_after` above 30.
503	`service-down`	The voice service is switched off.
401	`unauthorized`	The `Authorization` header is missing, malformed or the token is invalid or expired.
403	`forbidden`	The token is valid but the account is not allowed to perform this action.