> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://agentphone.to/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://agentphone.to/docs/_mcp/server. # Calls > Voice call flows, streaming responses, live transcript streaming, recordings, and call management Voice calls are real-time conversations through your agent's phone numbers. Calls can be inbound (received) or outbound (initiated via API). Each call includes metadata like duration, status, and transcript. You can also [stream transcripts in real time](#stream-transcript-sse) via Server-Sent Events. How calls are handled depends on your agent's **voice mode**. ## Voice modes #### Custom Webhook **`voiceMode: "webhook"`** (default) — Caller speech is transcribed and sent to your webhook as `agent.message` events. Your server controls every response using any LLM, RAG, or custom logic. #### Built-in AI **`voiceMode: "hosted"`** — Calls are handled end-to-end by a built-in LLM using your `systemPrompt`. No webhook or server needed. Switch modes at any time via `PATCH /v1/agents/:id`. The backend updates the voice configuration and number bindings. Test a new call after changing modes. > **Note** > > SMS is always webhook-based regardless of voice mode. ## Call flow (webhook mode) When `voiceMode` is `"webhook"`: ### Caller dials your number The voice engine answers and begins streaming audio. ### Caller speaks Streaming STT transcribes in real-time and detects end of speech. ### Transcript is sent to your webhook We POST the transcript to your webhook with `event: "agent.message"` and `channel: "voice"`, including `recentHistory` for context. ### Your server responds You process the transcript (e.g., send to your LLM) and return a response. We strongly recommend streaming NDJSON — TTS starts speaking on the first chunk. ### TTS speaks the response Each NDJSON chunk is spoken with sub-second latency. No waiting for the full response. ### Conversation continues The caller can interrupt at any time (barge-in). The cycle repeats naturally. ## Call flow (built-in AI mode) When `voiceMode` is `"hosted"`: ### Caller dials your number The AI answers with your `beginMessage` (e.g., "Hello! How can I help?"). ### Caller speaks Streaming STT transcribes in real-time. ### Built-in LLM generates a response The LLM uses your `systemPrompt` to generate a contextual response. ### TTS speaks the response Streaming TTS speaks the response with sub-second latency. ### Conversation continues No server or webhook involved — the platform handles everything. ## Voice capabilities Both modes share the same low-latency engine: | Capability | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | Streaming STT | Real-time speech-to-text transcription | | Streaming TTS | Sub-second text-to-speech synthesis | | Barge-in | Caller can interrupt the agent mid-sentence. Tune with `interruptionSensitivity` | | Backchanneling | Natural conversational cues ("uh-huh", "right"). Toggle with `enableBackchannel` | | Turn detection | Smart end-of-speech detection | | Streaming responses | Return NDJSON to start TTS on the first chunk | | Live transcript streaming | [Stream transcript turns](#stream-transcript-sse) in real time via SSE — works for live and completed calls | | DTMF digit press | Press keypad digits to navigate IVR menus and automated phone systems | | Call recording | Optional add-on — automatically records calls and provides audio URLs | These behaviors are configured per agent: voice, speed, interruption sensitivity, backchanneling, transcription mode, denoising, ambience, language, and more. See [Voice tuning](/docs/documentation/guides/agents#voice-tuning) on the Agents guide for the full set of knobs and recommended defaults. ## Webhook response format For voice webhooks, your server must return a JSON object (`{...}`) telling the agent what to say. Non-object responses (numbers, strings, arrays) are ignored and the caller hears silence. ### Streaming response (recommended) Return `Content-Type: application/x-ndjson` with newline-delimited JSON chunks. TTS starts speaking on the very first chunk while your server continues processing. ``` {"text": "Let me check that for you.", "interim": true} {"text": "Your order #4521 shipped yesterday via FedEx."} ``` Mark interim chunks with `"interim": true` — the final chunk (without `interim`) closes the turn. Use this for tool calls, LLM token forwarding, or any time your response takes more than \~1 second. ### Simple response Return a single JSON object for instant replies where no processing delay is expected. ```json { "text": "How can I help you?" } ``` ### Response fields | Field | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | Text to speak to the caller | | `hangup` | boolean | Set to `true` to end the call after speaking | | `action` | string | `"transfer"` to cold-transfer the call (requires `transferNumber` on the agent), `"hangup"` to end it | | `digits` | string | DTMF digits to press on the keypad (e.g. `"1"`, `"123"`, `"1*#"`). Used to navigate IVR menus and automated phone systems. Aliases: `press_digit`, `dtmf` | | `send_message` | object | Send the call counterparty an SMS during the call. Shape: `{"body": "..."}`. Recipient defaults to the other party on this call; only pass `to` if your account is allowed to text arbitrary numbers. Aliases: `send_sms`, or `{"action": "send_message", "body": "..."}` | | `interim` | boolean | NDJSON only — marks a chunk as interim (TTS speaks it but the turn stays open) | > **Webhook timeout** > > Voice webhook requests have a **30-second default timeout** (configurable from 5–120 seconds per webhook via the `timeout` field). If your server doesn't start responding in time, the request is cancelled and the caller hears silence for that turn. This is especially important when your webhook calls external APIs or runs LLM tool calls — always stream an interim chunk immediately so the caller hears something while you process. ### Example: streaming handler (Python / FastAPI) Install `fastapi` and `uvicorn`, and copy `verify_webhook.py` from [Webhook security](/docs/documentation/guides/webhooks#verification-example-python). Set `AGENTPHONE_WEBHOOK_SECRET`, save as `server.py`, and run `uvicorn server:app --port 3000`. **`server.py`** ```python title="server.py" import json import os from fastapi import FastAPI, Request, Response from fastapi.responses import StreamingResponse from verify_webhook import verify_webhook app = FastAPI() secret = os.environ["AGENTPHONE_WEBHOOK_SECRET"] @app.post("/webhook") async def handle_voice(request: Request): raw_body = await request.body() if not verify_webhook(raw_body, request.headers.get("X-Webhook-Signature"), request.headers.get("X-Webhook-Timestamp"), secret): return Response(status_code=401) try: event = json.loads(raw_body) except (ValueError, UnicodeDecodeError): return Response(status_code=400) if not isinstance(event, dict): return Response(status_code=400) if event.get("event") != "agent.message" or event.get("channel") != "voice": return Response(status_code=200) # Current speech is separate from the recentHistory context. transcript = event.get("data", {}).get("transcript", "hello") async def generate(): yield json.dumps({"text": "Let me check that.", "interim": True}) + "\n" # Replace this demo reply with bounded asynchronous model/tool work. # Include both event.get("recentHistory", []) and transcript as context. yield json.dumps({"text": f"You said: {transcript}"}) + "\n" return StreamingResponse(generate(), media_type="application/x-ndjson") ``` ### Example: streaming handler (Node.js / Express) Start with the [signed Express handler](/docs/documentation/reference/code-examples#expressjs-webhook-handler). In the voice branch, use `res.type("application/x-ndjson")`, write newline-terminated JSON chunks with `res.write()`, and end the response after the final chunk. ### Example: tool-calling handler (Python / Flask) Verify the request and read the current transcript before starting the response. Send an interim chunk, run bounded tool work, then send a final chunk. A tool exception should produce a short spoken fallback. Use a streaming response from your framework and keep request data outside the generator. ### Example: tool-calling handler (Node.js / Express) Use the same sequence with asynchronous tool calls. Avoid synchronous model/network calls on the event loop. One interim chunk does not disable the timeout: subsequent chunks must also arrive within the configured read timeout. See [Code examples](/docs/documentation/reference/code-examples#voice-webhook-with-openai) for the LLM context requirements. ## Troubleshooting voice calls Common issues and how to fix them. ### Caller hears silence after speaking **Your webhook is too slow or not responding.** Voice webhooks have a 30-second default timeout (configurable per webhook from 5–120 seconds). If your server doesn't respond in time, the turn is dropped and the caller hears nothing. **Fix:** Always stream an interim NDJSON chunk immediately (e.g. `{"text": "One moment.", "interim": true}`) before doing any slow work. This buys you time while keeping the caller engaged. Common causes: * LLM tool calls that take too long (external API latency + LLM processing) * Cold starts on serverless platforms (Lambda, Cloud Functions) * Webhook URL is unreachable or returning errors ### Caller hears silence after the greeting **Your webhook isn't configured or isn't returning a valid JSON object.** Voice responses must be a JSON object (`{...}`). Non-object responses (strings, arrays, numbers) are ignored. **Fix:** Verify your webhook is returning `{"text": "..."}`. Use a browser web call or a phone call to verify voice responses. `POST /v1/webhooks/test` tests signed messaging delivery, not the voice response protocol. ### Response is cut off or sounds garbled **You're sending the entire response as a single large chunk.** Long responses in a single chunk can cause TTS delays. **Fix:** Use NDJSON streaming and break responses into natural sentences. Send each sentence as an interim chunk so TTS can start speaking immediately. ### Agent speaks XML or code artifacts **Your LLM is including tool-call markup in its response.** Some LLMs emit `` or similar tags. **Fix:** Strip non-speech content from your LLM output before returning it. AgentPhone removes common patterns automatically, but your webhook should clean responses to be safe. ### Webhook works for SMS but not voice **You're returning a `200 OK` with no body, or a non-JSON response for voice.** SMS webhooks only need a `200` status — voice webhooks must return a JSON object with a `text` field. **Fix:** Check the `channel` field in the webhook payload. For `"voice"`, always return `{"text": "..."}`. For `"sms"`, a `200 OK` is sufficient. --- ## Call recording Call recording is an optional add-on that saves audio recordings of your voice calls. When enabled, completed calls include a `recordingUrl` field with a link to the audio file. | Field | Type | Description | | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `recordingUrl` | string or null | URL to the call recording audio file. Only populated when the recording add-on is enabled. | | `recordingAvailable` | boolean | Whether a recording exists for this call. Can be `true` even when `recordingUrl` is null (recording exists but the add-on is not active). | Recording URLs do not require an API key. Treat them and the call ID as sensitive bearer links; turning off the add-on is not a mechanism for revoking a previously shared URL. Enable recording from the **Billing** page in the dashboard. See [Usage & Billing](/docs/usage#call-recording-add-on) for pricing. > **Note** > > Recordings are captured automatically for all calls while the add-on is active. If you disable the add-on, existing recordings are preserved but `recordingUrl` will be null until you re-enable it. --- ## List calls List all calls for this project. ``` GET /v1/calls ``` ### Query parameters | Parameter | Type | Required | Default | Description | | ----------- | ------- | -------- | ------- | ----------------------------------------------------------- | | `limit` | integer | No | 20 | Number of results to return (max 100) | | `offset` | integer | No | 0 | Number of results to skip (min 0) | | `status` | string | No | — | Filter by status: `completed`, `in-progress`, `failed` | | `direction` | string | No | — | Filter by direction: `inbound`, `outbound`, `web` | | `search` | string | No | — | Search by phone number (matches `fromNumber` or `toNumber`) | ### Example ```bash curl -X GET "https://api.agentphone.ai/v1/calls?limit=10&offset=0" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```json { "data": [ { "id": "call_ghi012", "agentId": "agt_abc123", "phoneNumberId": "num_xyz789", "phoneNumber": "+15551234567", "fromNumber": "+15559876543", "toNumber": "+15551234567", "direction": "inbound", "status": "completed", "startedAt": "2025-01-15T14:00:00Z", "endedAt": "2025-01-15T14:05:30Z", "durationSeconds": 330, "lastTranscriptSnippet": "Thank you for calling, goodbye!", "recordingUrl": "https://recordings.agentphone.ai/call_ghi012.mp3", "recordingAvailable": true } ], "hasMore": false, "total": 1 } ``` ## Get call Get details of a specific call, including its full transcript. ``` GET /v1/calls/{call_id} ``` ### Example ```bash curl -X GET "https://api.agentphone.ai/v1/calls/call_ghi012" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```json { "id": "call_ghi012", "agentId": "agt_abc123", "phoneNumberId": "num_xyz789", "phoneNumber": "+15551234567", "fromNumber": "+15559876543", "toNumber": "+15551234567", "direction": "inbound", "status": "completed", "startedAt": "2025-01-15T14:00:00Z", "endedAt": "2025-01-15T14:05:30Z", "durationSeconds": 330, "recordingUrl": "https://recordings.agentphone.ai/call_ghi012.mp3", "recordingAvailable": true, "transcripts": [ { "id": "tr_001", "transcript": "Hello! Thanks for calling Acme Corp. How can I help you today?", "confidence": 0.95, "response": "Sure! Could you please provide your order number?", "createdAt": "2025-01-15T14:00:05Z" }, { "id": "tr_002", "transcript": "Hi, I'd like to check the status of my order.", "confidence": 0.92, "response": "Of course! Let me look that up for you.", "createdAt": "2025-01-15T14:00:15Z" } ] } ``` ## Stream transcript (SSE) Stream a call's transcript in real time via **Server-Sent Events**. On connect the server replays all existing transcript turns from the database, then streams new turns as they arrive from the voice engine. Works for both **live** and **completed** calls — same URL either way. ``` GET /v1/calls/{call_id}/transcript/stream ``` The response is an SSE stream (`Content-Type: text/event-stream`) with the following event types: | Event | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `connected` | Sent once on connect with call metadata (callId, agentId, direction, etc.) | | `turn` | A transcript turn — either replayed from history or arriving in real time. Contains `role` (`"user"` or `"agent"`), `content`, and `createdAt`. | | `ended` | The call has ended. Contains `callId`, `status`, `endedAt`, and `durationSeconds`. The stream closes after this event. | A `: heartbeat` comment is sent every 15 seconds to keep proxies and load balancers from closing the connection. ### Event payloads **`connected`** ```json { "callId": "call_ghi012", "status": "in-progress", "agentId": "agt_abc123", "agentName": "Support Bot", "direction": "inbound", "fromNumber": "+15559876543", "toNumber": "+15551234567", "startedAt": "2025-01-15T14:00:00Z" } ``` **`turn`** ```json { "role": "user", "content": "I need help with my order.", "createdAt": "2025-01-15T14:00:10Z" } ``` **`ended`** ```json { "callId": "call_ghi012", "status": "completed", "endedAt": "2025-01-15T14:05:30Z", "durationSeconds": 330 } ``` ### Example: curl ```bash curl -N "https://api.agentphone.ai/v1/calls/call_ghi012/transcript/stream" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Example: JavaScript (Node.js / fetch stream) ```javascript const API_KEY = "YOUR_API_KEY"; const callId = "call_ghi012"; const response = await fetch( `https://api.agentphone.ai/v1/calls/${callId}/transcript/stream`, { headers: { Authorization: `Bearer ${API_KEY}` } } ); if (!response.ok) { throw new Error(`Failed to stream transcript: ${response.status}`); } const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; let eventType = null; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const lines = buffer.split("\n"); buffer = lines.pop(); for (const line of lines) { if (line.startsWith("event:")) { eventType = line.slice(6).trim(); } else if (line.startsWith("data:")) { const data = JSON.parse(line.slice(5).trim()); if (eventType === "connected") { console.log(`Connected to call ${data.callId} (${data.status})`); } else if (eventType === "turn") { console.log(`[${data.role}] ${data.content}`); } else if (eventType === "ended") { console.log(`Call ended - ${data.durationSeconds}s`); } } } } ``` ### Example: Python ```python import requests API_KEY = "YOUR_API_KEY" call_id = "call_ghi012" url = f"https://api.agentphone.ai/v1/calls/{call_id}/transcript/stream" headers = {"Authorization": f"Bearer {API_KEY}"} with requests.get(url, headers=headers, stream=True, timeout=(10, 60)) as resp: resp.raise_for_status() event_type = None for line in resp.iter_lines(decode_unicode=True): if line.startswith("event:"): event_type = line[len("event:"):].strip() elif line.startswith("data:"): import json data = json.loads(line[len("data:"):].strip()) if event_type == "turn": print(f"[{data['role']}] {data['content']}") elif event_type == "ended": print(f"Call ended — {data['durationSeconds']}s") break ``` > **Live and completed calls use the same URL** > > For a **live call**, existing turns are replayed first, then the stream stays open and delivers new turns in real time until the call ends. For a **completed call**, all turns are replayed immediately followed by an `ended` event and the stream closes. Your client code doesn't need to differentiate — just handle the events. --- ## Create outbound call Initiate an outbound voice call from one of your agent's phone numbers. An eligible attached number is selected automatically. Set `fromNumberId` to select the caller ID explicitly; SIP-routed and messaging-only numbers are not eligible for this hosted/webhook call route. ``` POST /v1/calls ``` ### Request body | Field | Type | Required | Description | | ----------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agentId` | string | Yes | The agent that will handle the call. An eligible attached number is selected unless `fromNumberId` is provided. | | `toNumber` | string | Yes | The phone number to call (E.164 format, e.g., `"+15559876543"`) | | `initialGreeting` | string or null | No | Optional greeting to speak when the recipient answers | | `voice` | string | No | Voice ID override for this call. Uses the agent's configured voice if omitted. List valid IDs with [`GET /v1/agents/voices`](/docs/documentation/guides/agents#list-available-voices). | | `systemPrompt` | string or null | No | When provided, uses a built-in LLM for the conversation instead of forwarding to your webhook. | | `fromNumberId` | string or null | No | The ID of a specific phone number to use as the caller ID. If omitted, the system selects one of the agent's attached numbers. | ### Example ```bash curl -X POST "https://api.agentphone.ai/v1/calls" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "agt_abc123", "toNumber": "+15559876543", "initialGreeting": "Hi, this is Acme Corp calling about your recent order.", "systemPrompt": "You are a friendly support agent from Acme Corp." }' ``` Outbound calls have separate access and readiness checks. Signup credits alone may not unlock calling; follow a `402` response to resolve the account’s funding requirement. A newly provisioned number can return `409` with `Retry-After` while voice activates. An active call can also cause a per-number `409`, while an account concurrency cap returns `429`. Invalid or unsupported destinations must be corrected rather than retried. ## Web calls Web calls let users talk to your agent directly from a browser, no phone number needed. Use the `agentphone-web-sdk` npm package (version 0.2.0 or later) on the frontend and mint connection details from your backend. **How it works:** 1. Your backend calls `POST /v1/calls/web` with `agentId` to get the call's connection details 2. The access token is short-lived — pass the details to the frontend immediately and connect before `expiresAt` 3. The frontend starts the call with `webClient.startCall({ accessToken, callId, transport, iceServers })` ``` POST /v1/calls/web ``` ### Request body | Field | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `agentId` | string | Yes | The agent to call | | `metadata` | object | No | Arbitrary metadata attached to the call | | `variables` | object | No | Template variables for hosted-mode agents, referenced in the system prompt as `{{var_name}}`. Returns `400` for non-hosted agents. | ### Response | Field | Type | Description | | ------------- | ------ | ---------------------------------------------------------------------------------- | | `id` | string | The AgentPhone call ID — use with the call APIs (transcripts, recording, end call) | | `agentId` | string | The agent handling the call | | `accessToken` | string | Short-lived token for the web SDK | | `callId` | string | The media connection ID — pass to the web SDK; not interchangeable with `id` | | `transport` | string | Connection transport to pass to the web SDK | | `iceServers` | array | ICE servers (including any TURN credentials) to pass to the web SDK | | `expiresAt` | number | Access token expiry as Unix epoch milliseconds — connect before this time | | `status` | string | Initial call status | | `startedAt` | string | Call start time (ISO 8601) | ### Example ```bash curl -X POST "https://api.agentphone.ai/v1/calls/web" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"agentId": "agt_abc123"}' ``` The call direction will be `web` (in addition to `inbound` and `outbound`). ## List calls for number List all calls associated with a specific phone number. ``` GET /v1/numbers/{number_id}/calls ``` ### Example ```bash curl -X GET "https://api.agentphone.ai/v1/numbers/num_xyz789/calls?limit=10" \ -H "Authorization: Bearer YOUR_API_KEY" ```