> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Call

> Use the create_call MCP tool on the DialNexa remote MCP server.

<span data-api-safety-label="billable"><Badge color="yellow" size="sm" shape="pill">Billable - retry unsafe</Badge></span>

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 org to have verified KYC 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.                  |
| `metadata`             | `object (free-form)` | Yes      | Context made available to the agent during the call for personalization, e.g. \{"customer\_name": "John Doe"}. |
| `notes`                | `object (free-form)` | No       | Optional notes stored on the resulting call log. At most 15 top-level keys.                                    |

## 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`, `metadata`.
* 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.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_call",
    "arguments": {
      "phone_number": "+919876543210",
      "agent_id": "agent_abc123",
      "metadata": {}
    }
  }
}
```

The server returns one text content block. Parse `content[0].text` as JSON when the tool succeeds. See [MCP responses and errors](/docs/mcp-tools/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](/docs/mcp-tools/calls/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.

## Related MCP tools

* [Get Call](/docs/mcp-tools/calls/get-call): `get_call`
* [List Calls](/docs/mcp-tools/calls/list-calls): `list_calls`

## Related guides

* [Connect to the DialNexa MCP server](/docs/mcp-tools/overview)
* [Calls MCP tools](/docs/mcp-tools/calls/overview)
* [MCP responses and errors](/docs/mcp-tools/errors)