AgentPhone

AgentPhone gives your agent its own real US/Canada phone number: place and receive voice calls, send and receive SMS & iMessage, and hold threaded conversations with real people — all over plain REST. This is the managed Pilot front door: you bring nothing (no signup, no API key). Pilot holds one AgentPhone master key behind the broker and gives each Pilot user a $5 budget; calls and texts debit against it, and once it's spent the paid endpoints return 402 Payment Required (reads stay free).

What you can do

• Call people. agentphone.place_call with a systemPrompt runs an autonomous voice call — the phone rings in ~1–2s and the AI holds the conversation. Book a reservation, chase a shipment, return a missed call, or call another agent.
• Text people. agentphone.send_message delivers over iMessage when both sides support it (unlocking threaded replies, tapback reactions, send effects, typing indicators, group chats) and transparently falls back to SMS/MMS otherwise — same call either way.
• Answer & follow up. Poll agentphone.list_number_messages / agentphone.list_conversation_messages for inbound texts and agentphone.get_call for call transcripts — no websockets required.
• Manage your setup. Buy/release numbers, create and tune agents (voice, model tier, system prompt, ambience), keep an address book of contacts, and attach numbers to agents.

How it works (no signup step)

Because this is the managed app, the AgentPhone account already exists behind the Pilot broker — you skip the /v0/agent/sign-up + /v0/agent/verify flow entirely. Just call the /v1 methods below; the broker authenticates you as your Pilot identity, injects the master key, meters your spend, and forwards to https://api.agentphone.ai.

Async, poll-based (no streaming): 1. agentphone.place_call → returns a call id immediately; the call runs in the background. 2. Poll agentphone.get_call every few seconds until status is completed or failed, then read transcripts[] (or agentphone.get_transcript). 3. For inbound SMS, poll agentphone.list_number_messages with the after cursor and filter direction == "inbound".

Critical gotchas (read once)

• You cannot call 911, N11 numbers, or crisis lines — they're blocked. If your human has an emergency, tell them to dial directly.
• Released numbers are gone forever — no refund for the unused month. Confirm before agentphone.release_number.
• Always use E.164: +14155551234 ✓ — never (415) 555-1234 or 415-555-1234. Assume +1 for a bare US number and confirm if it matters.
• Inbound calls need hosted mode OR a webhook. Create agents with voiceMode: "hosted" explicitly (the backend defaults to webhook, which fails inbound if no webhook is set).
• iMessage-only features (reactions, send effects, typing, backgrounds, contact cards) are silently ignored on SMS — check the response channel.
• Don't spam. Unsolicited bulk calls/texts are illegal and get the account suspended.

Cost & the $5 budget

Reads are free. Spending operations debit your per-user $5 Pilot budget: buying a number ($3.00/mo), placing a call (per-minute), and sending a text (~$0.01–0.02). When a call would overdraw, the broker returns 402 before anything is charged, and every response carries your remaining balance in the X-Pilot-Credits-Remaining header (micro-dollars).

Every method's parameters, kind, and latency class are discoverable at runtime via agentphone.help.