Create Batch Call

Billable - retry unsafe Creates a batch call campaign from a small lead list and starts dialing real phone numbers immediately. This is NOT a read-only action, spends real money, and cannot be undone once calls go out (the campaign itself can be cancelled afterward with update_batch_call_status, but any calls already placed are not). Requires confirm: true — only set this after the user has explicitly approved starting this specific batch, never preemptively. Only suitable for short lists (a few dozen leads at most) — for larger campaigns, tell the user to use the dashboard upload instead. Recommended order: clean_batch_call_names on the name column, then preview_batch_call_leads on the file, resolve any issues with the user, THEN call this. file_base64 must be the base64-encoded content of a CSV or Excel file with a phone_number column (and optionally name/other columns as dynamic variables). agent_version_number is required in practice — omitting it fails with “no outbound phone number found,” since the org’s phone number is bound to a specific agent+version pair, not just the agent. Use get_agent or list_agent_versions first to find the right version_number.

Parameters

Name	Type	Required	Description
`title`	`string`	Yes	Campaign title
`agent_id`	`string`	Yes	The agent ID to use for calls, e.g. agent_abc123
`agent_version_number`	`string`	Yes	Required in practice — the specific published agent version whose bound phone number will be used to dial. Get this from get_agent or list_agent_versions.
`file_name`	`string`	Yes	File name with extension, e.g. leads.csv or leads.xlsx
`file_base64`	`string`	Yes	Base64-encoded content of a small (few dozen rows) CSV/Excel leads file
`starts_at`	`string`	No	ISO 8601 datetime to start calling; omit to start immediately
`calling_hours_start`	`string`	No	HH:mm — earliest time of day to call
`calling_hours_end`	`string`	No	HH:mm — latest time of day to call
`confirm`	`boolean`	Yes	Must be true. Set this only after the user has explicitly approved starting this specific batch call.

Before you call

Connect and initialize the MCP client with OAuth or an API key for the intended workspace.
Provide the required parameters: title, agent_id, agent_version_number, file_name, file_base64, confirm.
Set confirm: true only after the user approves the exact target and action.

Example MCP request

Send tools/call after your client completes MCP initialization. Replace placeholder values with IDs and inputs from your workspace. For object and array parameters, follow the nested requirements in the parameter description instead of treating an empty value as complete.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_batch_call",
    "arguments": {
      "title": "Example resource",
      "agent_id": "agent_abc123",
      "agent_version_number": "1",
      "file_name": "VALUE",
      "file_base64": "BASE64_ENCODED_CSV",
      "confirm": true
    }
  }
}

The server returns one text content block. Parse content[0].text as JSON when the tool succeeds. See MCP responses and errors for the full envelope and failure behavior.

Verify the result

Store the returned resource ID and confirm the response is not marked isError. Call Get Agent to read the affected resource. Verify the call, batch, or purchase state before retrying.

Retry safety

This tool can spend wallet balance or start real calls. After a timeout, inspect the relevant resource before retrying so you do not duplicate the action.

Get Agent: get_agent
List Agent Versions: list_agent_versions
Clean Batch Call Names: clean_batch_call_names
Preview Batch Call Leads: preview_batch_call_leads
Update Batch Call Status: update_batch_call_status
List Batch Calls: list_batch_calls
List Calls In Batch: list_calls_in_batch

Start Here

Tool Reference

Parameters

Before you call

Example MCP request

Verify the result

Retry safety

​Parameters

​Before you call

​Example MCP request

​Verify the result

​Retry safety

​Related MCP tools

​Related guides

Parameters

Before you call

Example MCP request

Verify the result

Retry safety

Related MCP tools

Related guides