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. Leads file, in this order of preference: the file argument when the user attached a file in the chat (pass the attachment, never re-encode it); otherwise an upload_id from create_upload_url for any real file; file_text only for a few rows the user typed into the conversation. If the user has not given any leads yet, ask for them and say they can either paste the numbers or attach their CSV/Excel file. Either way the file needs a phone_number column (and optionally name/other columns as dynamic variables). agent_version_number must be a PUBLISHED version; the batch stays on that version even if the agent is published again while it runs. The batch dials from one of the agent’s outbound numbers: pass phone_number_id when the agent has more than one (list_agent_phone_numbers). 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	The specific PUBLISHED agent version the batch runs on — a draft version is rejected. Get this from get_agent or list_agent_versions.
`phone_number_id`	`string`	No	The agent’s outbound number to dial from, e.g. phn_abc123 — required when the agent has more than one (list_agent_phone_numbers)
`file_name`	`string`	No	File name with extension, e.g. leads.csv or leads.xlsx. Required with file_text/file_base64; taken from the upload otherwise.
`file_text`	`string`	No	For rows the user typed into the conversation, or a small CSV/text file (under ~50 KB) the caller can read. Plain text, header row first. Not for a file the user attached in the chat: pass that as `file`. Lead columns are for calling context such as names and appointment details. Never include payment card numbers, bank account numbers, government ID numbers, passwords, health information or biometric data.
`file_base64`	`string`	No	For a small .xlsx (under ~50 KB) the caller can read from disk. Not for a file the user attached in the chat (pass that as `file`), and not for larger files (use create_upload_url).
`upload_id`	`string`	No	For a file on a machine the caller controls that is too large for file_text (over ~50 KB): call create_upload_url with reveal_url: true, upload the bytes with an HTTP PUT from a machine with internet access, then pass the upload_id here. Not for a file the user attached in the chat (pass that as `file`); chat sandboxes without internet access cannot complete the upload.
`file`	`object`	No	The file the user attached in the chat. The host passes it as a download link for the server. Preferred for any attachment, of any size; pass the attachment as is, without opening, converting or encoding it.
`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.

Complete input schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Campaign title"
    },
    "agent_id": {
      "type": "string",
      "description": "The agent ID to use for calls, e.g. agent_abc123"
    },
    "agent_version_number": {
      "type": "string",
      "description": "The specific PUBLISHED agent version the batch runs on — a draft version is rejected. Get this from get_agent or list_agent_versions."
    },
    "phone_number_id": {
      "type": "string",
      "description": "The agent's outbound number to dial from, e.g. phn_abc123 — required when the agent has more than one (list_agent_phone_numbers)"
    },
    "file_name": {
      "type": "string",
      "description": "File name with extension, e.g. leads.csv or leads.xlsx. Required with file_text/file_base64; taken from the upload otherwise."
    },
    "file_text": {
      "type": "string",
      "description": "For rows the user typed into the conversation, or a small CSV/text file (under ~50 KB) the caller can read. Plain text, header row first. Not for a file the user attached in the chat: pass that as `file`. Lead columns are for calling context such as names and appointment details. Never include payment card numbers, bank account numbers, government ID numbers, passwords, health information or biometric data."
    },
    "file_base64": {
      "type": "string",
      "description": "For a small .xlsx (under ~50 KB) the caller can read from disk. Not for a file the user attached in the chat (pass that as `file`), and not for larger files (use create_upload_url)."
    },
    "upload_id": {
      "type": "string",
      "description": "For a file on a machine the caller controls that is too large for file_text (over ~50 KB): call create_upload_url with reveal_url: true, upload the bytes with an HTTP PUT from a machine with internet access, then pass the upload_id here. Not for a file the user attached in the chat (pass that as `file`); chat sandboxes without internet access cannot complete the upload."
    },
    "file": {
      "type": "object",
      "properties": {
        "file_id": {
          "type": "string",
          "description": "Host-side file id"
        },
        "download_url": {
          "type": "string",
          "description": "Short-lived signed URL the host provides for the attached file"
        },
        "file_name": {
          "type": "string"
        },
        "mime_type": {
          "type": "string"
        },
        "size": {
          "type": "number"
        }
      },
      "required": [
        "file_id",
        "download_url"
      ],
      "additionalProperties": false,
      "description": "The file the user attached in the chat. The host passes it as a download link for the server. Preferred for any attachment, of any size; pass the attachment as is, without opening, converting or encoding it."
    },
    "starts_at": {
      "type": "string",
      "description": "ISO 8601 datetime to start calling; omit to start immediately"
    },
    "calling_hours_start": {
      "type": "string",
      "description": "HH:mm — earliest time of day to call"
    },
    "calling_hours_end": {
      "type": "string",
      "description": "HH:mm — latest time of day to call"
    },
    "confirm": {
      "type": "boolean",
      "description": "Must be true. Set this only after the user has explicitly approved starting this specific batch call."
    }
  },
  "required": [
    "title",
    "agent_id",
    "agent_version_number",
    "confirm"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Registered output schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the newly created batch, prefixed batch_"
    },
    "title": {
      "type": "string",
      "description": "The campaign title as created"
    },
    "total_records": {
      "description": "How many leads were imported from the file"
    },
    "dnc_skipped_count": {
      "description": "Leads left out because their number is on the workspace's DNC list"
    },
    "status": {
      "description": "Initial status of the batch"
    },
    "from_number": {
      "description": "The organization phone number the batch dials from, or null"
    },
    "file_source": {
      "type": "string",
      "description": "How the leads file arrived: 'text', 'base64', 'upload' (create_upload_url) or 'attachment' (the chat attachment)"
    }
  },
  "required": [
    "id",
    "title",
    "file_source"
  ],
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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, confirm.
If your OAuth grant covers several workspaces, also pass organization_id with the workspace to act in, from List My Organizations.
Provide one file source: a host attachment, a completed upload_id, or supported inline content. The optional file fields are alternatives; omitting all of them does not submit a file. See MCP file uploads.
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",
      "confirm": true,
      "upload_id": "COMPLETED_UPLOAD_ID"
    }
  }
}

Successful results include structuredContent and a text content block containing the same JSON. Check isError first, then read structuredContent or parse content[0].text. 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 Campaign Status 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 Campaign Status: get_campaign_status
Get Agent: get_agent
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 Agent Versions: list_agent_versions
Create Upload URL: create_upload_url
List Agent Phone Numbers: list_agent_phone_numbers
List Batch Calls: list_batch_calls
List Calls In Batch: list_calls_in_batch

Start Here

Tool Reference

Parameters

Complete input schema

Registered output schema

Before you call

Example MCP request

Verify the result

Retry safety

Parameters

Complete input schema

Registered output schema

Before you call

Example MCP request

Verify the result

Retry safety

Related MCP tools

Related guides