# Agent Phone

> Phone numbers for AI agents. Give your AI a real phone number.

Agent Phone is an API platform that gives AI agents phone identities. Developers use Agent Phone to provision real US/Canadian phone numbers and connect them to AI agents for SMS and voice communication.

## Key Features

- **Instant Phone Numbers**: Provision US and Canadian phone numbers via API in seconds
- **Two Voice Modes**: Built-in AI (zero infrastructure) or Custom Webhook (full control)
- **Unified Webhook**: One `agent.message` event for both SMS and voice, with full conversation history
- **Per-Agent Webhooks**: Route events to different endpoints per agent (overrides the project default)
- **Stateful Conversations**: Messages and calls auto-thread into durable conversation history with custom metadata
- **Voice Abstraction**: Simple JSON transcript-to-response loop — no TwiML or WebSocket management
- **Production-Grade**: HMAC+timestamp signatures, idempotency headers, exponential backoff retries
- **MCP Server**: Model Context Protocol support for tool-using AI agents (Cursor, Claude Code, Windsurf)

## Voice Modes

Every agent has a `voiceMode` that controls how voice calls are handled:

### Built-in AI (`"hosted"`)
- Calls are handled end-to-end by an AI using your system prompt
- No server or webhook needed — works immediately
- Provide `systemPrompt` (required), `beginMessage` (optional greeting), and `voice` (TTS voice ID)
- Best for: quick prototyping, simple conversational agents

### Custom Webhook (`"webhook"`)
- Caller speech is transcribed and sent to your webhook as `agent.message` events
- Your server controls every response — use any LLM, RAG, or custom logic
- Requires a webhook endpoint configured for your project or agent
- Best for: production agents that need tool use, database access, or custom business logic

### Switching Modes
Switch at any time via `PATCH /v1/agents/:id` with `{"voiceMode": "hosted", "systemPrompt": "..."}` or `{"voiceMode": "webhook"}`. The backend automatically re-provisions voice infrastructure and rebinds phone numbers with no downtime.

Note: SMS is always webhook-based regardless of voice mode.

## Agent Authentication

Two paths to get an API key — agents should prefer the self-signup flow.

### For agents (recommended)

The agent signs itself up via a two-step API flow. No human web signup needed.

1. `POST /v0/agent/sign-up` with `{"human_email": "...", "agent_name": "..."}` — sends a 6-digit OTP to the human's email, returns a `verification_id`. Nothing is provisioned yet.
2. Agent asks the human for the code.
3. `POST /v0/agent/verify` with `{"verification_id": "...", "otp_code": "..."}` — atomically creates account + phone number + starter agent + API key. Returns `{"account_id", "agent_id", "number_id", "phone_number", "api_key"}`.
4. (Recommended) Ask your human for their phone number and call them with `POST /v1/calls` to introduce yourself live — the wow moment. Their phone rings within seconds and you talk to them autonomously. No webhook needed.

Full details and curl examples: https://agentphone.ai/skills.md

### For humans

Sign up at https://agentphone.ai/dashboard and generate an API key from settings. No credit card required.

### Using the key

All API requests require the API key as a Bearer token: `Authorization: Bearer YOUR_API_KEY`. Base URL: https://api.agentphone.ai

API keys have full access to your account's resources (agents, numbers, calls, messages, webhooks). There is no separate sandbox — new accounts get $5.00 in free credit which covers the first month of one phone number plus some SMS and voice usage, so you can test in production safely.

## MCP Integration

AgentPhone exposes a Model Context Protocol server with 26 tools for managing phone numbers, SMS, voice calls, agents, conversations, and webhooks.

**Hosted MCP endpoint (Streamable HTTP):**
https://mcp.agentphone.ai/mcp

Pass your API key via the Authorization header. Compatible with any MCP client that supports Streamable HTTP transport.

**Local MCP (stdio):**

```json
{
  "mcpServers": {
    "agentphone": {
      "command": "npx",
      "args": ["-y", "agentphone-mcp"],
      "env": {
        "AGENTPHONE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Claude Code: `claude plugin add agentphone`

## Pricing

Pay-as-you-go. No monthly subscriptions or per-month allotments — you pay only for what you use.

- **Signup bonus**: $5.00 in free credit for new accounts (covers the first month of one number plus some usage)
- **Phone numbers**: $3.00 per number per month
- **SMS**: $0.02 per outbound message
- **Voice, webhook mode**: $0.13 per minute
- **Voice, hosted mode**: $0.22 per minute
- **Call recording** (optional add-on): $5.00 per month

Balance is maintained via auto-recharge through Stripe. Unpaid numbers enter a 30-day grace period before being released. Self-serve accounts can hold up to 10 numbers — contact us for more.

## API Base URL

https://api.agentphone.ai

## Authentication

All API requests require a Bearer token: `Authorization: Bearer YOUR_API_KEY`

## API Endpoints

### Agents

- `POST /v1/agents` — Create agent. Body: `name` (required), `description`, `voiceMode` ("webhook" | "hosted", default "webhook"), `systemPrompt` (required if hosted), `beginMessage`, `voice`
- `GET /v1/agents` — List agents. Query: `limit`, `offset`
- `GET /v1/agents/:id` — Get agent with attached numbers
- `PATCH /v1/agents/:id` — Update agent. Body: `name`, `description`, `voiceMode`, `systemPrompt`, `beginMessage`, `voice` (all optional). Switching `voiceMode` automatically re-provisions voice infrastructure
- `DELETE /v1/agents/:id` — Delete agent (preserves numbers, conversations, calls)
- `GET /v1/agents/voices` — List available TTS voices
- `POST /v1/agents/:id/numbers` — Attach number to agent. Body: `numberId`
- `GET /v1/agents/:id/conversations` — List agent conversations
- `GET /v1/agents/:id/calls` — List agent calls

### Phone Numbers

- `POST /v1/numbers` — Provision number. Body: `country` (default "US"), `areaCode`, `agentId`
- `GET /v1/numbers` — List numbers. Query: `limit`, `offset`
- `GET /v1/numbers/:id/messages` — List messages. Query: `limit`, `before`, `after`
- `GET /v1/numbers/:id/calls` — List calls for number
- `DELETE /v1/numbers/:id` — Release number (irreversible)

### Conversations

- `GET /v1/conversations` — List conversations
- `GET /v1/conversations/:id` — Get conversation with messages
- `GET /v1/conversations/:id/messages` — Paginated messages
- `PATCH /v1/conversations/:id` — Update metadata. Body: `metadata` (JSON object)

### Voice Calls

- `GET /v1/calls` — List calls with transcripts
- `GET /v1/calls/:id` — Get call with transcripts
- `POST /v1/calls` — Start outbound call. Body: `agentId` (required), `toNumber` (required), `fromNumberId` (optional — pick which of the agent's numbers to call from; defaults to first), `initialGreeting`, `voice`, `systemPrompt`

### Webhooks

Events are delivered to exactly one endpoint per event: the per-agent webhook if configured, otherwise the project default. No duplicates.

- `POST /v1/webhooks` — Create/update project default webhook. Body: `url`, `contextLimit` (0-50)
- `GET /v1/webhooks` — Get project default webhook config
- `DELETE /v1/webhooks` — Remove project default webhook
- `GET /v1/webhooks/deliveries` — View delivery history (all webhooks)
- `POST /v1/webhooks/test` — Send test webhook

### Per-Agent Webhooks (Optional Override)

When set, the agent's events go here instead of the project default.

- `POST /v1/agents/:id/webhook` — Create/update agent webhook (overrides project default)
- `GET /v1/agents/:id/webhook` — Get agent webhook config
- `DELETE /v1/agents/:id/webhook` — Remove agent webhook (reverts to project default)
- `GET /v1/agents/:id/webhook/deliveries` — View agent webhook delivery history
- `POST /v1/agents/:id/webhook/test` — Send test webhook

## Webhook Events

All inbound messages (SMS and voice) are delivered as `agent.message` events:

```json
{
  "event": "agent.message",
  "channel": "sms | voice",
  "agentId": "agent_123",
  "data": { "conversationId": "...", "from": "+1...", "to": "+1...", "message": "..." },
  "conversationState": { ... },
  "recentHistory": [ ... ]
}
```

Voice webhook responses: `{"text": "...", "hangup": false}`

Streaming voice responses (for tool calls / LLM token streaming):
Return `Content-Type: application/x-ndjson` with newline-delimited JSON chunks.
Mark interim chunks with `"interim": true` — TTS starts immediately on the first chunk.
```
{"text": "Let me check that for you.", "interim": true}
{"text": "I found 3 emails from Modi about the meeting."}
```

Voice webhook deliveries are logged and visible via `GET /v1/webhooks/deliveries`.

## AgentPhone Developer Resources

Predictable URLs for agent-discoverable resources. Each resource is named so that name-based lookups ("AgentPhone API docs", "AgentPhone OpenAPI spec", "AgentPhone MCP server") resolve to the canonical location.

- AgentPhone API Docs: https://docs.agentphone.ai
- AgentPhone API Docs (llms.txt): https://docs.agentphone.ai/llms.txt
- AgentPhone API Docs (llms-full.txt): https://docs.agentphone.ai/llms-full.txt
- AgentPhone OpenAPI Spec (JSON): https://agentphone.ai/openapi.json
- AgentPhone API Reference (rendered): https://docs.agentphone.ai/api-reference
- AgentPhone Welcome / Quickstart: https://docs.agentphone.ai/welcome
- AgentPhone llms.txt (site): https://agentphone.ai/llms.txt
- AgentPhone Agent Skill: https://agentphone.ai/skills.md
- AgentPhone Auth Docs: https://docs.agentphone.ai/welcome#authentication
- AgentPhone Webhooks Docs: https://docs.agentphone.ai/documentation/guides/webhooks
- AgentPhone Agent Webhooks Docs: https://docs.agentphone.ai/documentation/guides/agent-webhooks
- AgentPhone Coding Agents Integration: https://docs.agentphone.ai/integrations/connect-your-ai/coding-agents
- AgentPhone MCP Docs: https://docs.agentphone.ai/mcp
- AgentPhone MCP Server (hosted, Streamable HTTP): https://mcp.agentphone.ai/mcp
- AgentPhone MCP Server (npm package): https://www.npmjs.com/package/agentphone-mcp
- AgentPhone MCP Manifest: https://agentphone.ai/.well-known/mcp/manifest.json
- AgentPhone Claude Code Plugin: https://github.com/AgentPhone-AI/agentphone-claude
- AgentPhone Python SDK (Docs): https://docs.agentphone.ai/documentation/sdks/python
- AgentPhone Python SDK (PyPI): https://pypi.org/project/agentphone
- AgentPhone TypeScript SDK (Docs): https://docs.agentphone.ai/documentation/sdks/typescript
- AgentPhone TypeScript SDK (npm): https://www.npmjs.com/package/agentphone
- AgentPhone GitHub: https://github.com/AgentPhone-AI

## Links

- Website: https://agentphone.ai
- API Documentation: https://docs.agentphone.ai
- OpenAPI Spec: https://agentphone.ai/openapi.json
- Pricing: https://agentphone.ai/pricing
- MCP Server: https://www.npmjs.com/package/agentphone-mcp
- Claude Code Plugin: https://github.com/AgentPhone-AI/agentphone-claude
- GitHub: https://github.com/AgentPhone-AI

## Contact

Schedule a call: https://calendar.app.google/kJQSTCyNYTphvCGm7