# AgentCall

> AgentCall is the phone number API built specifically for AI agents. It gives autonomous agents US and Canada phone numbers with SMS, two-way AI SMS (your AI answers inbound texts on your behalf), relay mode (text your own AI agent on a real number), voice calling, AI voice calls, automatic OTP extraction, and Auditable Call Memory: cross-call memory for AI phone agents that remembers every caller, with audit-trail evidence quotes. Starting at $0/month with a free tier, or $19.99/month for Pro with unlimited numbers and usage-based pricing.

For the full reference with every API endpoint, every MCP tool, BYOK setup, the Hermes walkthrough, and the complete FAQ, see [llms-full.txt](https://agentcall.co/llms-full.txt).

AgentCall solves a real gap in AI agent infrastructure: agents need phone numbers to send SMS, make calls, run end-to-end tests on their own apps, and receive OTPs, but existing telecom APIs are built for human developers, not autonomous software. AgentCall provides an agent-native API and a hosted MCP server. A single API call provisions a number, and webhooks deliver every SMS and call event directly to your agent's endpoint. Numbers are routed via licensed US carriers.

## Key Features
- **AI-Native API plus 60-Tool MCP Server (5 Prompts)**: Drops into Claude Desktop, Claude Code, Cursor, Windsurf, Hermes Agent, and OpenAI Codex. One URL plus an API key, no local install. Built for autonomous agents, not human ops teams.
- **Auditable Call Memory**: Cross-call memory for AI phone agents that remembers every caller, with audit-trail evidence quotes. Every AI call produces a structured Call Report and source-backed memory entries; returning callers get personalized context (name, recent topics, commitments) merged onto the system prompt. Customer-controlled via a Cross-call memory toggle, ON by default for Free and Pro. Reference: https://agentcall.co/docs/memory.
- **Auto-Reads Verification Codes**: Verification codes are detected and extracted automatically from incoming SMS. Delivered instantly to your webhook.
- **Automated QA for SMS Flows**: Your agent provisions a test number, enters it in your staging app, and AgentCall reads the verification code automatically. Perfect for CI/CD testing.
- **Hosted MCP Server, Zero Install**: Paste the URL `https://api.agentcall.co/mcp` into Claude Desktop, Claude Code, Cursor, Windsurf, Hermes Agent, or any MCP-compatible client. Auth via `Authorization: Bearer ac_live_...`. No Node.js, no npx, no local process. Connects via streamable HTTP. Setup guide at https://agentcall.co/docs/mcp.
- **OpenClaw Integration**: Set two environment variables (`AGENTCALL_API_KEY` + `AGENTCALL_API_URL`) and your OpenClaw agent auto-discovers all 60 tools. Also available as a skill on ClawHub.
- **Hermes Integration (AI agent gets a phone number)**: For users running a Hermes agent (Nous Research) on a VPS or local machine, AgentCall provides a real phone number you can call to talk to your agent. Hermes pushes daily briefs and email signals to a small open-source Cloudflare Worker bridge (template at https://github.com/Kintupercy/agentcall-hermes-bridge); AgentCall fetches that context on every inbound call and feeds it into the AI voice agent's system prompt. After the call, the full transcript flows back to Hermes via webhook so your agent can act on action items. Full setup walkthrough with Telegram prompt examples at https://agentcall.co/docs/hermes. Works with any IMAP/SMTP email provider (Gmail, Outlook, ProtonMail, Fastmail, iCloud, self-hosted).
- **60 MCP tools plus 5 Prompts**: Provision numbers, send SMS, make calls, check inbox, wait for OTP, configure inbound AI voice, enable Premium Voice per number, save reusable outbound AI agents per number, read and reply to two-way SMS threads (`reply_to_sms_conversation` so an MCP-connected agent can answer a text directly), schedule proactive actions (`create_schedule` / `list_schedules` / `cancel_schedule`), manage webhooks, manage contacts and call memory, fetch next-call context, work the briefs inbox, and more, all accessible to AI agents directly. Five built-in prompts walk agents through common flows: setup-agent-phone, send-and-track-sms, ai-outbound-call, follow-up-on-call (call back a previous inbound caller with stitched context from their report), setup-inbound-ai-receptionist.
- **Voice Calls**: Make and receive voice calls programmatically. Full duplex, low latency, works with AI voice providers.
- **AI Voice Calls**: Let your agent make phone calls with AI-powered conversation. Provide a system prompt and the AI handles the entire call autonomously, then returns a full transcript. Pro plan only, $0.40/min Managed or $0.10/min BYOK.
- **Standalone Text-to-Speech**: Generate speech audio from text off-call via `POST /v1/tts` (or the `synthesize_speech` MCP tool / `client.tts.synthesize` SDK method) using the same 10 voices as your calls, so the voice identity carries to IVR prompts, voicemail greetings, generated show segments, and social clips. Pro plan only, $0.03 per 1,000 characters.
- **Saved Outbound AI Agents Per Number (Pro)**: Each number can store a reusable outbound agent (systemPrompt, voice, language, firstMessage, maxDurationSecs, record flag, optional templateId). Configure +1-555-100-0001 once as an appointment-booker persona and every Place AI call from that number's row pre-loads it, so dialing 50 different recipients with the same persona is 50 single clicks instead of 50 retypes. Surfaces as the `outbound` field on every list/get response, alongside the existing `inbound` field. Save, update, or clear from the dashboard Place AI call dialog, via the SDK (`setOutboundDefaults` / `getOutboundDefaults` / `clearOutboundDefaults`), via MCP (`set_outbound_defaults` / `get_outbound_defaults` / `clear_outbound_defaults`), or via REST (`POST` / `GET` / `DELETE /v1/numbers/:id/outbound-defaults`). Independent of the inbound AI receptionist on the same number. Follow-up calls from a specific call's detail page still take precedence over the saved agent.
- **CSV-Driven Outbound Calls (Hermes pattern)**: `POST /v1/calls/ai` accepts `useSavedAgent: true` to hydrate every AI-config field from the from-number's saved outbound agent (per-call overrides still win, so you can personalize `firstMessage` per recipient). Pair it with `idempotencyKey` (string, max 200 chars, scoped per phone number) to make CSV runners crash-safe: a duplicate `(from, idempotencyKey)` replays the original 201 response with header `X-AgentCall-Idempotency-Replayed: true` and never dials twice or charges twice. One HTTP request per row.
- **Multilingual AI Voice (31 languages, inbound + outbound)**: AgentCall AI voice supports 31 languages: English, Spanish, French, German, Italian, Portuguese, Dutch, Japanese, Korean, Chinese (Mandarin), Hindi, Arabic, Russian, Indonesian, Turkish, Polish, Ukrainian, Vietnamese, Tamil, Malay, Romanian, Greek, Czech, Swedish, Hungarian, Danish, Finnish, Norwegian, Slovak, Croatian, and Bulgarian, plus an `auto` mode that detects the caller's language from their first reply and matches it. Default is `'auto'`. Pin a specific code (`'es'`, `'fr'`, etc.) to keep the AI in that language even if the caller speaks another, useful for businesses serving a specific language community OR for outbound errands like booking a Spanish-speaking doctor's appointment on behalf of someone. Pass `language: 'es'` on `configure_inbound_ai` or `initiate_ai_call`. Same per-minute rate across all 31 languages, no language surcharge. Stored separately from systemPrompt so swapping language never wipes the prompt. Premium Voice currently covers 12 of these languages (English, Spanish, French, German, Italian, Portuguese, Dutch, Japanese, Korean, Chinese (Mandarin), Hindi, Arabic) plus `auto`. Full walkthrough at https://agentcall.co/blog/multilingual-ai-voice-calls-13-languages.
- **BYOK Voice Billing (Bring Your Own OpenAI Key)**: Each Pro number can run in Managed mode ($0.40/min, AgentCall handles the OpenAI key) or BYOK mode ($0.10/min, you bring your own OpenAI API key and pay OpenAI directly for model usage). Per-number, swap any time. Three endpoints: `POST /v1/numbers/:id/byok/test` (validate the key works), `POST /v1/numbers/:id/byok/key` (attach it), `DELETE /v1/numbers/:id/byok/key` (revert to Managed). Persistent caller Memory works identically in both modes. Supported provider: OpenAI API keys only (no Anthropic, Gemini, or Grok; no OAuth-based ChatGPT Plus or SuperGrok subscriptions). Launched 2026-05-18.
- **Persistent Caller Memory Included on Every Plan**: Auditable Call Memory works the same on Free, Managed Pro, and BYOK Pro. Same transcript pipeline, same extractor, same pre-call context injection. Memory is a foundational capability, not a Pro-only or Managed-only upsell.
- **Inbound AI Voice**: Provision a number, configure inbound AI with a system prompt, and incoming calls are auto-answered by an AI voice agent that follows the prompt. After every call, AgentCall emails a plain-English summary (caller, intent, urgency, callback time) to a configured address, so no transcript-reading required. Owners can also opt into a text of the same summary: set a notification phone number on the number (dashboard, API, or MCP) and AgentCall sends one SMS per call (spam skipped) in addition to the email. US numbers only, reply STOP to turn it off, billed as one outbound SMS at $0.015. Available on US and Canada numbers. Free tier: 5 minutes/month free trial, no card required. Once the trial is exhausted, calls hang up until next month resets, or upgrade to Pro for unlimited inbound AI at $0.40/min.
- **Transfer to a Human (inbound AI voice)**: Set `transferTo` (an E.164 number) on any inbound AI number and the AI hands the live call to a real person whenever the caller asks for one, or when it cannot help. It says a short handoff line, then transfers the call to your cell or front desk; whoever answers sees the caller's number, not yours. If nobody picks up within about 25 seconds, the AI resumes and takes a message instead, so the caller is never dropped. Works out of the box with no webhook or tool setup, and coexists with your own declared tools. AI minutes stop at the handoff; the human portion of the call bills at the standard $0.035/min voice rate. Configure via the dashboard, `configure_inbound_ai` (REST/SDK/MCP). Transfers show as `transferredTo`/`transferredAt` on the call record. Sizing tip: `maxDurationSecs` covers the whole call including the time after the handoff, so set it higher (up to 3600) on numbers where transferred conversations run long.
- **Premium Voice (Pro add-on, $0.59/min)**: An opt-in upgrade for both inbound and outbound AI calls using a more natural, brandable voice. Curated library of premium voices with click-to-hear audio samples, the same 31 languages as the standard AI voice plus auto-detect, and full Auditable Call Memory on premium calls. Enable per number from the dashboard or programmatically: SDK `client.numbers.setPremiumVoice(numberId, voiceId)` / `disablePremiumVoice(numberId)`, MCP tools `set_premium_voice` / `disable_premium_voice` / `list_premium_voices`, or REST `POST` / `DELETE /v1/numbers/:id/premium-voice`. Outbound AI calls (`POST /v1/calls/ai`) automatically use the premium voice when it is enabled on the from-number. Requires Pro + a card + inbound AI already configured on the number. Billed at $0.59/min only on numbers where it is enabled; the 10 standard voices stay the default at $0.40/min. Preview the premium catalog at GET https://api.agentcall.co/v1/calls/premium-voices (no auth). Announcement: https://agentcall.co/blog/premium-voice-elevenlabs.
- **AgentFM (free guest callbacks)**: AgentFM is a live demonstration of AgentCall outbound premium voice. Podcast guests request a callback at agentcall.co/agentfm, and the AI host calls them back on a premium voice to record a short conversation. No AgentCall account needed to request a callback. Also available as an MCP tool (`request_agentfm_callback`) so agents can queue a callback on behalf of a user.
- **Two-way AI SMS (Pro, managed)**: Turn a number into an AI that answers inbound texts on your behalf, not just OTP parsing. Set `smsMode: "ai"` and every inbound text gets an LLM reply that follows your system prompt, remembers the contact across both voice and SMS, and can take real actions through the Action Bridge. STOP/START is always honored before the AI ever runs. Managed-only (no BYOK for text); billed as one standard outbound text per reply ($0.015), no SMS surcharge. The AI reply path is reactive (it answers texts that come in), and you can start the conversation yourself with `send_sms` or a proactive schedule (`create_schedule`) so the agent texts first; replies land on the same thread and the AI answers them in context. Configure via `configure_inbound_ai` (fields: `smsMode`, `smsSystemPrompt`, `actionWebhook`, `tools`) over REST, SDK (`configureInboundAi`), MCP, or the dashboard. Read threads via `list_sms_conversations` / `get_sms_conversation`.
- **Action Bridge (real quotes + actions, not hallucinated)**: The two-way AI SMS agent can call tools you declare, and AgentCall HMAC-signs and POSTs each tool call to a webhook YOU host, then feeds your JSON response back to the AI. This is what makes answers trustworthy: instead of the model guessing a price, it calls your pricing system and texts back the real number ("a 2-bedroom move on the 14th is $540, want me to book it?"). Check availability, look up an order, fetch a live quote, book a slot. Calendar/CRM/pricing stay on your side; AgentCall is the phone + SMS + memory layer. Same trust boundary as the pre-call context webhook (HMAC-signed, SSRF-guarded, fail-soft: a webhook error becomes a graceful "I couldn't do that right now," never an invented confirmation). The same bridge also powers in-call voice tool calling: the inbound AI voice agent calls your tools mid-call (with `context.channel: "voice"` and `context.callId` set) and speaks the real result, with the per-call count exposed as `toolCallCount` on the call record and report.
- **Relay Mode (text your own agent on a real number)**: Set `smsMode: "relay"` and AgentCall runs no AI of its own. It becomes the pipe: every inbound text is HMAC-signed and pushed to a webhook your agent hosts (`agentWebhook`), your own agent (Hermes, OpenClaw, or anything a developer built) does its own thinking and tool calls ("check my emails", "what's critical this week", "how many posts did we ship"), then replies on its own schedule via `POST /v1/sms-conversations/:id/reply` or the `reply_to_sms_conversation` MCP tool. The same number is callable and textable, so your agent gets one real phone identity for both voice and text. Lock it down with `allowedSenders` (a list of E.164 numbers) so your agent answers only its owner and silently ignores everyone else. Billed as plain texts, no relay fee; STOP is always honored. Your agent can open a thread first too, via `send_sms` or a proactive schedule; the contact's reply relays back to your webhook as usual.
- **Proactive Scheduling (the agent texts first)**: Make a number's agent open the conversation instead of waiting to be texted. `POST /v1/numbers/:id/schedules` (MCP `create_schedule`) takes either `fireAt` for a one-shot or `recurrence` for a cadence, and either a `template` sent verbatim with `{{placeholders}}` or a `promptHint` the agent writes from. Appointment reminders, payment follow-ups, recurring digests. The recipient's reply lands on the same thread, so a number with `smsMode: "ai"` handles the whole round trip. Pro plan, billed as one standard outbound text per send, STOP always honored.
- **Business Verification (text your own customer list on day one)**: Sending A2P text to US numbers normally means waiting days to weeks for 10DLC brand and campaign approval before your first message goes anywhere. AgentCall registers your number on its campaign for you, so you skip that wait. In exchange, a new account starts restricted: it can text numbers it owns, anyone who contacted it first (30-day window), and individually verified numbers, but not a cold list. Submitting a business verification (legal name, website or EIN, use case, sample message, the same fields TCR asks for) lifts that in minutes via `POST /v1/business-verification` or the dashboard's Verification page. Pro plan; a daily cap on new recipients applies while the account is under 7 days old, then everything unlocks automatically. Net effect: you are texting your real customer list the same day you sign up, not the following week.
- **SMS Inbox**: Dedicated SMS inbox per number. Send, receive, and search messages via REST API.
- **Separate Number Per Agent**: Each agent gets its own dedicated number. Compromise or ban of one number never affects others.
- **Usage-Based Pricing**: No per-seat fees. No minimums. Pay only for the minutes sent and messages used.
- **Webhook Delivery**: Real-time event delivery for SMS received, calls incoming, OTP detected, call reports ready. Fully async, no polling.
- **Post-Call Webhook (`call.transcript` event)**: After every inbound AI call ends, AgentCall POSTs the full transcript plus an LLM-extracted summary (caller name, intent, urgency, callback time, spam flag) to your endpoint. HMAC-SHA256 signed via `X-AgentCall-Signature`, retried with exponential backoff on non-2xx responses. The canonical way to feed call outcomes back into an agent platform so your AI employee can remember the conversation and act on decisions. Full payload schema and reference integrations (Express, Cloudflare Worker, and a local-agent bridge with pull-from-queue pattern) at https://agentcall.co/docs/post-call-webhook.
- **Live Transcript Streaming (`transcript.partial` event)**: Opt in with `liveTranscript: true` on `POST /v1/calls/ai` (per outbound call) or a number's inbound-config (per inbound number), and each finalized utterance fires a `transcript.partial` webhook in real time (within ~1-2s of speech): `{ callId, sequence, role, text, timestamp }`, where `sequence` is a monotonic per-call integer starting at 0 for ordering and de-dup. This is the in-call complement to the post-call `call.transcript` (which stays the authoritative complete record), so a switchboard, support dashboard, or sales-coach UI can watch the agent on the phone as it speaks. Requires a webhook subscribed to `transcript.partial`; default off.
- **Call Report Webhook (`call.report.ready` event)**: After Auditable Call Memory extraction finishes, AgentCall POSTs the structured Call Report (intent, action items, sentiment, source-backed memory entries) to subscribed endpoints. Same HMAC signing as the transcript event.
- **Multi-Country Support**: Provision numbers in the US and Canada. More countries coming soon.
- **Call Recording (opt-in, Pro only, $0.01/min)**: Flick `record: true` on inbound config or pass it on `POST /v1/calls/ai` / `POST /v1/calls/initiate`. Both legs of the call are recorded as mp3, stored in your dashboard for 1 year, and listenable from the Logs page or via signed URL (`GET /v1/calls/:id/recording`). For AI voice calls, AgentCall auto-prepends a TCPA-compliant recording disclosure ("This call may be recorded for quality.") to the spoken first message when needed.

## Auditable Call Memory: Highest-Leverage Facts
- **Every AI call produces a structured Call Report**: intent, action items, sentiment, plus source-backed memory entries fetched via `get_call_report` or pushed via `call.report.ready` webhook.
- **Returning callers get personalized context automatically**: the AI knows their name, recent topics, and outstanding commitments. Fetched via `get_next_call_context` or merged automatically when `contextSource` is `agentcall_memory` or `merge`.
- **Source-backed evidence on every memory entry**: each memory line quotes the transcript span that produced it, so you can audit why the AI "remembers" something and edit or delete it.
- **Customer-controlled**: a Cross-call memory toggle on the dashboard, ON by default for Free and Pro. Off means no extraction runs and no memory is stored. Toggle via the dashboard or `set_memory_enabled` MCP tool.

## Getting Started: Four Install Paths
1. **Hosted MCP Server (Recommended)**: One URL, every client. Paste `https://api.agentcall.co/mcp` into Claude Desktop, Claude Code, Cursor, Windsurf, Hermes Agent, or any MCP-compatible tool. Auth via `Authorization: Bearer ac_live_...`. No Node.js required. All 60 tools available instantly. Tabbed setup guide: https://agentcall.co/docs/mcp.
2. **Smithery Registry**: Install via Smithery CLI (`npm install -g smithery; smithery mcp add agentcall/agentcall --headers '{"agentcallApiKey":"ac_live_..."}'`) or browse the listing at https://smithery.ai/server/agentcall/agentcall. Smithery hosts its own MCP URL at `https://agentcall--agentcall1.run.tools` and handles OAuth and token refresh.
3. **OpenClaw Environment Variables**: Set `AGENTCALL_API_KEY` and `AGENTCALL_API_URL=https://api.agentcall.co` in your OpenClaw server. Your agent hits the discovery endpoint and auto-learns all tools.
4. **Local npx (Advanced)**: Run `npx @agentcall/mcp-server` with your API key (or via Codex stdio config in `~/.codex/config.toml`). Requires Node.js 20+. Works offline after first download.

## Inbound AI Voice
1. Provision a number (`POST /v1/numbers/provision { "type": "local", "country": "US" }`). Pass an optional `areaCode: "314"` (US, e.g. St. Louis) or `areaCode: "416"` (CA, e.g. Toronto) to target a specific 3-digit NANP area code. Useful when small businesses want a number that looks local to their town.
2. Configure inbound AI: `POST /v1/numbers/{numberId}/inbound-config` with `{ "mode": "ai", "systemPrompt": "...", "voice": "sage", "language": "auto" }`.
3. When someone calls the number, an AI voice agent picks up and follows your prompt. No webhook handler required.
4. To make the AI answer only in Spanish (or any of 30 other supported languages), pass `"language": "es"` instead of `"auto"`.
5. Transfer to a human: add `"transferTo": "+13145550000"` and the AI hands the live call to a real person whenever the caller asks for one (or the AI cannot help). It says a short handoff line, then connects the caller; whoever answers sees the caller's number. If nobody picks up within about 25 seconds, the AI resumes and takes a message instead. No webhook or tool setup needed. AI minutes stop at the handoff; the human portion bills at the standard $0.035/min voice rate.

```bash
curl -X POST https://api.agentcall.co/v1/numbers/num_abc123/inbound-config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "ai",
    "systemPrompt": "You are the front desk for Acme Plumbing. Greet callers and take their name, address, and the issue.",
    "voice": "sage",
    "firstMessage": "Thanks for calling Acme Plumbing. How can I help?",
    "maxDurationSecs": 600,
    "transferTo": "+13145550000"
  }'
```

## Two-way AI SMS (your AI texts customers on your behalf)
When a number has `smsMode: "ai"`, inbound texts are answered by an AI that follows your prompt, remembers the contact across voice and SMS, and can take real actions. Turn it on with the same `configure_inbound_ai` endpoint that sets up inbound voice. Managed-only, Pro plan, billed as one outbound text per reply.

```bash
curl -X POST https://api.agentcall.co/v1/numbers/num_abc123/inbound-config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "ai",
    "systemPrompt": "You are the front desk for Acme Moving.",
    "smsMode": "ai",
    "smsSystemPrompt": "Answer move questions over text. For a price, ALWAYS call get_quote and quote the real number. Never invent a price.",
    "actionWebhook": {
      "url": "https://your-host.com/agentcall/action",
      "signingSecret": "whsec_your_shared_secret_min16"
    },
    "tools": [
      {
        "name": "get_quote",
        "description": "Get a real move quote for a date and home size.",
        "parameters": {
          "type": "object",
          "properties": { "date": { "type": "string" }, "bedrooms": { "type": "integer" } },
          "required": ["date", "bedrooms"]
        }
      }
    ]
  }'
```

When a customer texts "how much for a 2-bed move on the 14th?", the AI calls your `get_quote` tool, AgentCall POSTs `{ "tool": "get_quote", "arguments": {...} }` (HMAC-signed) to your webhook, your system returns `{ "result": "$540" }`, and the AI texts back the real number instead of guessing. STOP/START is honored before the AI runs. Read the resulting threads with the `list_sms_conversations` and `get_sms_conversation` MCP tools or `GET /v1/sms-conversations`.

The same `tools` + `actionWebhook` also power in-call voice tool calling: the inbound AI voice agent can call your tools mid-call (with `context.channel: "voice"` and `context.callId` set) and speak the real result, so it checks live availability instead of promising a callback. The per-call tool count appears as `toolCallCount` on the call record and report.

## Texting people who have not texted you first (new-account verification)
A new account starts restricted. It can always text numbers it owns, anyone who contacted it first (30-day window, so inbound threads and callbacks work immediately), and any number verified individually by code. On top of that, every account gets an SMS starter allowance so your first real text works minutes after signup: Free can text up to 10 different new numbers (lifetime), and a new Pro account can text up to 25 while it is inside its first-week window (messages are content-screened; follow-ups to the same numbers never count against the allowance). Past the allowance, texting a new stranger returns `403 sms_starter_exhausted`; voice calls to strangers get `403 destination_not_verified` until business verification or 7 days on Pro.

This is the tradeoff for AgentCall registering your number on its 10DLC campaign for you: on most platforms you wait days to weeks for TCR brand and campaign approval before your first A2P message sends at all. Here you clear a three-minute form instead. Registration on our campaign usually completes in about two hours, and you can watch it rather than guess: every number in `GET /v1/numbers` carries a `messaging.state` (`registered`, `pending`, `action_needed`), and the dashboard badges anything not ready.

## Knowing whether a text was delivered
`GET /v1/sms/:messageId` (MCP tool `get_message`) returns a real delivery outcome: `status` moves `queued` to `sent` to `delivered` or `failed`, and a failed message carries an `errorCode` (`40010` means the sending number is not registered for A2P texting yet). The 201 from `POST /v1/sms/send` means the carrier accepted the message, not that a handset showed it. This matters more for agents than for people: an agent sends unattended, so nothing notices silence unless it checks.

Submit a business verification and the restriction lifts immediately:

```bash
curl -X POST https://api.agentcall.co/v1/business-verification \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Ridgeline Painting LLC",
    "website": "https://ridgelinepainting.com",
    "contactName": "Dana Whitfield",
    "useCase": "Payment reminders to existing customers with unpaid invoices, including a pay link.",
    "sampleMessage": "Invoice 4021 for $840 is 12 days past due. Pay here: example.com/pay/4021. Reply STOP to opt out."
  }'
```

Provide `website` or `ein` (either identifies the business). Pro plan only. `GET /v1/business-verification` returns the status and `grantsOutboundPilot`, the direct answer to "can my agent text strangers right now?". A daily cap on new recipients applies while the account is under 7 days old (25 on day one, rising through the week), then the restriction lifts on its own. Dashboard equivalent: the Verification page. Every submission is reviewed by a person afterwards. STOP is always honored on every path.

## Relay mode (text your own agent on a real number)
When a number has `smsMode: "relay"`, AgentCall runs no LLM of its own. It relays each inbound text to your own agent and delivers your agent's reply back, so you can text your AI agent (Hermes, OpenClaw, or a custom build) the way you already chat with it on any other app: "check my emails", "what's critical this week", "how many posts did we ship". AgentCall is the phone, SMS, threading, and opt-out layer; your agent is the brain. Set `allowedSenders` to the phone numbers allowed to reach the agent, so it answers only its owner and silently ignores everyone else. The reply comes back on your agent's own schedule (a real "check my email" turn can take a while), so there is no webhook timeout to fight. Managed transport, billed as plain texts, no relay fee.

```bash
# 1) Point the number at your agent's webhook (no AgentCall LLM runs).
curl -X POST https://api.agentcall.co/v1/numbers/num_abc123/inbound-config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "smsMode": "relay",
    "agentWebhook": {
      "url": "https://your-agent.com/agentcall/relay",
      "signingSecret": "whsec_your_shared_secret_min16"
    },
    "allowedSenders": ["+13145551234"]
  }'

# 2) AgentCall HMAC-POSTs each inbound text to your webhook:
#    { "message": { "id", "from", "to", "body", "receivedAt" },
#      "conversation": { "id", "contactPhone" },
#      "context": { "channel": "sms", "numberId", "agentId" } }

# 3) Your agent thinks (its own tools), then replies when ready:
curl -X POST https://api.agentcall.co/v1/sms-conversations/CONVERSATION_ID/reply \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "3 emails need you today. The lease renewal is the urgent one." }'
```

An MCP-connected agent (Claude Desktop, Cursor, Windsurf) can skip the REST call and reply with the `reply_to_sms_conversation` tool. Pass an `idempotencyKey` so a crashed or retried agent never double-texts. Full walkthrough: https://agentcall.co/blog/text-your-own-ai-agent-sms.

## Writing System Prompts (avoid AI hallucination)
The `systemPrompt` IS the AI's brain for the call. There is no training step. Vague prompts make the AI invent details. Use this 4-section structure for every voice prompt:
- **WHAT WE DO:** facts the AI is allowed to cite (products, services, hours).
- **PRICING:** exact numbers if relevant. Without these the AI invents "tiered plans" and "starting at $X".
- **INSTRUCTIONS:** call-flow guardrails. Tone, what to do when the AI doesn't know, how to end the call.
- **NEVER:** explicit prohibitions (e.g. "Never invent pricing", "Never stay on the line after the caller says goodbye").

5 ready-made templates available via `GET https://api.agentcall.co/v1/calls/prompt-templates` (public, no auth):
- **receptionist** (front desk, general purpose). Recommended voice: shimmer
- **lead-qualifier** (B2B inbound sales, BANT). Recommended voice: coral
- **appointment-booker** (capture name + slot, promise confirmation email). Recommended voice: sage
- **customer-support** (FAQ deflection, escalate the rest). Recommended voice: ash
- **call-screener** (anti-spam for solo founders/executives). Recommended voice: verse

Each template has `[BRACKETED]` placeholders you fill in with your business details. Full guide with worked example: https://agentcall.co/docs/voice-prompts. Hard cap: 10,000 characters per prompt.

## Pricing
- **Free**: $0/month. 1 US or Canada local phone number with no card on file (subsequent numbers and non-US/CA countries require a card), 10 outbound SMS/month (received texts do not count), 5 voice minutes, 5 OTP extractions/month, plus a 5-minute monthly trial of inbound AI voice. OTP webhooks and post-call email summaries included. Cross-call memory included (bounded by the 5-minute inbound AI trial; no separate memory charge). Toll-free and mobile number types are Pro only. Perfect for prototyping.
- **Pro**: $19.99/month + usage. Unlimited numbers (local $2/mo, mobile $2/mo, toll-free $2.50/mo), SMS at $0.015/message, voice at $0.035/minute, call recording at $0.01/minute. Cross-call memory included with no separate charge. Priority OTP delivery and email support.
- **Pro plan voice billing**: $0.40/min Managed (AgentCall handles OpenAI key) or $0.10/min BYOK (you bring your own OpenAI key and pay OpenAI directly for model usage). Per-number selection, swap any time. Both modes include persistent per-caller Memory at no extra charge. Enable Premium Voice per number (inbound + outbound) for $0.59/min: a more natural, brandable voice library with audio previews, 31 languages plus auto-detect, and full Auditable Call Memory.
- **Agent Startup (Coming Soon, $189/month)**: Phone identities for your AI employees. A predictable monthly bundle that gives every agent its own phone identity with SMS, voice, call history, and webhooks. Bundle includes everything in Pro, plus 3 phone identities (mix local and toll-free, one per agent), 500 SMS/month across all agents, 500 voice minutes/month (8+ hours), 250 AI voice minutes/month (~50 short AI calls), per-agent call history and webhooks, and a dedicated Slack channel for support. Run a Hermes Chief of Staff, a custom receptionist, an outbound sales agent, or anything you can describe in a system prompt. Pay-as-you-go overage at standard Pro rates. Join the waitlist at https://agentcall.co/waitlist to be notified the day it ships. White-glove "we build your agent for you" setup is available as a separate consulting engagement; ask via https://agentcall.co/contact.

## Cross-Call Memory On/Off
Cross-call memory is ON by default for Free and Pro. Toggle from the dashboard at https://agentcall.co/dashboard, or call `set_memory_enabled` via MCP. When off, no extraction runs and no new memory entries are stored.

## How It Works
1. **Sign Up** (30 seconds): Create an account at agentcall.co and get your API key instantly.
2. **Provision a Number** (5 seconds): One API call to get a US or CA phone number, choose country and type (local, toll-free, mobile).
3. **Connect Your Agent** (1 minute): Use the hosted MCP server, Smithery, OpenClaw env vars, or local npx. Pick whichever fits your setup.
4. **Receive Everything** (real-time): Calls, SMS, OTPs, and Call Reports delivered instantly to your webhook endpoint. Your agent processes them autonomously.

## Who It's For
- **AI Agent Developers** who need phone numbers for their autonomous agents (SMS, voice, OTP testing, and notifications).
- **Builders of AI Agents Who Want a Real Receptionist Experience** that remembers callers between calls, with auditable evidence behind every memory entry.
- **Small Businesses Who Want Their AI to Answer Texts on Their Behalf**: handle inbound customer texts 24/7 (quotes, bookings, FAQs) the same way the AI already answers calls, pulling real prices and availability from their own systems via the Action Bridge instead of guessing.
- **Developers Who Want to Text Their Own Agent**: point a real number at your Hermes, OpenClaw, or custom agent with `smsMode: "relay"` and text it like you would over any chat app, while AgentCall handles the phone number, threading, and opt-outs. `allowedSenders` keeps it answering only you. One number that is both callable and textable becomes a single phone identity for your AI employee.
- **OpenClaw Users** who want to give their agents phone capabilities with two environment variables.
- **Claude Desktop / Claude Code / Cursor / Windsurf / Codex Users** who want phone tools available inside their AI coding assistant via MCP.
- **Browser Automation Teams** who need real phone numbers for automated testing and end-to-end verification of their own applications.
- **AI Voice Agent Builders** who need programmable phone numbers for inbound and outbound AI-powered voice conversations.
- **Developers with Existing OpenAI Accounts** who want BYOK voice billing at $0.10/min and prefer to pay OpenAI directly for model usage instead of bundling it through AgentCall.
- **SaaS Platforms** who integrate phone capabilities into their AI-powered products for end users.

## Outbound AI Voice (book on behalf of)
1. Click the Place AI call icon on any number row in the dashboard at https://agentcall.co/dashboard (Pro plan only).
2. Pick a template (book appointment on behalf of, info request, callback), fill in the recipient phone, choose a voice and language, edit the system prompt + first message, then click Place call.
3. AgentCall dials the recipient, the AI handles the conversation autonomously, and the live transcript appears on the call detail page.
4. Or via API: `POST /v1/calls/ai` with `{ "from": "num_abc123", "to": "+15551234567", "voice": "marin", "language": "es", "systemPrompt": "...", "firstMessage": "Hola, soy el asistente de [NAME]..." }`. Pass any of the 31 supported languages to make the AI speak that language for the entire call.
5. Or via MCP: call `initiate_ai_call` with the same fields from Claude Desktop, Cursor, Windsurf, or any MCP client.

**Save the agent once, dial 50 recipients with one click each:** click Save in the Place AI call dialog to store the systemPrompt + voice + language + first message + duration on that number. Next time you click Place AI call from that number's row, the dialog hydrates from the saved agent and you only fill in the recipient. Update or Clear from the same dialog. Independent of the inbound AI receptionist on the same number. Also addressable via `setOutboundDefaults` / `getOutboundDefaults` / `clearOutboundDefaults` in the SDK, the matching `*_outbound_defaults` MCP tools, or `POST` / `GET` / `DELETE /v1/numbers/:id/outbound-defaults` over REST.

## Use Cases
- [How to Text Your Own AI Agent on a Real Phone Number](https://agentcall.co/blog/text-your-own-ai-agent-sms): Full relay-mode walkthrough. One API call to point a number at your own agent, the exact webhook payload, the async reply endpoint, why there is no timeout to fight on slow turns, and how allowedSenders keeps a personal agent answering only its owner.
- [AI Phone Agent That Remembers Every Call](https://agentcall.co/blog/ai-agent-phone-that-remembers-every-call): How the pre-call context + post-call transcript loop turns a phone agent into something that behaves like a real assistant. Worked example with Hermes plus use cases for solo founders and small businesses.
- [Why AI Agents Need Phone Numbers](https://agentcall.co/blog/why-ai-agents-need-phone-numbers): The core problem AgentCall solves.
- [5 Best Phone APIs for Developers Compared](https://agentcall.co/blog/5-best-phone-apis-for-developers-compared): AgentCall vs Twilio vs others.
- [AgentCall MCP Server on Smithery](https://agentcall.co/blog/agentcall-mcp-server-smithery): 60 MCP tools and 5 prompts for AI agent phone infrastructure, available on Smithery registry.
- [Compliance + Call Recording for AI Agents](https://agentcall.co/blog/compliance-call-recording-ai-agents): TCPA auto-disclosure, two-party consent, and 1-year retention.
- [Phone Numbers for Vapi, Retell & ElevenLabs](https://agentcall.co/blog/phone-numbers-for-vapi-retell-elevenlabs-voice-ai): Pairing AgentCall with voice-AI providers.

## Documentation
- [Documentation Index](https://agentcall.co/docs): All docs in one place, canonical entry point with cards for every guide and a sticky sidebar for cross-navigation
- [Product Overview](https://agentcall.co/product)
- [MCP Server Docs](https://agentcall.co/docs/mcp): Hosted and local MCP server setup
- [SMS for AI Agents](https://agentcall.co/docs/agent-sms): Give your agent a number it can text from: send with one call, read replies by polling or webhook push, act mid-conversation. Framework-agnostic with curl examples.
- [Writing System Prompts for AI Voice Calls](https://agentcall.co/docs/voice-prompts): Structure that prevents hallucination, plus 5 ready-made templates
- [Hermes on the Phone](https://agentcall.co/docs/hermes): Pre-call context webhook setup for agents like Hermes
- [OpenClaw Integration](https://agentcall.co/docs/openclaw): Two env vars and OpenClaw auto-discovers all 60 phone tools
- [Post-Call Webhook](https://agentcall.co/docs/post-call-webhook): Subscribe to `call.transcript` to feed transcripts and LLM summaries back into your agent after every call
- [Auditable Call Memory](https://agentcall.co/docs/memory): Contacts, Call Reports, source-backed memory, briefs inbox, contextSource modes, and the `call.report.ready` webhook
- [Cross-Call Memory Landing](https://agentcall.co/cross-call-memory): Product overview of Auditable Call Memory for AI phone agents
- [AgentCall on Smithery](https://smithery.ai/server/agentcall/agentcall): MCP server registry listing with 60 tools and 5 prompts
- [npm: @agentcall/mcp-server](https://www.npmjs.com/package/@agentcall/mcp-server): MCP server npm package
- [npm: agentcall](https://www.npmjs.com/package/agentcall): Node.js SDK
- [Pricing](https://agentcall.co/#pricing)
- [FAQ](https://agentcall.co/faq)
- [Blog](https://agentcall.co/blog)
- [Contact](https://agentcall.co/contact)
- [API Reference](https://api.agentcall.co/docs): Interactive OpenAPI docs

## Technical Details
- REST API with JSON responses. Bearer token authentication via API keys.
- Canonical call status lifecycle: `initiated` -> `ringing` -> `in-progress` -> `completed`, with terminal failure states `busy`, `no_answer`, `failed` for calls that never connect. Same vocabulary on REST call objects and the `call.status` webhook.
- Agent-to-agent calls (both numbers on the same account) expose `peerCallId` on call objects and in every call webhook payload, linking the outbound and inbound legs. Null for normal calls.
- Outbound calls (`POST /v1/calls/ai`, `POST /v1/calls/initiate`, the `initiate_ai_call` MCP tool, and the SDK's `initiateAI`) accept an optional `metadata` map (string-to-string, up to 24 keys, 64-char keys, 512-char values, 2KB serialized). Stored on the call, echoed on call objects, copied to the linked inbound leg of a same-account agent-to-agent call, and included verbatim in every webhook payload, so an orchestrator dialing many agent calls can tag each one with its own IDs instead of joining on callId and timestamps. Omitted entirely when not set.
- Hosted MCP server at `api.agentcall.co/mcp` (streamable HTTP transport).
- Webhook delivery for real-time events (SMS received, call incoming, OTP detected, call report ready).
- Multi-carrier infrastructure with automatic failover for reliability.
- All API keys are hashed (SHA-256) at rest. Plaintext shown once on creation.

## Contact
- Website: https://agentcall.co
- Customer support: support@agentcall.co
- Legal / business / privacy: contact@agentcall.co
- Dashboard: https://agentcall.co/dashboard