> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.agentphone.ai/documentation/reference/faq/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.ai/_mcp/server. # FAQ > Frequently asked questions about AgentPhone ## General ### How do I get started? Create a project at [agentphone.ai](https://agentphone.ai) to get your API key, then follow the [Quick Start](/welcome#quick-start) to provision a phone number and configure a webhook. ### What countries are supported? Currently, US and Canadian phone numbers are supported. You can request a specific area code when provisioning. International numbers are coming soon. ### How many phone numbers can I create? Every account starts with **\$5.00 in free credit** — enough to provision a number and start making calls with no credit card required. Phone numbers cost **\$3.00/month** each, and you can provision numbers self-serve up to your account limit (visible in `GET /v1/usage`). Call recording is an optional add-on at **\$5.00/month**. Need more numbers? [Contact us](https://calendar.app.google/kJQSTCyNYTphvCGm7) and we'll increase your limit. ### Can I choose a specific phone number? You can request a preferred area code (US/CA only) using the `areaCode` parameter when provisioning. The exact number is automatically selected from available inventory. ### What happens when I delete a phone number? The number is released back to the carrier pool and cannot be recovered. All message and conversation history is preserved for audit purposes. ### Can I use the same number for multiple agents? No. Each phone number is attached to a single agent. Create separate numbers for different agents. ### My agent has multiple numbers. Which one is used for outbound calls? By default, the first attached number is used. To choose a specific number, pass `fromNumberId` in your `POST /v1/calls` request. Both numbers will still receive inbound calls and SMS independently — each number maintains its own conversation threads. ### What are the different call directions? | Direction | Description | | ---------- | --------------------------------------------------------------- | | `inbound` | Someone called your agent's phone number | | `outbound` | Your agent called someone via `POST /v1/calls` | | `web` | A browser-based call via `POST /v1/calls/web` (no phone number) | ### Do I need 10DLC registration to send SMS? Yes. US carriers require all businesses sending SMS from 10-digit phone numbers to register through 10DLC (10-Digit Long Code). Receiving inbound SMS works immediately — no registration needed. To enable outbound SMS, fill out the [registration form](https://agentphone.ai/register). It takes about 5 minutes and we submit everything to the carriers for you. If you can't figure it out, [schedule a call](https://calendar.app.google/kJQSTCyNYTphvCGm7) and we'll handle the registration for you. Voice calls are not affected. ## WhatsApp ### Why did my WhatsApp message get rejected? Almost always the 24-hour window. Meta only lets you send a free-form WhatsApp message to someone who messaged you in the last 24 hours. Outside that window the send is rejected and you need an approved template. Check `capabilities.whatsappWindowExpiresAt` on `GET /v1/conversations/{id}` before sending, so you can pick a template instead of eating a failure. ### How do I start a WhatsApp conversation with someone? With an approved template. There is no other way, by Meta's design, and it applies to the first message to a new contact as well as a follow-up after the window closes. Create one with `POST /integrations/whatsapp/{connection_id}/templates`, wait for Meta to approve it, then send it with the `template` field on `POST /v1/messages`. ### Who pays for WhatsApp messages? Meta bills your own WhatsApp Business Account directly, using the payment method attached to it. WhatsApp charges do not draw down AgentPhone credits and do not appear in AgentPhone usage. One consequence catches people out: session messages inside the 24-hour window are free, so a WABA with no payment method looks fine until the first template send, which fails with Meta error `131042`. Add a payment method in WhatsApp Manager before you rely on templates. ### Can I use WhatsApp group chats? Not yet. WhatsApp's Groups API requires an Official Business Account, which is a separate application to Meta. ### Do I need 10DLC for WhatsApp? No. 10DLC is a US carrier requirement for SMS. WhatsApp does not touch the cellular network, so it is unaffected. ## Voice ### Can I use voice without a phone number? Yes! Web calls let users talk to your agent directly from the browser — no PSTN phone number required. Call `POST /v1/calls/web` with an `agentId` to get an access token, then pass it to the [AgentPhone Web SDK](https://www.npmjs.com/package/agentphone-web-sdk) on your frontend. Webhooks, transcripts, and `agent.call_ended` events work the same as phone calls. See [Code Examples > Browser Web Call](/documentation/reference/code-examples#browser-web-call). ### What are the two voice modes? * **Webhook** (`voiceMode: "webhook"`) — Caller speech is transcribed and sent to your webhook. You control every response with your own LLM or logic. * **Hosted** (`voiceMode: "hosted"`) — A built-in LLM handles the conversation using your `systemPrompt`. No webhook or server needed. See the [Calls guide](/documentation/guides/calls) for detailed call flows. ### How do I reduce voice latency? Use streaming NDJSON responses. Send an interim chunk like `{"text": "Let me check on that.", "interim": true}` immediately, then stream the real answer. TTS starts speaking on the first chunk — the caller hears natural speech instead of silence. See [Best Practices > Voice Latency](/documentation/reference/best-practices#voice-latency) for more detail. ### Why does my caller hear silence after speaking? Voice webhooks have a **30-second default timeout** (configurable from 5–120 seconds per webhook via the `timeout` field). If your server doesn't begin responding in time, the request is cancelled and the caller hears nothing for that turn. This commonly happens when your webhook runs LLM tool calls (e.g., calendar lookup, database query) that take too long. The fix is to always stream an NDJSON interim chunk like `{"text": "One moment, let me check.", "interim": true}` immediately before doing any slow work. See [Calls > Troubleshooting](/documentation/guides/calls#troubleshooting-voice-calls) for more causes and fixes. ### Can the caller interrupt the agent? Yes. Both voice modes support barge-in — the caller can interrupt mid-sentence. The platform handles interruptions automatically. ### Can I transfer a call to a human? Yes. Set `transferNumber` on your agent (E.164 format, e.g. `+14155551234`) and callers can be cold-transferred mid-call. * **Hosted mode** — The AI decides when to transfer (e.g. when the caller asks to speak with a person). * **Webhook mode** — Your webhook controls it by returning `{"action": "transfer"}` in the voice response. To clear the transfer destination, send `"transferNumber": ""` in the update request. ### Can my agent navigate IVR menus (press 1, press 2)? Yes. Return `{"digits": "1"}` in your voice webhook response to press keypad digits. This sends DTMF tones to navigate automated phone systems. You can press multiple digits at once (e.g. `"123"`) and use `*` or `#`. The field aliases `press_digit` and `dtmf` also work. In hosted mode, the built-in LLM presses digits automatically when prompted by the phone system — no webhook logic required. ### What TTS voices are available? Use `GET /v1/agents/voices` to list all available voices. You can set the voice when creating an agent, updating an agent, or making an outbound call. ### How does call recording work? Call recording is an optional add-on (\$5/month) that captures audio for all voice calls. Enable it from the **Billing** page in the dashboard. When active, completed calls include a `recordingUrl` in the API response. The `recordingAvailable` field tells you whether a recording exists even if the add-on is not currently enabled. See [Calls > Call recording](/documentation/guides/calls#call-recording) for details. ## Webhooks ### How do I test webhooks locally? Use ngrok or localtunnel to expose your local server to the internet, then register the public URL as your webhook. See the [Testing guide](/documentation/reference/testing) for a step-by-step walkthrough. ### What happens if my webhook endpoint is down? Webhooks are automatically retried with exponential backoff — up to 6 attempts over roughly 24 hours (immediate, 5 min, 30 min, 2h, 6h, 12h). Failed deliveries are logged and visible via `GET /v1/webhooks/deliveries`. ### What webhook events are available? | Event | Trigger | Key payload fields | | ------------------ | ------------------------------ | ------------------------------------------------------------------------ | | `agent.message` | SMS/iMessage/MMS received | `channel`, `data.message`, `data.mediaUrl`, `recentHistory` | | `agent.message` | Voice turn transcribed | `channel`, `data.transcript`, `data.confidence`, `recentHistory` | | `agent.reaction` | Someone reacted to an iMessage | `data.reactionType`, `data.messageId`, `data.fromNumber` | | `agent.call_ended` | Voice call ends | `data.callId`, `data.durationSeconds`, `data.transcript`, `data.summary` | ### Can I get the full transcript after a call? Yes, three ways: (1) the `agent.call_ended` webhook includes the complete transcript (not limited by `contextLimit`), (2) call `GET /v1/calls/:id/transcript` at any time, or (3) use `GET /v1/calls/:id/transcript/stream` to replay the full transcript as an SSE stream. ### Can I stream the transcript in real time while a call is happening? Yes. `GET /v1/calls/:id/transcript/stream` opens a Server-Sent Events stream that replays existing turns on connect and then delivers new turns as they happen in real time. The stream sends `connected`, `turn`, and `ended` events. It works for both live and completed calls — same URL. See [Calls > Stream transcript (SSE)](/documentation/guides/calls#stream-transcript-sse) for the full event reference and code examples. ### Can I receive duplicate webhooks? Each event is delivered to exactly one endpoint (the per-agent webhook if configured, otherwise the project default). However, retries can cause the same event to arrive multiple times. Always use the `X-Webhook-ID` header for idempotency. ### How do I verify webhook signatures? Use HMAC-SHA256 with your webhook secret. The signed string is `{timestamp}.{raw_body}`. Always check the timestamp is within 5 minutes to prevent replay attacks. See [Webhooks > Security](/documentation/guides/webhooks#security) for code examples in Python and Node.js. ### What is `conversationState`? Custom metadata you store on a conversation via `PATCH /v1/conversations/:id`. This state is included in every webhook payload, enabling your AI backend to maintain context across messages without managing state yourself. ## Errors & Rate Limits ### What happens if I exceed rate limits? You'll receive a `429 Too Many Requests` response. Endpoint throttles include a `Retry-After` header and are safe to retry after waiting; messaging caps return an error code instead and won't clear on retry. See the [Error Handling guide](/documentation/reference/error-handling). ### How should I handle errors? Check the error response format (most errors return a JSON envelope with `message`, `code`, and `type`; some return a plain `{"detail": "..."}` body). Retry transient errors with exponential backoff on idempotent requests, and confirm whether a failed send actually went through before resending it. See the [Error Handling guide](/documentation/reference/error-handling) for the full reference. ## SDKs & Integrations ### What SDKs are available? Official SDKs for [TypeScript/JavaScript](/documentation/sdks/typescript) (`npm install agentphone`) and [Python](/documentation/sdks/python) (`pip install agentphone`). Both support all API operations. ### What is the MCP server? The AgentPhone MCP server lets AI assistants (Cursor, Claude Desktop, Windsurf) provision numbers, send SMS, and make calls through natural language. See the [MCP guide](/mcp). ### Where do I get my API key? Sign up at [agentphone.ai](https://agentphone.ai) and create an API key from your [project settings](https://agentphone.ai/settings). > Frequently asked questions about AgentPhone