Create batch API
Discover how to create a batch for Bolna Voice AI agent by uploading a CSV file containing user contact numbers and prompt variable details for users.
batch_id. The batch does not start calling until you call POST /batches/{batch_id}/schedule.
CSV format
contact_numberis required — E.164 format- Any other column becomes a
{variable}available in your agent’s prompt and welcome message - The per-call execution stores these columns in
context_details.recipient_data
Example request
Usemultipart/form-data — not JSON.
Split a batch across agent versions
Passversion_split to split the batch’s contacts across 2 to 4 versions of the agent, by percentage:
- Each arm needs a different
agent_version_idof this agent, and a whole-numberweightfrom 1 to 99. The weights must add up to 100. - Every contact is assigned a version when the batch is created. The split is exact: 70/30 of 10 contacts calls 7 on the first version and 3 on the second, in random order. Retries keep the contact’s version.
- Calls outside the batch keep using the live version.
- Every version must use the live version’s telephony provider.
- Batches with a workflow can’t be A/B tested.
version_split returns 400 with a message saying what’s wrong. List all batches and Get batch return the split as version_split, with each version’s version_name. To see which version handled each call, read agent_version_id on the batch’s executions. For every way to A/B test versions, see A/B test agent versions.
Next step: schedule the batch
A created batch is idle until scheduled. CallPOST /batches/{batch_id}/schedule with a scheduled_at timestamp:
Authorizations
Body
List of phone numbers from which the batch calls will be made. Each number must include the country code in E.164 format. Pass multiple values to use multiple originating numbers.
JSON string containing retry configuration for failed calls. See auto-retry documentation for details. Example - {"enabled":true,"max_retries":2,"retry_intervals_minutes":[15,30],"prioritize_retries":true}
URL that Bolna POSTs the batch payload to when the batch finishes processing, and again when all of its executions reach a terminal state. Use it to receive the batch's executions without polling. Must be a valid URL; an invalid value is ignored and no webhook is sent.
"https://your-server.com/batch-webhook"
JSON string that splits the batch's contacts across 2 to 4 versions of the agent for an A/B test. Each arm needs a different agent_version_id that belongs to this agent and isn't deleted, and a whole-number weight from 1 to 99. The weights must add up to 100. Each contact is assigned a version when the batch is created, and its retries keep that version. Calls outside the batch keep using the live version. Every version must use the live version's telephony provider. Not supported on batches with a workflow. Example - {"arms":[{"agent_version_id":"0c6a5e0e-7b8f-4d1a-9f2e-3a4b5c6d7e8f","weight":50},{"agent_version_id":"9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b","weight":50}]}
"{\"arms\":[{\"agent_version_id\":\"0c6a5e0e-7b8f-4d1a-9f2e-3a4b5c6d7e8f\",\"weight\":50},{\"agent_version_id\":\"9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b\",\"weight\":50}]}"

