AgentCall

# AgentCall — Phone Numbers for AI Agents You have access to the AgentCall API for phone numbers, SMS, voice calls, and AI voice calls. ## Authentication All requests require: `Authorization: Bearer <AGENTCALL_API_KEY>` The API key is available in the `AGENTCALL_API_KEY` environment variable. ## Base URL `https://api.agentcall.co` For a complete plain-text API reference: `GET https://api.agentcall.co/llms.txt` ## Phone Numbers **Provision a number:** ``` POST /v1/numbers/provision Body: { "type": "local", "country": "US", "label": "my-agent" } Types: local ($2/mo), tollfree ($4/mo), mobile ($3/mo), sim ($8/mo, Pro only) Response: { "id": "num_xxx", "number": "+12125551234", "type": "local", ... } ``` **List numbers:** ``` GET /v1/numbers Query: ?limit=20&country=US&type=local ``` **Get number details:** ``` GET /v1/numbers/:id ``` **Release a number (irreversible):** ``` DELETE /v1/numbers/:id ``` ## SMS **Send SMS:** ``` POST /v1/sms/send Body: { "from": "num_xxx", "to": "+14155551234", "body": "Hello!" } "from" can be a number ID or E.164 phone string ``` **Get inbox:** ``` GET /v1/sms/inbox/:numberId Query: ?limit=20&otpOnly=true ``` **Get a specific message:** ``` GET /v1/sms/:messageId ``` **Wait for OTP code (long-polls up to 60 seconds):** ``` GET /v1/sms/otp/:numberId Query: ?timeout=60000 Response: { "otp": "482913", "message": { ... } } ``` ## Voice Calls **Start an outbound call:** ``` POST /v1/calls/initiate Body: { "from": "num_xxx", "to": "+14155551234", "record": false } ``` **Start an AI voice call (Pro plan, $0.20/min):** The AI handles the entire conversation autonomously based on your systemPrompt. ``` POST /v1/calls/ai Body: { "from": "num_xxx", "to": "+14155551234", "systemPrompt": "You are calling to schedule a dentist appointment for Tuesday afternoon.", "voice": "alloy", "firstMessage": "Hi, I'd like to schedule an appointment please.", "maxDurationSecs": 600 } Voices (pick based on user's desired tone): - alloy: neutral, balanced (default) - ash: warm, conversational - ballad: expressive, melodic - coral: clear, professional - echo: resonant, deep - sage: calm, authoritative, confident - shimmer: bright, energetic - verse: smooth, articulate ``` **List call history:** ``` GET /v1/calls Query: ?limit=20 ``` **Get call details:** ``` GET /v1/calls/:callId ``` **Get AI call transcript:** ``` GET /v1/calls/:callId/transcript Response: { "entries": [{ "role": "assistant", "text": "...", "timestamp": "..." }], "summary": "..." } ``` **Hang up an active call:** ``` POST /v1/calls/:callId/hangup ``` ## Webhooks **Register a webhook:** ``` POST /v1/webhooks Body: { "url": "https://example.com/hook", "events": ["sms.inbound", "sms.otp", "call.status"] } Events: sms.inbound, sms.otp, call.inbound, call.ringing, call.status, call.recording, number.released ``` **List webhooks:** ``` GET /v1/webhooks ``` **Rotate webhook secret:** ``` POST /v1/webhooks/:id/rotate ``` **Delete a webhook:** ``` DELETE /v1/webhooks/:id ``` ## Usage & Billing **Get usage breakdown:** ``` GET /v1/usage Query: ?period=2026-02 ``` ## Phone Number Format All phone numbers must be E.164: `+{country code}{number}`, e.g. `+14155551234` ## Common Workflows ### Test your app's SMS verification (QA) 1. `POST /v1/numbers/provision` with `{ "type": "local" }` — get a test number 2. Enter the number into your staging app's verification form 3. `GET /v1/sms/otp/:numberId?timeout=60000` — wait for the verification code 4. Assert the code arrives and your app accepts it 5. `DELETE /v1/numbers/:id` — release the test number ### AI voice call 1. `POST /v1/numbers/provision` with `{ "type": "local" }` — get a number (if you don't have one) 2. `POST /v1/calls/ai` with `{ "from": "num_xxx", "to": "+1...", "systemPrompt": "..." }` — start the call 3. Wait for the call to complete 4. `GET /v1/calls/:callId/transcript` — get the full conversation transcript ## Error Codes - **401**: Invalid or missing API key - **403 plan_limit**: Plan limit reached (upgrade to Pro at agentcall.co/dashboard) - **404**: Resource not found - **422**: Validation error (check request body) - **429**: Rate limit exceeded (100 req/min)