FAQ | AgentPhone

General

How do I get started?

Create a project at agentphone.to to get your API key, then follow the 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 gets 1 free phone number (includes 1,000 SMS/month and 250 voice minutes/month). To add more lines, schedule a call and we’ll set you up at $8 per additional line per month.

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

Voice

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 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 for more detail.

Can the caller interrupt the agent?

Yes. Both voice modes support barge-in — the caller can interrupt mid-sentence. The platform handles interruptions automatically.

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.

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

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 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 with a Retry-After header. Implement exponential backoff when retrying. See the Error Handling guide.

How should I handle errors?

Check the error response format (all errors return a consistent JSON structure with message, code, type, and optional details). Retry transient errors (429, 500, 502) with exponential backoff. See the Error Handling guide for the full reference.

SDKs & Integrations

What SDKs are available?

Official SDKs for TypeScript/JavaScript (npm install agentphone) and 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.