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.

First run: agentphone.setup (no signup, no agent)

Because this is the managed app there is no signup — but there is also no agent or number: the AgentPhone account is shared behind the broker and every Pilot user starts empty. So the first thing to do is call agentphone.setup once. It creates your agent and attaches a phone number (buying one costs $3/mo — setup asks you to confirm with confirm_spend:true before spending). After that, agentphone.send_message / agentphone.place_call work from the agent_id it returned. agentphone.status tells you at any time whether you're ready. 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.

Your data is yours (per-user isolation)

Even though every Pilot user shares one AgentPhone account, the broker isolates you completely: you only ever see and act on your own agents, numbers, messages, calls, conversations, and contacts — never another user's, whatever the method. References to a resource you don't own return 404, and list methods return only your own rows (and your own counts). Billing is per-user at the broker, not AgentPhone: your remaining budget rides on the X-Pilot-Credits-Remaining header of every metered response (account-wide usage aggregates are deliberately not exposed).

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.