Create Call

Billable - retry unsafe Places a real outbound phone call using one of the organization’s agents. This is NOT a read-only action: it dials an actual phone number immediately and deducts from the organization’s billing wallet on success. Only call this after the user has explicitly confirmed the phone number and intent — never as a guess or a way to “check” something. Requires the organization’s account verification (completed in the dashboard) and sufficient wallet balance; fails with a clear error otherwise. Returns the new call’s ID (e.g. call_abc123), which can be passed to get_call to check on its status afterward.

Parameters

Name	Type	Required	Description
`phone_number`	`string`	Yes	Number to call, including country code, e.g. +911234567890
`agent_id`	`string`	Yes	Agent ID to place the call, e.g. agent_abc123
`agent_version_number`	`number`	No	Specific published agent version to use. Defaults to the latest published version if omitted.
`phone_number_id`	`string`	No	The agent’s outbound number to call from, e.g. phn_abc123 — required when the agent has more than one (list_agent_phone_numbers)
`metadata`	`object (free-form)`	No	Context made available to the agent during the call for personalization, e.g. {“customer_name”: “John Doe”}. Never include payment card numbers, bank account numbers, government ID numbers, passwords, health information or biometric data.
`notes`	`object (free-form)`	No	Optional notes stored on the resulting call log. At most 15 top-level keys. Never include payment card numbers, bank account numbers, government ID numbers, passwords, health information or biometric data.

Complete input schema

{
  "type": "object",
  "properties": {
    "phone_number": {
      "type": "string",
      "description": "Number to call, including country code, e.g. +911234567890"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent ID to place the call, e.g. agent_abc123"
    },
    "agent_version_number": {
      "type": "number",
      "description": "Specific published agent version to use. Defaults to the latest published version if omitted."
    },
    "phone_number_id": {
      "type": "string",
      "description": "The agent's outbound number to call from, e.g. phn_abc123 — required when the agent has more than one (list_agent_phone_numbers)"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Context made available to the agent during the call for personalization, e.g. {\"customer_name\": \"John Doe\"}. Never include payment card numbers, bank account numbers, government ID numbers, passwords, health information or biometric data."
    },
    "notes": {
      "type": "object",
      "additionalProperties": {},
      "description": "Optional notes stored on the resulting call log. At most 15 top-level keys. Never include payment card numbers, bank account numbers, government ID numbers, passwords, health information or biometric data."
    }
  },
  "required": [
    "phone_number",
    "agent_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Registered output schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "ID of the newly created call, prefixed call_ — pass to get_call to check its status"
    }
  },
  "required": [
    "call_id"
  ],
  "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: phone_number, agent_id.
If your OAuth grant covers several workspaces, also pass organization_id with the workspace to act in, from List My Organizations.
Confirm the exact target and intended effect with the user before calling.

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_call",
    "arguments": {
      "phone_number": "+919876543210",
      "agent_id": "agent_abc123"
    }
  }
}

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 Call 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 Call: get_call
List Agent Phone Numbers: list_agent_phone_numbers
List Calls: list_calls
Get Call Details: get_call_details

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