Calls

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 via Server-Sent Events.

How calls are handled depends on your agent’s voice mode.

Voice modes

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.

Call flow (webhook mode)

When voiceMode is "webhook":

Call flow (built-in AI mode)

When voiceMode is "hosted":

Voice capabilities

Both modes share the same low-latency engine:

These behaviors are configured per agent: voice, speed, interruption sensitivity, backchanneling, transcription mode, denoising, ambience, language, and more. See 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.

{ "text": "How can I help you?" }

Response fields

Example: streaming handler (Python / FastAPI)

Install fastapi and uvicorn, and copy verify_webhook.py from Webhook security. Set AGENTPHONE_WEBHOOK_SECRET, save as server.py, and run uvicorn server:app --port 3000.

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. 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 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 <function_call> 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.

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 for pricing.

List calls

List all calls for this project.

GET /v1/calls

Query parameters

Example

curl -X GET "https://api.agentphone.ai/v1/calls?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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

curl -X GET "https://api.agentphone.ai/v1/calls/call_ghi012" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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:

A : heartbeat comment is sent every 15 seconds to keep proxies and load balancers from closing the connection.

Event payloads

connected

{
  "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

{
  "role": "user",
  "content": "I need help with my order.",
  "createdAt": "2025-01-15T14:00:10Z"
}

ended

{
  "callId": "call_ghi012",
  "status": "completed",
  "endedAt": "2025-01-15T14:05:30Z",
  "durationSeconds": 330
}

Example: curl

curl -N "https://api.agentphone.ai/v1/calls/call_ghi012/transcript/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: JavaScript (Node.js / fetch stream)

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

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

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

Example

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

Response

Example

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

curl -X GET "https://api.agentphone.ai/v1/numbers/num_xyz789/calls?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"