Phone Call (Live)
phone_call_createPlace a live phone call and have a real conversation. The tool stays open for the entire call duration. As the caller speaks, you receive live transcript chunks via progress notifications; when the caller finishes a turn (server emits isFinal: true), an elicitation prompt asks you what the agent should say next. You respond with say (the exact text to speak) and optional endCallAfterSpoken: true to hang up after the line. Returns the full transcript when the call ends. Requires the connecting MCP client to support elicitation — without it, the tool errors out immediately.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Destination phone number in E.164 format. | |
| agentId | No | Required when the API key / OAuth grant is user-bound (no agentId in the auth context, e.g. a master key or a user-consented Anima Connect grant) — picks which of the org's agents places the call. Ignored when the auth is already agent-bound (the bound agent wins; mismatches are rejected with AGENT_MISMATCH). Use agent_list to find valid IDs. | |
| voiceId | No | Optional voice override. Use voice_list for valid IDs; the catalog is multilingual and each entry carries an audio preview. | |
| fromNumber | No | Optional source phone in E.164. Default: the calling agent's primary phone identity. | |
| agentConfig | No | Opt in to the server-side conversation loop. When present (even as `{}`), the Anima API runs the LLM-backed conversation loop on each caller turn and speaks the reply — the MCP tool just records both sides of the transcript and returns it when the call ends. **Required when the connecting MCP client doesn't implement elicitation** (e.g. Claude Code returns `-32600 Elicitation not supported`). Omit ONLY if you have your own bot ready to subscribe to MCP elicitation requests and reply via the `say` field per turn. | |
| firstMessage | Yes | Opening line the agent speaks when the call is answered. Be natural — this is what the human hears first. | |
| maxDurationSec | No | Hard cap on total call duration in seconds. Default 600 (10 min). Max 1800 (30 min). | |
| silenceTimeoutSec | No | If no caller utterance arrives within this many seconds (measured from the last agent utterance), the call hangs up automatically. Default 30. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when `endedReason` is `error` or `elicitation_unsupported` — carries the underlying code+message so callers can distinguish capability gaps from real failures. | |
| callId | Yes | ID of the placed call. `null` if the call ended before the carrier assigned an ID (e.g. WS auth failure or pre-ring termination) — use `endedReason` to understand why. | |
| transcript | Yes | Full transcript with role labels in chronological order. | |
| durationSec | No | Total call duration in seconds. | |
| endedReason | Yes | Why the call ended (hangup, timeout, error, etc.). | |
| latencyTurns | No | Per-turn latency breakdown captured by the API's LatencyTracker. Each entry is a turn; the t_*_ms fields are absolute millisecond timestamps. Diff adjacent marks to compute stage durations — common ones: perceived_latency_ms = t_speak_dispatch_ms - t_caller_speech_end_ms (basic) or t_tts_first_tx_ms - t_caller_speech_end_ms (premium), endpoint_wait_ms = t_final_ms - t_caller_speech_end_ms, ws_round_trip_ms = t_ws_recv_ms - t_ws_send_ms. Omitted if the API didn't send latency data (pre-Wave-3K servers). |