# 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

1. Sign up at https://agentphone.to/register (no credit card required)
2. Go to https://agentphone.to/dashboard/settings to generate an API key
3. Use the API key as a Bearer token: `Authorization: Bearer YOUR_API_KEY`
4. All API requests go to https://api.agentphone.to

API keys have full access to your project's resources (agents, numbers, calls, messages, webhooks). There is no separate sandbox — your first phone number is free, 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.to/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

- First phone number: Free forever (includes 1,000 SMS/month and 250 voice minutes/month)
- Additional lines: $8/month per line

## API Base URL

https://api.agentphone.to

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

## Links

- Website: https://agentphone.to
- API Documentation: https://docs.agentphone.to
- Pricing: https://agentphone.to/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