agentcall

by kintupercy

Install this Skill

curl -fsSL -o agentcall.zip https://skill.seembox.com/api/v1/skills/agentcall/download && unzip agentcall.zip

SKILL.md About

# AgentCall — Phone Numbers for AI Agents

You have access to the AgentCall API for phone numbers, SMS, voice calls, and AI voice calls. Inbound and outbound calls can both be answered or initiated by an AI voice agent.

## Authentication

All authenticated 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` (no auth required).

## Cost & Safety — Confirm Before Acting

Several tools below take real-world actions on the user's behalf. Confirm with the user before invoking them, and stay within the scope of what they explicitly asked you to do.

**Billable actions (cost real money — confirm scope first):**
- `POST /v1/numbers/provision` — recurring monthly cost ($2.00–$2.50/month depending on type). Confirm the user wants a new number; ask which type, country, and label before provisioning.
- `POST /v1/sms/send` — $0.015/message on Pro (10/month free on Free plan). Confirm the recipient number and the message body before sending.
- `POST /v1/calls/initiate` — $0.035/min on Pro. Confirm the destination number and purpose before dialing. Optional `record: true` adds $0.01/min on top.
- `POST /v1/calls/ai` — $0.40/min on Pro. Confirm the destination, the system prompt, and `maxDurationSecs` before dialing — outbound AI calls reach a real human and accumulate cost per minute.
- Inbound AI voice (`POST /v1/numbers/:id/inbound-config` with `mode: "ai"`) — $0.40/min on every incoming call to that number. Confirm the user wants inbound AI enabled on this specific number, and that the system prompt accurately describes their business.
- Optional `record: true` on AI voice paths — $0.01/min on top of the AI rate. Mention this delta when proposing recording.

**Irreversible actions:**
- `DELETE /v1/numbers/:id` — releases the number permanently. The same number cannot be re-provisioned. Always confirm before releasing, and warn the user that this is irreversible.
- `POST /v1/calls/:callId/hangup` — terminates an in-flight call. Usually fine but confirm if the call may still be progressing toward its goal.

**External-effect actions (contact real people):**
- Sending SMS, initiating outbound calls, and AI voice calls reach real recipients on real networks. Don't initiate these speculatively. The receiving party should be expecting contact, or the user should explicitly authorize the outreach.
- For two-party-consent states (CA, FL, IL, MD, MA, PA, WA, NV, NH, MT, CT, DE), recording requires disclosure. AgentCall auto-prepends "This call may be recorded for quality." to the spoken `firstMessage` when `record: true` is set on AI voice paths and the message doesn't already mention recording — but you should still mention recording in firstMessage content for clarity if the user is writing one from scratch.

**Built-in API guardrails (don't rely on these as your only check):**
- Free plan hard caps: 1 number, 10 SMS/month, 5 voice minutes/month, 5 OTP extractions/month — prevents runaway spend on the free tier.
- Pro plan billable features (inbound/outbound AI voice, call recording) require a payment method on file. The API returns 402 with a `setupUrl` if not present — surface this to the user instead of looping.
- Rate limits: 100 req/min global; per-route limits on expensive endpoints (10 req/min on AI voice, 20 req/hour on uploads).
- Carrier restrictions: AI voice (in or out) and inbound AI configuration are US/Canada-only; the API returns 400 `carrier_not_supported` for other countries.

If the user's request is ambiguous (e.g. "set up a phone number" with no type or country, or "send a text" with no recipient), ask one or two clarifying questions before invoking a billable tool.

## Phone Numbers

**Provision a number:**
```
POST /v1/numbers/provision
Body: { "type": "local", "country": "US", "label": "my-agent" }
Types: local ($2/mo), tollfree ($2.50/mo), mobile ($2/mo). All numbers are VoIP-routed via licensed US carriers; not for consumer-platform signup verification (Stripe, WhatsApp, Google, banks).
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
```

## Inbound AI Voice (Pro plan, $0.40/min, US and Canada numbers only)

Configure a phone number so incoming calls are answered autonomously by an AI voice agent. The AI follows the system prompt you set.

After every call, AgentCall summarizes the transcript with an LLM and emails a plain-English summary — caller name (when given), phone, urgency tag, and a 1-2 sentence ask — to an address you configure on the number. Spam calls are auto-suppressed from the email. The structured `call.transcript` webhook event still fires in parallel for programmatic consumers.

**Configure inbound AI on a number:**
```
POST /v1/numbers/:numberId/inbound-config
Body: {
  "mode": "ai",
  "systemPrompt": "You are the front desk for Acme Plumbing. Greet the caller warmly, take their name and a brief description of the issue, then say someone will call back within 24 hours.",
  "voice": "shimmer",
  "firstMessage": "Hi, thanks for calling Acme Plumbing. How can I help?",
  "maxDurationSecs": 300,
  "notify": {
    "emailTo": "owner@acmeplumbing.com",
    "businessName": "Acme Plumbing",
    "agencyName": "Acme Plumbing"
  }
}
```

The `notify` block is optional. Set `notify.emailTo` to receive the post-call summary email; `businessName` is shown in the email subject; `agencyName` is the sign-off line. The MCP `configure_inbound_ai` tool also accepts `notify` — agents in Claude Desktop, Cursor, Windsurf, etc. can configure the email destination in the same call as the system prompt, no dashboard handoff needed.

**Optional call recording (Pro plan, $0.01/min on top of the AI voice rate):**
Add `record: true` to the body above (or flick the toggle on the dashboard's `/numbers` config form) to record every inbound call to this number. Recordings live in your AgentCall dashboard for 1 year and are listenable from the Logs → Calls tab or via `GET /v1/calls/:callId/recording` (returns a fresh short-lived signed URL). The `call.recording` webhook fires when each recording is ready. The same `record` flag is supported on outbound AI voice (`POST /v1/calls/ai`). When recording is on, AgentCall auto-prepends a TCPA-compliant disclosure to the spoken `firstMessage` if it doesn't already mention recording.

**Get current inbound config:**
```
GET /v1/numbers/:numberId/inbound-config
```

**Disable inbound AI (calls hang up at carrier):**
```
DELETE /v1/numbers/:numberId/inbound-config
```

## Browse Voices and Prompt Templates (no auth)

Both endpoints are public — call them before configuring AI voice to avoid hallucinated business details and to pick a voice that fits the use case.

**List the 8 voices with samples:**
```
GET /v1/calls/voices
Returns: { voices: [{ id, name, trait, description, bestFor, sampleUrl }, ...], defaultVoice: "shimmer" }
```

**List ready-made prompt templates:**
```
GET /v1/calls/prompt-templates
Returns 5 templates with [BRACKETED] placeholders to fill in:
- receptionist (Front Desk) — recommends shimmer voice
- lead-qualifier (Sales, BANT-style) — coral
- appointment-booker — sage
- customer-support (FAQ Deflection) — ash
- call-screener (Anti-Spam) — verse
Each entry includes: id, title, description, recommendedVoice, maxDurationSecs, firstMessage, systemPrompt.
```

For a comprehensive prompt-writing guide: https://agentcall.co/docs/voice-prompts

## 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": { ... } }
```

## Outbound Voice Calls

**Start a standard outbound call:**
```
POST /v1/calls/initiate
Body: { "from": "num_xxx", "to": "+14155551234", "record": false }
```

**Start an outbound AI voice call (Pro plan, $0.40/min — billable, contacts real human, confirm with user first):**
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": "shimmer",
  "firstMessage": "Hi, I'd like to schedule an appointment please.",
  "maxDurationSecs": 600,
  "record": false
}
```
Add `record: true` to capture an mp3 of the call — adds $0.01/min on top.

Voices (default: shimmer; preview each via GET /v1/calls/voices):
- shimmer: bright, energetic — recommended starting point (default)
- sage: calm, authoritative, confident — healthcare, finance, advisory
- ash: warm, conversational — customer service, support lines
- ballad: expressive, melodic — engaging, narrative conversations
- coral: clear, professional — B2B calls, sales
- echo: resonant, deep — formal inquiries, executive comms
- verse: smooth, articulate — premium/luxury, executive communication
- alloy: neutral, balanced — generic notifications, IVR-style flows

**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": "ai" | "human", "text": "...", "timestamp": "..." }], "summary": "...", "duration": 111 }
```

**Hang up an active call:**
```
POST /v1/calls/:callId/hangup
```

## Webhooks

> **Important: webhooks here are for OUTBOUND event delivery, NOT inbound call routing.**
> AgentCall POSTs to your URL when events fire (SMS received, OTP detected, call completed,
> recording ready, etc.). Webhooks are NOT how you make a phone number answer incoming calls.
> To configure how a number answers when called, use the **Inbound AI Voice** section above
> (`POST /v1/numbers/:numberId/inbound-config`) — not webhooks. (If you're coming from Twilio:
> AgentCall replaces Twilio's inbound voice webhook URL with `configure_inbound_ai`.)

**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, call.transcript, 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-04
```

Pricing (per use, Pro plan):
- SMS outbound: $0.015/msg
- SMS inbound: $0.008/msg
- Voice (standard outbound): $0.035/min
- Voice (standard inbound): $0.015/min
- AI voice (outbound): $0.40/min
- AI voice (inbound): $0.40/min
- Call recording: $0.01/min

## Phone Number Format

All phone numbers must be E.164: `+{country code}{number}`, e.g. `+14155551234`

## Common Workflows

### Set up an AI receptionist on a phone number
1. `POST /v1/numbers/provision` with `{ "type": "local" }` — get a number
2. `GET /v1/calls/prompt-templates` — pick a template (e.g. "receptionist")
3. Replace `[BRACKETED]` placeholders with the customer's real business details
4. `POST /v1/numbers/:numberId/inbound-config` with `{ "mode": "ai", "systemPrompt": "...", "voice": "shimmer", "firstMessage": "..." }`
5. Anyone who calls the number is now answered by the AI agent
6. `GET /v1/calls` to see incoming call history; `GET /v1/calls/:callId/transcript` for transcripts

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

### Make an outbound 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
- **402 payment_method_required**: Add a card before configuring billable features (returns `setupUrl` to Stripe Checkout)
- **403 plan_limit_voice_ai**: Inbound/outbound AI voice requires Pro plan ($19.99/mo)
- **403 plan_limit_***: Other plan limits — upgrade at agentcall.co/dashboard
- **400 carrier_not_supported**: Inbound AI voice is only supported on US and Canada numbers
- **404**: Resource not found
- **422**: Validation error (check request body)
- **429**: Rate limit exceeded (100 req/min global; per-route limits on expensive endpoints)
- **503 voice_ai_unavailable**: Server-side OpenAI key issue — retry later

_meta.json Metadata

{
  "ownerId": "kn7d072cygf11v6hx13rfnmmcx81nwys",
  "publishedAt": 1778189392826,
  "slug": "agentcall",
  "version": "2.1.8"
}