{"id":"efb8116e-e889-4907-95f1-8bdbd308c426","entityType":"agent","slug":"clawhub-kintupercy-agentcall","name":"AgentCall","canonicalUrl":"https://www.xpersona.co/agent/clawhub-kintupercy-agentcall","canonicalPath":"/agent/clawhub-kintupercy-agentcall","generatedAt":"2026-10-09T12:45:30.073Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:27:53.685Z","emptyReason":null},"description":"Give your agent real phone numbers for SMS, OTP verification, and voice calls via the AgentCall API.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 4.4K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17ekr7wpa5bzmkg50krp4tre183tpgg:agentcall","sourceUrl":"https://clawhub.ai/kintupercy/agentcall","homepage":"https://clawhub.ai/kintupercy/skills/agentcall","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/kintupercy/agentcall","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/kintupercy/skills/agentcall","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":54,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"AgentCall technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:27:53.685Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:27:53.685Z","emptyReason":null},"stars":null,"forks":null,"downloads":4395,"packageName":null,"latestVersion":"2.13.1","tractionLabel":"4.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:27:53.685Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T05:27:53.685Z","lastCrawledAt":"2026-10-09T05:27:53.685Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T05:27:53.685Z","lastVerifiedAt":null,"highlights":[{"version":"2.13.1","createdAt":"2026-09-08T17:59:43.811Z","changelog":"Align all agents with the card-verified 72-hour live trial, five inbound AI minutes total, five verified-destination SMS attempts, legacy monthly account terms, and get_plan-first instructions.","fileCount":5,"zipByteSize":66514},{"version":"2.13.0","createdAt":"2026-08-25T19:16:45.703Z","changelog":"v2.13.0: get_plan + upgrade_to_pro tools so an agent can help its human upgrade (checkout link only, nothing charged until the human completes it, confirm before acting). Every plan_limit_* error carries upgradeUrl + upgradeToolName. Plain outbound calls are Pro only, callers hear a short message when a Free number is out of trial minutes, 3-per-day redial cap per destination. 62 tools.","fileCount":5,"zipByteSize":64140},{"version":"2.12.9","createdAt":"2026-08-11T22:29:22.109Z","changelog":"Provisioning failures no longer lock you out: the hourly budget counts numbers actually received, so carrier errors and empty area codes cost nothing. 429 now carries Retry-After. provision_number is no longer auto-retried after an ambiguous failure (a replay could buy a second number); call list_numbers first. Documents provisioning_rate_limit, no_numbers_in_area_code, carrier_error.","fileCount":5,"zipByteSize":62013},{"version":"2.12.8","createdAt":"2026-08-11T15:11:58.150Z","changelog":"SMS threads now carry recency: get_sms_conversation returns a context object splitting the thread into recent (7 days), recent-substantive (greetings removed), and older messages with ages, so agents stop describing a months-old exchange as a recent conversation. Relay mode gets the same classified thread as an additive smsContext push.","fileCount":5,"zipByteSize":60983},{"version":"2.12.7","createdAt":"2026-08-10T18:49:48.306Z","changelog":"Free tier is now 20 outbound SMS/month (was 10). Relay mode (text your own agent) works on Free and draws from that same allowance; two-way AI SMS stays Pro. configure_inbound_ai now states the plan per SMS mode and warns that 'ai' on Free is accepted but silently never answers. Still 60 tools.","fileCount":5,"zipByteSize":59639},{"version":"2.12.6","createdAt":"2026-08-10T00:55:45.121Z","changelog":"get_message returns real delivery status (queued/sent/delivered/failed + errorCode); get_number gains messaging state for A2P registration; 40010 troubleshooting guidance. No new tools; still 60.","fileCount":5,"zipByteSize":59532},{"version":"2.12.5","createdAt":"2026-08-09T06:18:40.019Z","changelog":"Transfer to a human on inbound AI voice: configure_inbound_ai gains optional transferTo (E.164). The AI hands the live call to a real person when the caller asks, with a take-a-message fallback if nobody answers in ~25s. No new tools; still 60.","fileCount":5,"zipByteSize":57852},{"version":"2.12.4","createdAt":"2026-08-09T01:10:30.854Z","changelog":"Documents the Free-tier SMS starter allowance: a Free account may text up to 10 distinct new numbers, lifetime (SMS only, content-screened). Corrects the New-Account Outbound Restriction section, which wrongly said no new account may contact an arbitrary number. Adds the 403 sms_starter_exhausted error code with do-not-retry guidance. No new tools; still 60.","fileCount":5,"zipByteSize":57046}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17ekr7wpa5bzmkg50krp4tre183tpgg:agentcall","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17ekr7wpa5bzmkg50krp4tre183tpgg:agentcall` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/kintupercy/agentcall before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T12:45:30.068Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kintupercy-agentcall/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:27:53.685Z","emptyReason":null},"readme":"Skill: AgentCall\n\nOwner: kintupercy\n\nSummary: Give your agent real phone numbers for SMS, OTP verification, and voice calls via the AgentCall API.\n\nTags: ai-voice:2.0.0, api:2.0.0, calls:2.0.0, latest:2.13.1, otp:2.0.0, phone:2.0.0, sms:2.0.0, verification:2.0.0, voice:2.0.0\n\nVersion history:\n\nv2.13.1 | 2026-09-08T17:59:43.811Z | user\n\nAlign all agents with the card-verified 72-hour live trial, five inbound AI minutes total, five verified-destination SMS attempts, legacy monthly account terms, and get_plan-first instructions.\n\nv2.13.0 | 2026-08-25T19:16:45.703Z | user\n\nv2.13.0: get_plan + upgrade_to_pro tools so an agent can help its human upgrade (checkout link only, nothing charged until the human completes it, confirm before acting). Every plan_limit_* error carries upgradeUrl + upgradeToolName. Plain outbound calls are Pro only, callers hear a short message when a Free number is out of trial minutes, 3-per-day redial cap per destination. 62 tools.\n\nv2.12.9 | 2026-08-11T22:29:22.109Z | user\n\nProvisioning failures no longer lock you out: the hourly budget counts numbers actually received, so carrier errors and empty area codes cost nothing. 429 now carries Retry-After. provision_number is no longer auto-retried after an ambiguous failure (a replay could buy a second number); call list_numbers first. Documents provisioning_rate_limit, no_numbers_in_area_code, carrier_error.\n\nv2.12.8 | 2026-08-11T15:11:58.150Z | user\n\nSMS threads now carry recency: get_sms_conversation returns a context object splitting the thread into recent (7 days), recent-substantive (greetings removed), and older messages with ages, so agents stop describing a months-old exchange as a recent conversation. Relay mode gets the same classified thread as an additive smsContext push.\n\nv2.12.7 | 2026-08-10T18:49:48.306Z | user\n\nFree tier is now 20 outbound SMS/month (was 10). Relay mode (text your own agent) works on Free and draws from that same allowance; two-way AI SMS stays Pro. configure_inbound_ai now states the plan per SMS mode and warns that 'ai' on Free is accepted but silently never answers. Still 60 tools.\n\nv2.12.6 | 2026-08-10T00:55:45.121Z | user\n\nget_message returns real delivery status (queued/sent/delivered/failed + errorCode); get_number gains messaging state for A2P registration; 40010 troubleshooting guidance. No new tools; still 60.\n\nv2.12.5 | 2026-08-09T06:18:40.019Z | user\n\nTransfer to a human on inbound AI voice: configure_inbound_ai gains optional transferTo (E.164). The AI hands the live call to a real person when the caller asks, with a take-a-message fallback if nobody answers in ~25s. No new tools; still 60.\n\nv2.12.4 | 2026-08-09T01:10:30.854Z | user\n\nDocuments the Free-tier SMS starter allowance: a Free account may text up to 10 distinct new numbers, lifetime (SMS only, content-screened). Corrects the New-Account Outbound Restriction section, which wrongly said no new account may contact an arbitrary number. Adds the 403 sms_starter_exhausted error code with do-not-retry guidance. No new tools; still 60.\n\nv2.12.3 | 2026-08-08T03:35:34.394Z | user\n\nPremium Voice language parity: all 31 language presets provisioned on the premium agent (verified by config readback + a live Hungarian premium call), copy moves from 12 languages to the same 31 as standard. No new tools; still 60.\n\nv2.12.2 | 2026-08-06T03:24:54.106Z | user\n\nDocuments the new-account outbound restriction (403 destination_not_verified), which was previously undocumented. Explains what a restricted account CAN already do, the business-verification fast path, per-number code verification, and the automatic 7-day expiry. Tells agents not to retry or probe other numbers, and to ask the user for real business details.\n\nv2.12.1 | 2026-08-05T19:21:06.846Z | user\n\nCorrected the inbound-only claim on two-way AI SMS and relay mode: a number can also text someone first via send_sms or create_schedule. Removed an incorrect smsMode 'ai' precondition on create_schedule. Documented the consent and spend guardrails on the proactive path (Pro only, STOP always skipped, 200 sends per number per day). Free-plan figures corrected to 10 outbound SMS/month.\n\nv2.12.0 | 2026-06-11T01:43:27.267Z | auto\n\n- Premium Voice now applies to both inbound calls and outbound AI calls from the same number.\n- Updated SKILL.md to clarify billing and applicability for Premium Voice.\n- Minor text corrections and clarifications throughout documentation.\n- Removed obsolete skill-card.md file.\n\nv2.11.0 | 2026-06-10T13:20:47.147Z | auto\n\n- Removed outdated skill-card.md.\n- Updated SKILL.md and instructions.md content for clarity and accuracy.\n- Modified claw.json to reflect recent configuration changes.\n\nv2.10.0 | 2026-06-08T14:04:18.330Z | user\n\nProactive scheduling: create_schedule/list_schedules/cancel_schedule (appointment reminders + recurring digests). Ships @agentcall/mcp-server@0.14.0 + agentcall@0.9.1. 58 tools.\n\nv2.9.0 | 2026-06-07T00:03:59.514Z | user\n\nv2.9.0: Two-way AI SMS and relay mode. configure_inbound_ai gains smsMode (off/ai/relay), smsSystemPrompt, actionWebhook, tools, agentWebhook, allowedSenders. Three new SMS conversation tools (list_sms_conversations, get_sms_conversation, reply_to_sms_conversation). New REST /v1/sms-conversations read+reply endpoints and sms.ai_reply webhook. Total tools 55 (was 52). Ships with @agentcall/mcp-server@0.13.0 and agentcall@0.9.0.\n\nv2.8.2 | 2026-06-06T04:42:59.475Z | user\n\nDocument notify.smsTo on configure_inbound_ai: optional owner SMS call summaries alongside emailTo. Updated inbound config example and notify guidance.\n\nv2.8.1 | 2026-06-02T17:23:39.418Z | user\n\nv2.8.1: patch from post-ship review. No tool/schema/behavior change (still 52 tools). SDK gender union tightened, 404 documented on premium-voice docstrings, npm startup banner count fixed. Ships with @agentcall/mcp-server@0.12.1 + agentcall@0.8.1.\n\nv2.8.0 | 2026-06-02T16:18:23.808Z | user\n\nv2.8.0: agents can now ENABLE Premium Voice, not just browse it. New MCP tools set_premium_voice / disable_premium_voice / list_premium_voices (52 tools total) with the billable-add-on confirm-the-rate guardrail; mirrors new SDK methods. Ships with @agentcall/mcp-server@0.12.0 + agentcall@0.8.0.\n\nv2.7.1 | 2026-06-02T15:44:36.381Z | user\n\nDocumented GET /v1/calls/premium-voices in the Browse Voices section so agents can list premium voices.\n\nv2.7.0 | 2026-06-02T15:28:33.843Z | user\n\nPremium Voice (powered by ElevenLabs): 12 voices for inbound AI receptionists at $0.59/min, dashboard-enabled. Ships with mcp-server 0.11.0.\n\nv2.6.0 | 2026-05-26T04:00:38.263Z | user\n\nv2.6.0: useSavedAgent + idempotencyKey on initiate_ai_call for CSV-runner workflows. Hydrate omitted fields from the saved outbound agent (per-call overrides win). Replay duplicate requests with the same key. Tool count remains 49. Ships with @agentcall/mcp-server@0.10.0 + agentcall@0.7.0.\n\nv2.5.0 | 2026-05-26T02:55:32.987Z | user\n\nv2.5.0: Added set_outbound_defaults, get_outbound_defaults, clear_outbound_defaults tools. Save a reusable outbound AI agent on a phone number so the dashboard Place AI call dialog and any MCP client hydrate from it instead of retyping for every outbound call from the same number. The outbound field is now returned on every list_numbers and get_number response. Total tools 49 (was 46). Ships with @agentcall/mcp-server@0.9.0 and agentcall@0.6.0.\n\nv2.4.1 | 2026-05-26T01:11:25.496Z | user\n\nNew follow-up-on-call MCP prompt that mirrors the dashboard 'Follow up with AI' button. Ships with @agentcall/mcp-server@0.8.1.\n\nv2.4.0 | 2026-05-26T00:38:14.994Z | user\n\nMultilingual AI voice on inbound + outbound (12 languages + auto-detect), new update_number_language MCP tool, 3 new outbound prompt templates, ?direction filter on prompt-templates. Ships with @agentcall/mcp-server@0.8.0 and agentcall@0.5.0.\n\nv2.3.1 | 2026-05-19T21:02:02.224Z | user\n\nSchema-drift fix on 5 MCP tool output shapes (webhook rotate, webhook create isActive, get_call_report candidates, get_call_transcript 202, PATCH /v1/memory/:id projection). Plus inboundAiConfigOutputSchema BYOK fields now correctly declared inside config. Ships with @agentcall/mcp-server@0.7.1 and agentcall@0.4.1.\n\nv2.3.0 | 2026-05-19T00:09:26.651Z | user\n\nadded set_byok_openai_key + disable_byok tools (44 tools total). configure_inbound_ai response now exposes voiceMode + hasByokKey + byokOpenaiApiKeyPreview. Inbound AI is per-number configurable in two billing modes: Managed ($0.40/min) or BYOK ($0.10/min). Memory included on both modes. Ships with @agentcall/mcp-server@0.7.0.\n\nv2.2.3 | 2026-05-17T01:00:10.188Z | user\n\nv2.2.3 — customer-controlled cross-call memory toggle: set_memory_enabled tool + PATCH /v1/account + dashboard switch on /dashboard. Free and Pro both default to on; Free is naturally capped by the 5-minute monthly inbound AI trial.\n\nv2.2.2 | 2026-05-17T00:39:10.006Z | user\n\nv2.2.2: Smithery score work. Added optional AGENTCALL_BASE_URL + AGENTCALL_TIMEOUT_MS env vars (wired to SDK config) and swept missing input-parameter descriptions on update_contact, update_memory, list_call_reports, list_briefs. Ships with @agentcall/mcp-server@0.6.2. No tool behavior change.\n\nv2.2.1 | 2026-05-17T00:22:49.476Z | user\n\nv2.2.1: Tightened MCP outputSchema on get_call_report.payload and get_memory_timeline events (before/after). Mirrors @agentcall/mcp-server@0.6.1. No tool behavior change; schema-only patch for Smithery / static-analyzer typing quality.\n\nv2.2.0 | 2026-05-17T00:07:52.885Z | user\n\nv2.2.0: Auditable Call Memory. 20 new endpoints + 19 new MCP tools (42 total). Every AI call auto-extracts into structured memory with cross-call recognition. Includes the killer get_next_call_context tool for pre-call lookup. Hosted MCP + npm @agentcall/mcp-server bumped to 0.6.0 in lockstep. SDK agentcall@0.3.0 adds client.contacts, client.memory, client.reports, client.briefs. Feature opt-in per agent via memoryEnabled flag (default false).\n\nv2.1.19 | 2026-05-14T00:24:29.902Z | user\n\nFixed outputSchema drift on list_calls (callListItemShape uses hasRecording boolean, separate from callShape's recordingUrl). Ships in @agentcall/mcp-server 0.4.19 and hosted MCP.\n\nv2.1.18 | 2026-05-13T22:26:29.556Z | user\n\nPost-call transcript webhook (call.transcript event) documented end-to-end. New Webhooks subsection covers subscribe + HMAC verify + dedup on callId + 3 integration patterns (store, forward, queue-for-local-agent). Reference bridge v0.2.0 ships POST /agentcall/transcript and POST /hermes/pull-transcripts for local agent platforms. Full walkthrough at /docs/post-call-webhook.\n\nv2.1.17 | 2026-05-13T05:05:25.381Z | user\n\nconfigure_inbound_ai officially accepts contextWebhook. AgentCall POSTs to your HTTPS URL on every inbound call connect (HMAC-signed); the response's contextBlock is merged onto the systemPrompt before the AI answers. Use this to inject a live brief or current priorities so the AI speaks with up-to-date context. Fail-open on errors. Setup walkthrough at https://agentcall.co/docs/hermes.\n\nv2.1.16 | 2026-05-13T04:03:00.161Z | user\n\nExpanded the voice catalog labels embedded in MCP tool descriptions so agents see a trait and best-fit use case for every voice (previously only marin, cedar, and shimmer had inline labels; the remaining seven were bare names). Applies to configure_inbound_ai, update_number_voice, initiate_ai_call, and the ai-outbound-call prompt.\n\nv2.1.15 | 2026-05-13T03:20:16.693Z | user\n\nAdded a partial-update path on PATCH /v1/numbers/:id for changing just the inbound AI voice (or just the label) without touching the rest of the inbound config. Use this when the user asks to switch voices on an existing receptionist; systemPrompt, firstMessage, recording flag, and notify email block are preserved. Full-replace POST /v1/numbers/:id/inbound-config is still the right tool for first-time setup or multi-field changes.\n\nv2.1.14 | 2026-05-09T22:49:56.101Z | user\n\nDrop the risk-restatement paragraph that ClawScan v2.4.22 quoted as the Rogue Agents Concern on v2.1.13. Keep the pre-flight checklist and the monitor/disable obligation. Section header now mirrors the scanner's recommendation language word-for-word.\n\nv2.1.13 | 2026-05-09T22:36:39.337Z | user\n\nAddress ClawScan v2.4.22 Rogue Agents finding. Added a dedicated 'Persistent Inbound AI Configuration: Confirm Before Enabling, Monitor After' subsection with a 6-item pre-config checklist and a post-config monitor/disable obligation. Plus full em-dash sweep on the instructions.\n\nv2.1.12 | 2026-05-09T15:59:46.891Z | user\n\nVoice catalog 8 -> 10 (added marin and cedar, the newest natural-sounding picks). Fixed silent-greeting bug on the AI receptionist. Removed remaining vendor mentions from public copy.\n\nv2.1.11 | 2026-05-09T02:54:02.486Z | user\n\nv2.1.11: Free inbound AI trial is strictly trial-only (no overage path on Free). Once exhausted, calls hang up until next month resets, OR upgrade to Pro for unlimited inbound AI. Cleaner trial-to-upgrade funnel.\n\nv2.1.10 | 2026-05-09T00:23:13.707Z | user\n\nv2.1.10: Two corrections. Removed 'post-call email summaries' from paidFeatures (they fire on any plan when inbound AI is configured, not Pro-exclusive). Tightened 'unlimited numbers' to call out toll-free + mobile as Pro-only types so the Free local-only API gate is reflected.\n\nv2.1.9 | 2026-05-08T23:30:36.500Z | user\n\nv2.1.9: Inbound AI voice now has a 5-minute monthly Free trial with no card required. Past the trial: $0.40/min with payment method, or unlimited on Pro. Updated billing notice, paidFeatures, Cost & Safety section, and 403 error reference accordingly.\n\nv2.1.8 | 2026-05-07T21:29:52.826Z | user\n\nRemoved specific carrier vendor names from public-facing copy. Numbers are now described as VoIP-routed via 'licensed US carriers' instead of naming the underlying providers. Internal infrastructure detail isn't useful product copy and shouldn't be on the public surface.\n\nv2.1.7 | 2026-05-07T21:20:50.556Z | user\n\nFollowup to v2.1.6: set the platform-stored skill summary (previously stuck on the original Feb 2026 'real phone numbers for OTP verification' line which implied external-platform verification works). New summary scopes to honest capabilities (AI receptionist + email summaries + programmable phone/SMS, VoIP-routed). Description expanded to call out 'OTP for apps you control' and explicit non-fit for consumer-platform signup verification (Stripe, WhatsApp, banks).\n\nv2.1.6 | 2026-05-07T21:17:08.081Z | user\n\nRemoved false-advertising claims about SIM-backed numbers. Numbers are VoIP-routed via Telnyx and Twilio, not real SIM cards, and consumer platforms that block VoIP for signup (Stripe, WhatsApp, Google, banks) will reject them. Real eSIM integration is on the roadmap. Dropped the 'sim' type from the provision types list and removed 'SIM numbers' from paidFeatures.\n\nv2.1.5 | 2026-05-06T18:09:59.868Z | user\n\nCost & Safety section addresses ClawScan v2.4.22 finding on tool misuse — instructions.md now tells the AI agent to confirm with the user before invoking billable, irreversible, or external-effect tools, plus documents existing rate limits / plan caps / payment-method gates as baseline guardrails. Bundles three more updates: opt-in call recording on AI voice paths ($0.01/min, 1-year retention, dashboard playback, TCPA auto-disclosure); de-emphasized 'OpenAI Realtime' in user-facing copy (now 'AI voice agent'); removed the stale 'MCP doesn't expose notify yet' caveat (it does now).\n\nv2.1.4 | 2026-05-06T05:01:15.821Z | user\n\nSurface the post-call email summary as a Pro deliverable in the description, paidFeatures, and instructions. After every inbound AI call, AgentCall emails the configured address a plain-English summary (caller name, phone, intent, urgency, callback time). Notify block now shown in the inbound-config example. MCP/SDK exposure of notify is on the next minor release.\n\nv2.1.2 | 2026-04-29T19:53:37.012Z | user\n\nReplace internal carrier names with user-friendly geographic phrasing in copy.\n\nv2.1.1 | 2026-04-29T15:48:19.215Z | user\n\nRestore display name (was reset to generic placeholder in 2.1.0). Same content as 2.1.0 — inbound AI voice, voice catalog endpoint, prompt templates, 21 tools.\n\nv2.1.0 | 2026-04-29T15:47:38.966Z | user\n\nInbound AI voice — configure any Telnyx number to be answered by an OpenAI Realtime voice agent. Added GET /v1/calls/voices (8-voice catalog with sample MP3s) and GET /v1/calls/prompt-templates (5 ready-made templates: receptionist, lead qualifier, appointment booker, customer support, call screener). 21 tools total (was 19 — added configure_inbound_ai + disable_inbound_ai). Default voice now shimmer (was alloy). Fixed outdated tollfree/mobile pricing.\n\nv2.0.4 | 2026-04-27T06:44:28.334Z | user\n\nUpdate Pro pricing to $19.99/mo and clarify Free tier is never charged\n\nArchive index:\n\nArchive v2.13.1: 5 files, 66514 bytes\n\nFiles: claw.json (46213b), instructions.md (65122b), skill-card.md (3109b), SKILL.md (65122b), _meta.json (129b)\n\nFile v2.13.1:SKILL.md\n\n# AgentCall: Phone Numbers for AI Agents\n\n<!-- BEGIN GENERATED OFFER POLICY -->\n## Current offer and agent behavior\n\nNew accounts receive a one-time 72-hour live trial with one US/Canada local number, 300 managed inbound AI seconds (five minutes) total, and five SMS send attempts to verified destinations. Card verification is required before number allocation; the clock starts when allocation succeeds. There is no monthly reset or automatic paid subscription. Live OTP extraction and outbound calls require Pro.\n\nExisting Free accounts retain their assigned monthly allowances. Read the account's offerVersion, trial and limits rather than assuming every Free account has the same offer. Only describe a monthly reset when the account response supplies a non-null resetsAt.\n\nPro is $19.99/month plus number rental and usage: local/mobile numbers $2/month each, toll-free $2.50/month, outbound SMS $0.015/message, standard outbound voice $0.035/min, managed AI voice $0.40/min, BYOK voice $0.10/min plus your AI provider's charges, or Premium Voice $0.59/min. AI calls round up to whole minutes per call. New-account destination/business verification can still apply after upgrading.\n\nAfter trial expiry, the number is held for at least 48 hours before release, with a successful expiry notice before release becomes eligible. A delayed notice extends the hold. Trial expiry and number retention are separate; stored configuration and results remain available. Upgrading during the hold preserves the number.\n\nBefore quoting allowances or taking a paid action, call get_plan (or GET /v1/account) and use the returned offerVersion, trial, limits, billingStatus and summary. New live_trial_72h_v1 accounts have a one-time 72-hour trial starting at successful number allocation, 300 managed inbound AI seconds total and five verified-destination SMS attempts; card verification is required first. No monthly reset, automatic upgrade or Free overage. Existing free_monthly_v1 accounts retain assigned monthly allowances. Live OTP extraction, outbound calls, BYOK and Premium Voice require Pro for new trial accounts. Explain payment_method_required, payment_recovery_required, trial expiry and quota errors; stop retrying them. Share the returned setup/upgrade link when the user wants to proceed, let the human complete card/payment steps, then reread get_plan before retrying. Do not assume saving a card upgrades the account, or promise a released number can be recovered. Pro is $19.99/month plus number rental and usage. Do not auto-run upgrade_to_pro just because another tool failed. Honor the user's authorization for any real-world action. Read https://api.agentcall.co/llms.txt for the current reference.\n<!-- END GENERATED OFFER POLICY -->\n\nYou 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.\n\n## Authentication\n\nAll authenticated requests require: `Authorization: Bearer <AGENTCALL_API_KEY>`\n\nThe API key is available in the `AGENTCALL_API_KEY` environment variable.\n\n## Base URL\n\n`https://api.agentcall.co`\n\nFor a complete plain-text API reference: `GET https://api.agentcall.co/llms.txt` (no auth required).\n\n## Cost & Safety: Confirm Before Acting\n\nSeveral 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.\n\n**Billable actions (cost real money. Confirm scope first):**\n- `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.\n- `POST /v1/sms/send`: $0.015/message on Pro (new trials: five attempts total to verified destinations; existing Free: assigned allowance). Confirm the recipient number and the message body before sending.\n- `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.\n- `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.\n- Inbound AI voice (`POST /v1/numbers/:id/inbound-config` with `mode: \"ai\"`). New accounts get 300 managed inbound AI seconds total within a one-time 72-hour live trial, with card verification before number allocation. Exhaustion or expiry stops new trial calls; it does not create paid overage or a monthly reset. Existing Free accounts keep their assigned monthly offer. Read get_plan or GET /v1/account before quoting limits. Pro inbound AI is per-number configurable in two billing modes: Managed at $0.40/min (default; AgentCall holds the AI provider key) or BYOK at $0.10/min (customer provides their own AI provider key via `set_byok_openai_key`). There is no pay-as-you-go overage path on Free. Confirm the user wants inbound AI enabled on this specific number, and that the system prompt accurately describes their business.\n- `POST /v1/numbers/:id/byok-key` (`set_byok_openai_key`): switches a number's inbound AI voice from Managed billing ($0.40/min) to BYOK billing ($0.10/min) and stores the customer-supplied AI provider key for that number. Confirm the user wants to switch billing modes on the specific number, that they have a working key on hand, and that they understand the per-minute rate change before invoking.\n- `DELETE /v1/numbers/:id/byok-key` (`disable_byok`): removes the stored BYOK key on a number and reverts it to Managed billing ($0.40/min). Confirm the user wants to revert billing modes; the system prompt, voice, recording flag, and notify block on the number are preserved.\n- `POST /v1/numbers/:id/premium-voice` (`set_premium_voice`): enables Premium Voice on a number, or changes which premium voice it uses. Premium Voice is an opt-in Pro add-on: a curated voice library, the same 31 languages as the standard voice plus auto-detect, full caller memory, billed at $0.59/min only on the numbers where it is enabled (the 10 standard voices stay the default at $0.40/min). Applies to both inbound calls and outbound AI calls placed from the same number. Pass a `voiceId` from `list_premium_voices`. The number must already have inbound AI configured; enabling premium never wipes the rest of the inbound config; idempotent. Confirm the exact numberId, the chosen voice, and that the user accepts the $0.59/min premium rate before invoking. Requires Pro + a card on file + inbound AI configured, else returns 403 / 402 / 409 respectively; surface that error, do not retry.\n- `DELETE /v1/numbers/:id/premium-voice` (`disable_premium_voice`): reverts a number to the standard inbound AI voice, stopping the $0.59/min add-on. Preserves the rest of the inbound config. Idempotent. Pro plan only.\n- `list_premium_voices` (`GET /v1/calls/premium-voices`, no auth): browse the Premium Voice catalog (id, name, description, gender, accent, sampleUrl). Use the returned id with set_premium_voice.\n- Optional `record: true` on AI voice paths. $0.01/min on top of the AI rate. Mention this delta when proposing recording.\n- `create_schedule` (`POST /v1/numbers/:id/schedules`): schedules a proactive text the agent sends FIRST (a one-time appointment reminder, or a recurring digest). Each time it fires it sends one outbound SMS ($0.015 on Pro) to a real person who did not just message in, and a recurring schedule keeps firing until cancelled. Confirm the recipient, the message (or the recurrence and timezone), and the timing before creating it. Pro plan only; the number must have inbound AI / `smsMode: \"ai\"`. Offer `cancel_schedule` as soon as the schedule is no longer needed.\n\n**Irreversible actions:**\n- `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.\n- `POST /v1/calls/:callId/hangup`: terminates an in-flight call. Usually fine but confirm if the call may still be progressing toward its goal.\n\n**External-effect actions (contact real people):**\n- 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.\n- 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.\n\n**Built-in API guardrails (don't rely on these as your only check):**\n- **New live trial**: New accounts receive a one-time 72-hour live trial with one US/Canada local number, 300 managed inbound AI seconds (five minutes) total, and five SMS send attempts to verified destinations. Card verification is required before number allocation; the clock starts when allocation succeeds. There is no monthly reset or automatic paid subscription. Live OTP extraction and outbound calls require Pro. Existing Free accounts retain their assigned monthly allowances. Read the account's offerVersion, trial and limits rather than assuming every Free account has the same offer. Only describe a monthly reset when the account response supplies a non-null resetsAt.\n- Outbound AI voice + call recording require a payment method on file (Pro plan). The API returns 402 with a `setupUrl` if a Pro user has no card. Surface this to the user instead of looping.\n- **403 plan_limit_inbound_ai_trial_exhausted**: New accounts get 300 managed inbound AI seconds total within a one-time 72-hour live trial, with card verification before number allocation. Exhaustion or expiry stops new trial calls; it does not create paid overage or a monthly reset. Existing Free accounts keep their assigned monthly offer. Read get_plan or GET /v1/account before quoting limits. Before quoting allowances or taking a paid action, call get_plan (or GET /v1/account) and use the returned offerVersion, trial, limits, billingStatus and summary. New live_trial_72h_v1 accounts have a one-time 72-hour trial starting at successful number allocation, 300 managed inbound AI seconds total and five verified-destination SMS attempts; card verification is required first. No monthly reset, automatic upgrade or Free overage. Existing free_monthly_v1 accounts retain assigned monthly allowances. Live OTP extraction, outbound calls, BYOK and Premium Voice require Pro for new trial accounts. Explain payment_method_required, payment_recovery_required, trial expiry and quota errors; stop retrying them. Share the returned setup/upgrade link when the user wants to proceed, let the human complete card/payment steps, then reread get_plan before retrying. Do not assume saving a card upgrades the account, or promise a released number can be recovered. Pro is $19.99/month plus number rental and usage. Do not auto-offer upgrade_to_pro only if the user requests an upgrade just because another tool failed. Honor the user's authorization for any real-world action. Read https://api.agentcall.co/llms.txt for the current reference.\n- Every `plan_limit_*` error carries `upgradeUrl` (https://agentcall.co/billing) and `upgradeToolName` (`upgrade_to_pro`). When one comes back, tell the user what the feature costs (Pro is $19.99/mo plus usage), and only if they say yes run `upgrade_to_pro` and show them the checkout link it returns. That tool starts a Stripe Checkout session; nothing is charged until the human completes the form themselves. Never call it speculatively, and never call it more than once per conversation.\n- Redial cap: a destination can be dialed at most 3 times per UTC day (numbers the account owns or has verified are exempt). A 429 `redial_limit_exceeded` means stop dialing that number today; do not retry or try variations.\n- Rate limits: 100 req/min global; per-route limits on expensive endpoints (10 req/min on AI voice, 20 req/hour on uploads).\n- 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.\n\n### Inbound AI Configuration: Enable Only After Explicit User Confirmation; Monitor Usage; Disable When No Longer Needed\n\n`configure_inbound_ai` and `POST /v1/numbers/:id/inbound-config` with `mode: \"ai\"` should follow this procedure every time:\n\n**Pre-flight checklist (require the user to confirm each before invocation):**\n1. The exact E.164 number to configure. Read it back if the user has more than one number.\n2. The system prompt content. Read back at least the WHAT WE DO and PRICING sections so the user can correct anything inaccurate before invocation.\n3. The recording setting (`record: true` or `false`). Default to `false`. Confirm explicit opt-in if the user wants recording.\n4. The notification email and/or text (`notify.emailTo`, `notify.smsTo`). Confirm the destination belongs to the user and that they want post-call summaries delivered to it.\n5. The shortest practical call duration (`maxDurationSecs`). Pick the smallest value that fits the use case rather than relying on the 600-second default.\nNew accounts get 300 managed inbound AI seconds total within a one-time 72-hour live trial, with card verification before number allocation. Exhaustion or expiry stops new trial calls; it does not create paid overage or a monthly reset. Existing Free accounts keep their assigned monthly offer. Read get_plan or GET /v1/account before quoting limits. New live trials include five SMS send attempts total to verified destinations during the trial. Failed or ambiguous sends consume an attempt. Existing Free accounts keep their assigned monthly SMS allowance; read get_plan or GET /v1/account. Pro outbound SMS is $0.015/message, subject to account and destination restrictions.\n\n**Post-configuration responsibility:**\n- Monitor usage: periodically call `get_usage` or point the user at the dashboard at /billing.\n- Disable as soon as the configuration is no longer needed: proactively offer `disable_inbound_ai` (or `DELETE /v1/numbers/:id/inbound-config`) when the user's stated goal has been met (testing finished, campaign over, business closed for the season).\n- If the user reports unexpected calls or charges, call `disable_inbound_ai` first, then investigate.\n\nIf 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.\n\n## Phone Numbers\n\n**Provision a number:**\n```\nPOST /v1/numbers/provision\nBody: { \"type\": \"local\", \"country\": \"US\", \"label\": \"my-agent\" }\nTypes: 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).\nResponse: { \"id\": \"num_xxx\", \"number\": \"+12125551234\", \"type\": \"local\", ... }\n```\n\n**List numbers:**\n```\nGET /v1/numbers\nQuery: ?limit=20&country=US&type=local\n```\n\n**Get number details:**\n```\nGET /v1/numbers/:id\n```\n\n**Release a number (irreversible):**\n```\nDELETE /v1/numbers/:id\n```\n\n**Rename a number or change its inbound AI voice/language (partial update, preserves all other inbound config):**\n```\nPATCH /v1/numbers/:id\nBody: { \"label\": \"Hermes assistant\" }                  // rename only\nBody: { \"voice\": \"marin\" }                             // voice only (requires inbound AI already configured)\nBody: { \"language\": \"es\" }                             // language only (requires inbound AI already configured)\nBody: { \"label\": \"Hermes\", \"voice\": \"coral\", \"language\": \"fr\" }  // any combination\nVoices: alloy, ash, ballad, cedar, coral, echo, marin, sage, shimmer, verse\nLanguages: auto, en, es, fr, de, it, pt, nl, ja, ko, zh, hi, ar, ru, id, tr, pl, uk, vi, ta, ms, ro, el, cs, sv, hu, da, fi, no, sk, hr, bg  (31 languages plus auto)\nResponse: full number object including updated `inbound` block.\n```\nUse this when the user wants to change the voice or language on an existing receptionist. Do NOT call `POST /v1/numbers/:id/inbound-config` for a voice or language change. That endpoint replaces the entire inbound config and would wipe the system prompt, first message, recording flag, and notify block.\n\n## Inbound AI Voice (72-hour live trial; Pro Managed $0.40/min or BYOK $0.10/min)\n\nConfigure a phone number so incoming calls are answered autonomously by an AI voice agent. The AI follows the system prompt you set.\n\nAfter 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.\n\n**Configure inbound AI on a number:**\n```\nPOST /v1/numbers/:numberId/inbound-config\nBody: {\n  \"mode\": \"ai\",\n  \"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.\",\n  \"voice\": \"shimmer\",\n  \"language\": \"auto\",\n  \"firstMessage\": \"Hi, thanks for calling Acme Plumbing. How can I help?\",\n  \"maxDurationSecs\": 300,\n  \"transferTo\": \"+14155551234\",\n  \"notify\": {\n    \"emailTo\": \"owner@acmeplumbing.com\",\n    \"smsTo\": \"+14155551234\",\n    \"businessName\": \"Acme Plumbing\",\n    \"agencyName\": \"Acme Plumbing\"\n  }\n}\n```\n\nThe `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. Set `notify.smsTo` (E.164 phone) to also receive a short text summary of each call (caller, what they wanted, urgency, callback time), US-local senders only, one text per call (spam skipped), reply STOP to opt out, billed as one outbound SMS ($0.015). `emailTo` and `smsTo` are independent: set either, both, or neither. The MCP `configure_inbound_ai` tool also accepts `notify`: agents in Claude Desktop, Cursor, Windsurf, etc. can configure the email and text destinations in the same call as the system prompt, no dashboard handoff needed.\n\n**Transfer to a human (optional):** set `transferTo` (an E.164 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; whoever answers sees the caller's number, not the AgentCall number. If nobody picks up within about 25 seconds, the AI resumes and takes a message instead, so the caller is never dropped. Works with no webhook or tool setup and coexists with declared `tools`. AI minutes stop at the handoff; the human portion of the call bills at the standard $0.035/min voice rate. Transfers show as `transferredTo` / `transferredAt` on the call record. Omit or pass `null` for no transfer (the AI takes a message, the default). Confirm the transfer destination with the user before configuring it: it is a real phone that will ring on live calls.\n\n**Spoken language (optional, default 'auto'):** the `language` field controls what language the AI answers in. `'auto'` matches the caller's language naturally and is what existing receptionists do today. Pass a specific ISO-639-1 code to make the AI respond ONLY in that language even if the caller speaks another, useful when the business serves a specific language community. Supported (31 languages plus auto): `auto`, `en` (English), `es` (Spanish), `fr` (French), `de` (German), `it` (Italian), `pt` (Portuguese), `nl` (Dutch), `ja` (Japanese), `ko` (Korean), `zh` (Chinese Mandarin), `hi` (Hindi), `ar` (Arabic), `ru` (Russian), `id` (Indonesian), `tr` (Turkish), `pl` (Polish), `uk` (Ukrainian), `vi` (Vietnamese), `ta` (Tamil), `ms` (Malay), `ro` (Romanian), `el` (Greek), `cs` (Czech), `sv` (Swedish), `hu` (Hungarian), `da` (Danish), `fi` (Finnish), `no` (Norwegian), `sk` (Slovak), `hr` (Croatian), `bg` (Bulgarian). Premium Voice covers the same 31 languages plus `auto`. The directive is added at session-build time so the customer's `systemPrompt` stays unchanged when language is swapped. Use `update_number_language` to change just the language without touching anything else.\n\n**Pre-call context webhook (optional):** add a `contextWebhook` block to wire a live context source onto the number. When set, AgentCall POSTs to your HTTPS URL on every inbound call connect (HMAC-signed with `signingSecret`); your endpoint responds with `{\"contextBlock\":\"...\"}` and AgentCall merges that string onto the system prompt before the AI answers. Useful for injecting today's brief, current priorities, or recent email signals so the AI speaks with up-to-date data instead of a static prompt. Example:\n```\n\"contextWebhook\": {\n  \"url\": \"https://hermes.your-domain.com/agentcall/precall\",\n  \"signingSecret\": \"<32+ char shared secret>\",\n  \"timeoutMs\": 1200\n}\n```\nFail-open: any error in the webhook leaves the call running with the static prompt. Walkthrough at https://agentcall.co/docs/hermes.\n\n**Optional call recording (Pro plan, $0.01/min on top of the AI voice rate):**\nAdd `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.\n\n**Get current inbound config:**\n```\nGET /v1/numbers/:numberId/inbound-config\n```\n\n**Disable inbound AI (calls hang up at carrier):**\n```\nDELETE /v1/numbers/:numberId/inbound-config\n```\n\n### Voice billing mode: Managed vs BYOK (per number)\n\nEach Pro number with inbound AI configured chooses one of two billing modes for its AI voice minutes:\n\n- **Managed** (default): $0.40/min. AgentCall holds the AI provider key on the customer's behalf. Simplest setup; no key handling on the customer side.\n- **BYOK**: $0.10/min. The customer provides their own AI provider key; AgentCall bills only the platform overhead. The same number's system prompt, voice, recording flag, and notify block are preserved across mode switches.\n\nMemory, transcripts, post-call email and text summaries, the `call.transcript` and `call.report.ready` webhook events, and call recording all work identically on both modes.\n\n**Switch a number to BYOK (set or rotate the key):**\n```\nPOST /v1/numbers/:numberId/byok-key\nBody: { \"openaiApiKey\": \"sk-...\" }\nResponse: { \"voiceMode\": \"byok\", \"hasByokKey\": true, \"byokOpenaiApiKeyPreview\": \"sk-...abcd\" }\n```\n\n**Switch a number back to Managed (revert billing mode):**\n```\nDELETE /v1/numbers/:numberId/byok-key\nResponse: { \"voiceMode\": \"managed\", \"hasByokKey\": false, \"byokOpenaiApiKeyPreview\": null }\n```\n\n**Inspect the current mode** (the existing inbound-config response now includes voiceMode + hasByokKey + byokOpenaiApiKeyPreview):\n```\nGET /v1/numbers/:numberId/inbound-config\nResponse: {\n  ...inbound config fields...,\n  \"voiceMode\": \"managed\" | \"byok\",\n  \"hasByokKey\": boolean,\n  \"byokOpenaiApiKeyPreview\": \"sk-...abcd\" | null\n}\n```\n\nThe stored key is write-only; the GET response surfaces a redacted preview (last 4 chars) and a boolean, never the full value. Rotating is a re-POST to `byok-key` with the new value; AgentCall replaces the stored value atomically.\n\n## Browse Voices and Prompt Templates (no auth)\n\nBoth endpoints are public. Call them before configuring AI voice to avoid hallucinated business details and to pick a voice that fits the use case.\n\n**List the 10 voices with samples:**\n```\nGET /v1/calls/voices\nReturns: { voices: [{ id, name, trait, description, bestFor, sampleUrl? }, ...], defaultVoice: \"shimmer\" }\n```\nThe newest natural-sounding picks are `marin` (soft, natural) and `cedar` (warm, grounded). The original 8 (`shimmer`, `sage`, `ash`, `ballad`, `coral`, `echo`, `verse`, `alloy`) ship with sample MP3s; marin and cedar are live-preview only for now.\n\n**List the premium voices (`list_premium_voices`):**\n```\nGET /v1/calls/premium-voices\nReturns: { voices: [{ id, name, description, gender, accent, sampleUrl }, ...], pricing: { premiumVoice: \"$0.59/minute\" } }\n```\nPremium Voice is the higher-quality, brandable tier for inbound AI receptionists: a curated voice library, the same 31 languages as the standard voice plus auto-detect, and full caller memory, a Pro add-on at $0.59/min.  Each entry's `id` is the voiceId; preview it via the returned `sampleUrl`. Enable it on a number with `set_premium_voice` (numberId + voiceId), or from the dashboard (a number's inbound AI settings, then the Premium Voice section); revert with `disable_premium_voice`. As a billable add-on, confirm the user accepts the $0.59/min premium rate on the specific number before enabling.\n\n**List ready-made prompt templates:**\n```\nGET /v1/calls/prompt-templates\nReturns 5 templates with [BRACKETED] placeholders to fill in:\n- receptionist (Front Desk). Recommends shimmer voice\n- lead-qualifier (Sales, BANT-style). Coral\n- appointment-booker. Sage\n- customer-support (FAQ Deflection). Ash\n- call-screener (Anti-Spam). Verse\nEach entry includes: id, title, description, recommendedVoice, maxDurationSecs, firstMessage, systemPrompt.\n```\n\nFor a comprehensive prompt-writing guide: https://agentcall.co/docs/voice-prompts\n\n## New-Account Outbound Restriction (read before the first outbound text or call)\n\nA new account may not *call* an arbitrary number, and a Pro account under 7 days old may only text new numbers within its starter allowance (below). Attempting anything past that returns `403 destination_not_verified`. This is enforced on every outbound path, including proactive schedules (which never use the starter allowance). Retrying does not help.\n\nNew live trials include five SMS send attempts total to verified destinations during the trial. Failed or ambiguous sends consume an attempt. Existing Free accounts keep their assigned monthly SMS allowance; read get_plan or GET /v1/account. Pro outbound SMS is $0.015/message, subject to account and destination restrictions. New live trials do not use the legacy starter-destination exception. Existing Free and new Pro accounts can have separate starter allowances; read account and verification status. Never retry destination restrictions in a loop.\n\nA restricted account CAN already:\n- contact any number the account owns (agent-to-agent testing works immediately)\n- reply to anyone who contacted it first, within the last 30 days (inbound threads and callbacks are unaffected)\n- contact any number verified individually: `POST /v1/verified-destinations` with `{ \"phone\": \"+14155551234\" }` sends a 6-digit code there, then `POST /v1/verified-destinations/:id/confirm` with `{ \"code\": \"123456\" }`. Cap 25 on Pro, 5 on Free.\n\nNone of the three paths above consume a starter slot. Only a text to a brand-new stranger does.\n\nTo lift the restriction entirely (Pro only), the account owner submits a business verification:\n```\nPOST /v1/business-verification\nBody: {\n  \"legalName\": \"Ridgeline Painting LLC\",\n  \"website\": \"https://ridgelinepainting.com\",   // website OR ein required\n  \"contactName\": \"Dana Whitfield\",\n  \"useCase\": \"Payment reminders to existing customers with unpaid invoices, including a pay link.\",\n  \"sampleMessage\": \"Invoice 4021 for $840 is 12 days past due. Pay here: example.com/pay/4021. Reply STOP to opt out.\"\n}\nGET /v1/business-verification    # returns grantsOutboundPilot: can this account contact strangers now?\n```\nThis lifts the restriction on submission (a human reviews afterwards). A daily cap on distinct NEW recipients applies while the account is under 7 days old, starting at 25 on day one. After 7 days on Pro the restriction lifts automatically regardless.\n\n**If you are an AI agent and hit this error:** do not retry, do not try other numbers to find one that works, and do not attempt to work around it. Report it to the user and tell them the two routes above. Submitting the business verification requires the user's own business details, so ask them for those rather than inventing any.\n\n## SMS\n\n**Send SMS:**\n```\nPOST /v1/sms/send\nBody: { \"from\": \"num_xxx\", \"to\": \"+14155551234\", \"body\": \"Hello!\" }\n\"from\" can be a number ID or E.164 phone string\n```\n\n**Get inbox:**\n```\nGET /v1/sms/inbox/:numberId\nQuery: ?limit=20&otpOnly=true\n```\n\n**Get a specific message:**\n```\nGET /v1/sms/:messageId\n```\n\n**Wait for OTP code (long-polls up to 60 seconds):**\n```\nGET /v1/sms/otp/:numberId\nQuery: ?timeout=60000\nResponse: { \"otp\": \"482913\", \"message\": { ... } }\n```\n\n## Two-Way AI SMS and Relay Mode\n\nA number can answer inbound texts, not just parse OTPs. Set this on the same inbound config endpoint that sets up the AI receptionist (POST /v1/numbers/:numberId/inbound-config) via the `smsMode` field:\n\n- `smsMode: \"ai\"`: AgentCall's AI answers each inbound text following your prompt, remembers the contact across voice and SMS, and can return real quotes by calling tools you declare. Declare them with `tools` and host them at `actionWebhook` (HMAC-signed, the same security model as the pre-call context webhook). The AI calls your tool, you return the real value, the AI texts it back instead of guessing. Pro plan, managed only, billed as one outbound text per reply.\n- `smsMode: \"relay\"`: AgentCall runs no AI of its own. It forwards each inbound text to your own agent at `agentWebhook` (HMAC-signed), and your agent replies on its own schedule, so you can text your own agent on a real number. Use `allowedSenders` (E.164 array, up to 20) to restrict which numbers can reach the agent, so a personal agent answers only its owner. Billed as plain texts, no relay fee.\n\nConfig fields on configure_inbound_ai: `smsMode` (\"off\" | \"ai\" | \"relay\"), `smsSystemPrompt`, `actionWebhook`, `tools`, `agentWebhook`, `allowedSenders`.\n\nThe same `tools` + `actionWebhook` pair also powers in-call VOICE tool calling: on an inbound AI voice call, the agent can call the declared tools mid-call (check real calendar availability, look up an order) and the JSON result feeds back into the live conversation. Each tool call is HMAC-POSTed to the actionWebhook with `context.channel` set to \"voice\" and `context.callId` populated. Errors degrade gracefully (the agent says it could not complete the action rather than inventing a result). The per-call count appears as `toolCallCount` on the call record and in the call report. Works alongside the pre-call context webhook.\n\n**Read SMS threads:**\n```\nGET /v1/sms-conversations            # list threads (paginated)\nGET /v1/sms-conversations/:id        # one thread + last 50 messages + context\n```\nMCP tools: list_sms_conversations, get_sms_conversation.\n\nThe thread detail also returns a `context` object that classifies those same messages by age, and you should use it for anything about recency. `messages` is the last 50 texts on the thread, which on a quiet thread can span months, so treating them as a recent conversation makes you describe a months-old exchange as something you just talked about. `context.recentMessages` covers the last 7 days, `context.recentSubstantiveMessages` is that list with plain greetings removed, and `context.olderMessages` is background only. Answer \"what did we recently talk about?\" from `recentSubstantiveMessages` alone; when it is empty, say there has been no recent substantive text discussion rather than reaching into `olderMessages`, durable memory, or call history and presenting any of them as a recent text conversation. `context.freshness` carries the window and the reference time it was measured against.\n\n**Reply into a thread (relay mode):**\n```\nPOST /v1/sms-conversations/:id/reply\nBody: { \"body\": \"3 emails need you today.\", \"idempotencyKey\": \"turn_8842\" }\n```\nYour own agent calls this when it has an answer; AgentCall sends and threads the text. Opt-out-checked (refuses to text someone who sent STOP) and idempotent on `idempotencyKey` for 24 hours so a retried agent never double-texts. MCP tool: reply_to_sms_conversation. Billed as one outbound text.\n\nThe relay push to your `agentWebhook` carries the same freshness-classified thread as an additive `smsContext` field beside `message`, `conversation`, and `context`, so your agent gets the recency split without a second API call. An endpoint written against the earlier payload keeps working unchanged.\n\nSTOP and UNSUBSCRIBE are always honored before either mode runs. Both modes are reactive: they handle texts that arrive. To open a conversation yourself, send the first message with `POST /v1/sms/send` (`send_sms`) or set a proactive schedule (below); the contact's reply lands on the same thread and is handled by whichever mode the number is in.\n\n## Proactive Scheduling (the agent texts first)\n\nTwo-way AI SMS is reactive: the number answers when someone texts it. Proactive scheduling makes a number's agent reach out FIRST on a schedule, so it can send appointment reminders, payment follow-ups, and recurring digests without the contact messaging in. Pro plan only (proactive sends never fire on Free). The send itself works on any provisioned number; set `smsMode: \"ai\"` when you want the contact's reply answered automatically on the same thread, so a one-word answer like \"C\" is understood in context. Each fire is billed as one standard outbound text, is skipped for anyone who has sent STOP, and is capped at 200 per number per day.\n\n```\nPOST   /v1/numbers/:numberId/schedules     # create a schedule\nGET    /v1/numbers/:numberId/schedules      # list schedules (?status= optional)\nDELETE /v1/numbers/:numberId/schedules/:id  # cancel + remove\n```\n\nEach schedule is one of two timings and one of two message styles:\n- Timing: `fireAt` (a one-time ISO 8601 instant in the future, for reminders) OR `recurrence` (`{ frequency: \"daily\" | \"weekly\", hour, minute, dayOfWeek }` interpreted in `timezone`, for digests). Provide exactly one.\n- Message: `template` (sent verbatim, with `{{placeholders}}` filled from `payload`) OR `promptHint` (the agent composes the message using its memory of the contact). Provide exactly one.\n\nPass `dedupeKey` to make a re-create safe: a duplicate key on the same number returns 409, so a calendar sync can create the same reminder repeatedly without duplicating it.\n\n```\nPOST /v1/numbers/num_abc/schedules\nBody: {\n  \"kind\": \"reminder\",\n  \"contactPhone\": \"+14155551234\",\n  \"fireAt\": \"2026-06-09T19:00:00Z\",\n  \"template\": \"Hi {{name}}, reminder: your {{service}} is tomorrow at {{time}}. Reply C to confirm.\",\n  \"payload\": { \"name\": \"Marcus\", \"service\": \"cleaning\", \"time\": \"2pm\" },\n  \"dedupeKey\": \"reminder:appt_8841:24h\"\n}\n```\n\nMCP tools: create_schedule, list_schedules, cancel_schedule. A calendar integration is just a client of create_schedule: post one reminder per appointment with a stable dedupeKey. Each send is billed as one outbound text ($0.015 on Pro); confirm recipient, message, and timing with the user before scheduling, and offer cancel_schedule when it is no longer needed.\n\n## Outbound Voice Calls\n\n**Start a standard outbound call:**\n```\nPOST /v1/calls/initiate\nBody: { \"from\": \"num_xxx\", \"to\": \"+14155551234\", \"record\": false }\n```\n\n**Start an outbound AI voice call (Pro plan, $0.40/min. Billable, contacts real human, confirm with user first):**\nThe AI handles the entire conversation autonomously based on your systemPrompt.\n```\nPOST /v1/calls/ai\nBody: {\n  \"from\": \"num_xxx\",\n  \"to\": \"+14155551234\",\n  \"systemPrompt\": \"You are calling to schedule a dentist appointment for Tuesday afternoon.\",\n  \"voice\": \"shimmer\",\n  \"language\": \"auto\",\n  \"firstMessage\": \"Hi, I'd like to schedule an appointment please.\",\n  \"maxDurationSecs\": 600,\n  \"record\": false\n}\n```\nAdd `record: true` to capture an mp3 of the call. Adds $0.01/min on top.\n\nOptional fields for orchestrators:\n- `metadata`: a string-to-string map (at most 24 keys, 64-char keys, 512-char values, 2KB serialized) echoed on the call object and in every subsequent webhook payload (call.status, call.transcript, call.recording, call.report.ready). When the destination is another number on the same account, the linked inbound leg carries the same metadata. Use it to tag calls with your own IDs (showId, segmentId) instead of joining on callId.\n- `liveTranscript: true`: stream the transcript live. Each finalized utterance fires a `transcript.partial` webhook during the call ({ callId, sequence, role, text, timestamp }, sequence is monotonic per call) within a second or two of speech. Requires a webhook subscribed to `transcript.partial`. The final `call.transcript` stays unchanged and authoritative.\n- Calls between two numbers on the same account expose `peerCallId` on both call records and in webhook payloads, linking the outbound and inbound legs.\n\n**Spoken language on outbound calls (optional, default 'auto'):** the `language` field controls what language the AI speaks during the call. `'auto'` lets the AI match the recipient's language naturally. Pass a specific ISO-639-1 code to make the AI respond ONLY in that language. Useful for booking appointments or requesting info on behalf of someone in another language, e.g. `language: 'es'` to call a Spanish-speaking doctor's office on behalf of a customer who doesn't speak Spanish. Supported (31 languages plus auto): `auto`, `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `ja`, `ko`, `zh`, `hi`, `ar`, `ru`, `id`, `tr`, `pl`, `uk`, `vi`, `ta`, `ms`, `ro`, `el`, `cs`, `sv`, `hu`, `da`, `fi`, `no`, `sk`, `hr`, `bg`. The `firstMessage` stays verbatim, so if you want the greeting in Spanish, write the firstMessage in Spanish yourself; the language setting only governs the AI's responses after.\n\n**Outbound prompt templates** (no auth, public): fetch `GET /v1/calls/prompt-templates?direction=outbound` for three ready-made outbound templates with `[BRACKETED]` placeholders to fill in: `outbound-appointment-booker` (book an appointment on behalf of someone), `outbound-info-request` (call to ask a specific question on behalf of someone), `outbound-callback-confirmation` (follow up on something).\n\nVoices (10 total, default: shimmer; preview the original 8 via GET /v1/calls/voices, marin and cedar are live-preview only):\n- marin: soft, natural. New top pick for receptionist, support, conversational small business\n- cedar: warm, grounded. New. Advisory, healthcare, trust-building calls\n- shimmer: bright, energetic. Long-running default\n- sage: calm, authoritative, confident. Healthcare, finance, advisory\n- ash: warm, conversational. Customer service, support lines\n- ballad: expressive, melodic. Engaging, narrative conversations\n- coral: clear, professional. B2B calls, sales\n- echo: resonant, deep. Formal inquiries, executive comms\n- verse: smooth, articulate. Premium or luxury, executive communication\n- alloy: neutral, balanced. Generic notifications, IVR-style flows\n\n### Saved outbound AI agent per number (Pro plan)\n\nSave a reusable outbound AI agent on a phone number so repeat outbound calls from the same number reuse the same configuration. The dashboard Place AI call dialog hydrates from this blob; MCP clients can read it back instead of asking the user to retype the prompt every call. This is independent of the inbound AI receptionist on the same number; configuring one does not change the other.\n\nThe saved blob holds: `systemPrompt`, `voice`, `language`, `firstMessage`, `maxDurationSecs`, `record`, and an optional `templateId` (the outbound prompt template used to seed it, when applicable).\n\n**Save the outbound agent on a number:**\n```\nPOST /v1/numbers/:numberId/outbound-defaults\nBody: {\n  \"systemPrompt\": \"You are calling on behalf of Acme Plumbing to confirm tomorrow's 10am appointment.\",\n  \"voice\": \"shimmer\",\n  \"language\": \"auto\",\n  \"firstMessage\": \"Hi, calling to confirm tomorrow's appointment.\",\n  \"maxDurationSecs\": 300,\n  \"record\": false,\n  \"templateId\": \"outbound-callback-confirmation\"\n}\n```\n\n**Read the saved outbound agent (returns null if none set):**\n```\nGET /v1/numbers/:numberId/outbound-defaults\n```\n\n**Remove the saved outbound agent:**\n```\nDELETE /v1/numbers/:numberId/outbound-defaults\n```\n\nThe MCP tools `set_outbound_defaults`, `get_outbound_defaults`, and `clear_outbound_defaults` mirror these endpoints. `list_numbers` and `get_number` responses include an `outbound` field alongside the existing `inbound` field, so a single fetch surfaces both per-number configurations.\n\n### Hydrating from the saved outbound agent and replay-safe retries\n\n`POST /v1/calls/ai` (MCP `initiate_ai_call`) accepts two optional input fields designed for CSV-driven outbound runs.\n\n**`useSavedAgent: boolean`**: when true, AgentCall hydrates the omitted call fields (`systemPrompt`, `voice`, `language`, `firstMessage`, `maxDurationSecs`, `record`) from the saved outbound agent on the `from` number. Per-call values in the same request always win, so the saved persona can be inherited while `firstMessage` is personalized per recipient. If the `from` number has no saved outbound agent, the API returns 400 with code `no_saved_agent`; call `set_outbound_defaults` first or supply the fields inline.\n\n**`idempotencyKey: string`** (1 to 200 chars, scoped per phone number): a duplicate request to `POST /v1/calls/ai` with the same `from` + `idempotencyKey` pair replays the original response and does not place a second carrier call. The replayed response carries an `X-AgentCall-Idempotency-Replayed: true` header. Uniqueness is enforced at the database layer, so concurrent retries are race-safe.\n\n**Canonical CSV-runner pattern** (one row per call, replay-safe across retries, persona stored once on the number):\n```\n{\n  \"from\": \"num_xxx\",\n  \"to\": \"+14155551234\",\n  \"useSavedAgent\": true,\n  \"idempotencyKey\": \"batch-2026-05-25:row-0042\",\n  \"firstMessage\": \"Hi Jamie, calling to confirm tomorrow's 10am appointment.\"\n}\n```\n\nThis is the recommended shape for CSV-driven outbound on a Hermes-style runner. The persona lives on the number via `set_outbound_defaults`; each row supplies only the recipient, a per-row `idempotencyKey`, and an optional per-row override.\n\n**List call history:**\n```\nGET /v1/calls\nQuery: ?limit=20\n```\n\n**Get call details:**\n```\nGET /v1/calls/:callId\n```\n\n**Get AI call transcript:**\n```\nGET /v1/calls/:callId/transcript\nResponse: { \"entries\": [{ \"role\": \"ai\" | \"human\", \"text\": \"...\", \"timestamp\": \"...\" }], \"summary\": \"...\", \"duration\": 111 }\n```\n\n**Hang up an active call:**\n```\nPOST /v1/calls/:callId/hangup\n```\n\n## Standalone Text to Speech (Pro plan, $0.03 per 1,000 characters)\n\nTurn text into spoken audio in the SAME 10 voices the AI uses on calls, so a number's voice identity carries off-call to IVR prompts, voicemail greetings, generated show segments, and social clips.\n\n```\nPOST /v1/tts\nBody: { \"text\": \"Thanks for calling Acme. We're open 9 to 5.\", \"voice\": \"marin\", \"format\": \"mp3\" }\nReturns: raw audio bytes (audio/mpeg or audio/wav) + x-agentcall-tts-characters header\n```\n\nFields: `text` (1-4096 characters, required; chunk longer copy), `voice` (one of the 10 call voices, default shimmer), `format` (\"mp3\" default or \"wav\"), `language` (optional ISO-639-1 hint). Billed per character of input text; confirm the text and approximate cost with the user before synthesizing large batches. MCP tool: `synthesize_speech` (returns the audio inline). SDK: `client.tts.synthesize({ text, voice, format })`.\n\n## AgentFM Callback\n\nAgentFM is a live podcast powered by AgentCall outbound premium voice. Guests request a callback and the AI host calls them back to record a short conversation.\n\n**Request a callback (no auth required):**\n```bash\ncurl -X POST https://api.agentcall.co/v1/agentfm/callback-request \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"phone\":\"+15551234567\",\"persona\":\"I build AI agents and want to discuss voice interfaces.\"}'\n```\n\nResponse: `{ \"status\": \"queued\" }` or `{ \"status\": \"already_pending\" }` (24h dedup per phone).\n\nMCP tool: `request_agentfm_callback(phone, persona?)`. No AgentCall account or plan required to call this tool. Rate limit: 3 requests per hour per IP. Deduplicated per phone per 24 hours so calling this multiple times for the same number is safe.\n\nWeb form for guests: https://agentcall.co/agentfm\n\n## Webhooks\n\n> **Important: webhooks here are for OUTBOUND event delivery, NOT inbound call routing.**\n> AgentCall POSTs to your URL when events fire (SMS received, OTP detected, call completed,\n> recording ready, etc.). Webhooks are NOT how you make a phone number answer incoming calls.\n> To configure how a number answers when called, use the **Inbound AI Voice** section above\n> (`POST /v1/numbers/:numberId/inbound-config`). Not webhooks. (If you're coming from Twilio:\n> AgentCall replaces Twilio's inbound voice webhook URL with `configure_inbound_ai`.)\n\n**Register a webhook:**\n```\nPOST /v1/webhooks\nBody: { \"url\": \"https://example.com/hook\", \"events\": [\"sms.inbound\", \"sms.otp\", \"call.status\"] }\nEvents: sms.inbound, sms.otp, sms.ai_reply, call.inbound, call.ringing, call.status, call.recording, call.transcript, call.report.ready, transcript.partial, number.released\n```\n\nCall status values are canonical everywhere (REST and webhooks): `initiated` -> `ringing` -> `in-progress` -> `completed`, with `busy`, `no_answer`, or `failed` for calls that never connect. Call webhook payloads also carry `peerCallId` (the other leg of a same-account agent-to-agent call, or null) and the call's `metadata` map when set on dial.\n\n`transcript.partial` is the live-stream complement to `call.transcript`: opt in with `liveTranscript: true` on `POST /v1/calls/ai` or on a number's inbound-config, and each finalized utterance is delivered during the call as { callId, sequence, role, text, timestamp }.\n\n**List webhooks:**\n```\nGET /v1/webhooks\n```\n\n**Rotate webhook secret:**\n```\nPOST /v1/webhooks/:id/rotate\n```\n\n**Delete a webhook:**\n```\nDELETE /v1/webhooks/:id\n```\n\n### Post-call transcript webhook (`call.transcript`)\n\nWhen the user wants their AI agent to learn from inbound AI calls, subscribe a webhook to the `call.transcript` event. AgentCall POSTs the full transcript and an LLM-extracted summary to the configured URL after each inbound AI call ends.\n\n**Subscribe:**\n```\nPOST /v1/webhooks\nBody: { \"url\": \"https://agent.example.com/agentcall/transcript\", \"events\": [\"call.transcript\"] }\n```\n\n**Payload shape:**\n```\n{\n  \"callId\": \"call_xxx\",\n  \"duration\": 53,\n  \"transcript\": [\n    { \"role\": \"ai\" | \"human\", \"text\": \"...\", \"timestamp\": \"ISO 8601\" }\n  ],\n  \"summary\": {\n    \"summary\": \"1-2 sentence plain English\",\n    \"callerName\": \"string or null\",\n    \"intent\": \"service_request | quote_request | scheduling | complaint | spam | general_inquiry | other\",\n    \"urgency\": \"high | medium | low\",\n    \"callbackBy\": \"string or null\",\n    \"spam\": true | false\n  }\n}\n```\n\n**Required handling on the receiving endpoint:**\n- Verify the HMAC-SHA256 signature in the `X-AgentCall-Signature` header using the webhook's signing secret. Reject mismatches with a non-2xx response.\n- Dedup on `callId`. AgentCall retries with exponential backoff until it receives a 2xx, so a slow first response can produce a duplicate delivery.\n- Acknowledge fast: return 2xx as soon as the payload is verified and persisted. Heavy processing belongs in a background job, not inline on the request.\n\n**Integration patterns:**\n- **Store** the payload to a database row keyed by `callId` and let the agent read it on its own schedule.\n- **Forward** the payload to an agent platform's ingest endpoint for real-time follow-up.\n- **Queue** the payload on a public bridge for a local agent platform to drain on cron. Reference bridge: github.com/Kintupercy/agentcall-hermes-bridge v0.2.0 exposes `POST /agentcall/transcript` (HMAC-verified queue append, max 100 entries, oldest dropped) and `POST /hermes/pull-transcripts` (`X-Hermes-Push-Key` authed read-and-clear).\n\nFull walkthrough with code examples: https://agentcall.co/docs/post-call-webhook.\n\n## Auditable Call Memory\n\nEvery completed AI call can be auto-extracted into structured, source-backed memory: contacts, facts, preferences, commitments, tasks, briefs. Each memory item carries a verbatim transcript quote as evidence and a full audit timeline. Cross-call memory means an inbound or outbound AI call can be aware of what was said in prior calls from the same number, automatically.\n\nMemory is opt-in per agent: set `memoryEnabled: true` on your agent (currently via the dashboard or direct DB update; account-level toggle endpoint is planned). Once enabled, every completed AI call produces a `CallReport` and a set of `MemoryCandidate` rows roughly 5 to 30 seconds after the call ends.\n\n### Contacts\n\nA `Contact` is one caller per phone per agent. Created automatically on the first call from or to a new number when memory is enabled. Contains `displayName`, `tags`, `ownerNotes`, `verified`, `blockedAt`, `callCount`, `lastSeenAt`. Caller ID is NOT verified by AgentCall by default; `verified` is owner-set or future STIR/SHAKEN attestation.\n\n**List contacts:**\n```\nGET /v1/contacts?limit=20&cursor=...\n```\n\n**Look up by phone (E.164):**\n```\nGET /v1/contacts/by-phone/+14155551234\n```\n\n**Edit owner fields:**\n```\nPATCH /v1/contacts/:id\nBody: { displayName?, tags?, ownerNotes?, verified?, blockedAt? }\n```\n\n**Right-to-forget** (wipes Memory + MemoryCandidate + Brief; redacts CallReport payloads; preserves Call + transcript audit shell):\n```\nDELETE /v1/contacts/:id\n```\n\nFile v2.13.1:_meta.json\n\n{\n  \"ownerId\": \"kn7d072cygf11v6hx13rfnmmcx81nwys\",\n  \"slug\": \"agentcall\",\n  \"version\": \"2.13.1\",\n  \"publishedAt\": 1788890383811\n}\n\nFile v2.13.1:instructions.md\n\n# AgentCall: Phone Numbers for AI Agents\n\n<!-- BEGIN GENERATED OFFER POLICY -->\n## Current offer and agent behavior\n\nNew accounts receive a one-time 72-hour live trial with one US/Canada local number, 300 managed inbound AI seconds (five minutes) total, and five SMS send attempts to verified destinations. Card verification is required before number allocation; the clock starts when allocation succeeds. There is no monthly reset or automatic paid subscription. Live OTP extraction and outbound calls require Pro.\n\nExisting Free accounts retain their assigned monthly allowances. Read the account's offerVersion, trial and limits rather than assuming every Free account has the same offer. Only describe a monthly reset when the account response supplies a non-null resetsAt.\n\nPro is $19.99/month plus number rental and usage: local/mobile numbers $2/month each, toll-free $2.50/month, outbound SMS $0.015/message, standard outbound voice $0.035/min, managed AI voice $0.40/min, BYOK voice $0.10/min plus your AI provider's charges, or Premium Voice $0.59/min. AI calls round up to whole minutes per call. New-account destination/business verification can still apply after upgrading.\n\nAfter trial expiry, the number is held for at least 48 hours before release, with a successful expiry notice before release becomes eligible. A delayed notice extends the hold. Trial expiry and number retention are separate; stored configuration and results remain available. Upgrading during the hold preserves the number.\n\nBefore quoting allowances or taking a paid action, call get_plan (or GET /v1/account) and use the returned offerVersion, trial, limits, billingStatus and summary. New live_trial_72h_v1 accounts have a one-time 72-hour trial starting at successful number allocation, 300 managed inbound AI seconds total and five verified-destination SMS attempts; card verification is required first. No monthly reset, automatic upgrade or Free overage. Existing free_monthly_v1 accounts retain assigned monthly allowances. Live OTP extraction, outbound calls, BYOK and Premium Voice require Pro for new trial accounts. Explain payment_method_required, payment_recovery_required, trial expiry and quota errors; stop retrying them. Share the returned setup/upgrade link when the user wants to proceed, let the human complete card/payment steps, then reread get_plan before retrying. Do not assume saving a card upgrades the account, or promise a released number can be recovered. Pro is $19.99/month plus number rental and usage. Do not auto-run upgrade_to_pro just because another tool failed. Honor the user's authorization for any real-world action. Read https://api.agentcall.co/llms.txt for the current reference.\n<!-- END GENERATED OFFER POLICY -->\n\nYou 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.\n\n## Authentication\n\nAll authenticated requests require: `Authorization: Bearer <AGENTCALL_API_KEY>`\n\nThe API key is available in the `AGENTCALL_API_KEY` environment variable.\n\n## Base URL\n\n`https://api.agentcall.co`\n\nFor a complete plain-text API reference: `GET https://api.agentcall.co/llms.txt` (no auth required).\n\n## Cost & Safety: Confirm Before Acting\n\nSeveral 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.\n\n**Billable actions (cost real money. Confirm scope first):**\n- `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.\n- `POST /v1/sms/send`: $0.015/message on Pro (new trials: five attempts total to verified destinations; existing Free: assigned allowance). Confirm the recipient number and the message body before sending.\n- `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.\n- `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.\n- Inbound AI voice (`POST /v1/numbers/:id/inbound-config` with `mode: \"ai\"`). New accounts get 300 managed inbound AI seconds total within a one-time 72-hour live trial, with card verification before number allocation. Exhaustion or expiry stops new trial calls; it does not create paid overage or a monthly reset. Existing Free accounts keep their assigned monthly offer. Read get_plan or GET /v1/account before quoting limits. Pro inbound AI is per-number configurable in two billing modes: Managed at $0.40/min (default; AgentCall holds the AI provider key) or BYOK at $0.10/min (customer provides their own AI provider key via `set_byok_openai_key`). There is no pay-as-you-go overage path on Free. Confirm the user wants inbound AI enabled on this specific number, and that the system prompt accurately describes their business.\n- `POST /v1/numbers/:id/byok-key` (`set_byok_openai_key`): switches a number's inbound AI voice from Managed billing ($0.40/min) to BYOK billing ($0.10/min) and stores the customer-supplied AI provider key for that number. Confirm the user wants to switch billing modes on the specific number, that they have a working key on hand, and that they understand the per-minute rate change before invoking.\n- `DELETE /v1/numbers/:id/byok-key` (`disable_byok`): removes the stored BYOK key on a number and reverts it to Managed billing ($0.40/min). Confirm the user wants to revert billing modes; the system prompt, voice, recording flag, and notify block on the number are preserved.\n- `POST /v1/numbers/:id/premium-voice` (`set_premium_voice`): enables Premium Voice on a number, or changes which premium voice it uses. Premium Voice is an opt-in Pro add-on: a curated voice library, the same 31 languages as the standard voice plus auto-detect, full caller memory, billed at $0.59/min only on the numbers where it is enabled (the 10 standard voices stay the default at $0.40/min). Applies to both inbound calls and outbound AI calls placed from the same number. Pass a `voiceId` from `list_premium_voices`. The number must already have inbound AI configured; enabling premium never wipes the rest of the inbound config; idempotent. Confirm the exact numberId, the chosen voice, and that the user accepts the $0.59/min premium rate before invoking. Requires Pro + a card on file + inbound AI configured, else returns 403 / 402 / 409 respectively; surface that error, do not retry.\n- `DELETE /v1/numbers/:id/premium-voice` (`disable_premium_voice`): reverts a number to the standard inbound AI voice, stopping the $0.59/min add-on. Preserves the rest of the inbound config. Idempotent. Pro plan only.\n- `list_premium_voices` (`GET /v1/calls/premium-voices`, no auth): browse the Premium Voice catalog (id, name, description, gender, accent, sampleUrl). Use the returned id with set_premium_voice.\n- Optional `record: true` on AI voice paths. $0.01/min on top of the AI rate. Mention this delta when proposing recording.\n- `create_schedule` (`POST /v1/numbers/:id/schedules`): schedules a proactive text the agent sends FIRST (a one-time appointment reminder, or a recurring digest). Each time it fires it sends one outbound SMS ($0.015 on Pro) to a real person who did not just message in, and a recurring schedule keeps firing until cancelled. Confirm the recipient, the message (or the recurrence and timezone), and the timing before creating it. Pro plan only; the number must have inbound AI / `smsMode: \"ai\"`. Offer `cancel_schedule` as soon as the schedule is no longer needed.\n\n**Irreversible actions:**\n- `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.\n- `POST /v1/calls/:callId/hangup`: terminates an in-flight call. Usually fine but confirm if the call may still be progressing toward its goal.\n\n**External-effect actions (contact real people):**\n- 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.\n- 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.\n\n**Built-in API guardrails (don't rely on these as your only check):**\n- **New live trial**: New accounts receive a one-time 72-hour live trial with one US/Canada local number, 300 managed inbound AI seconds (five minutes) total, and five SMS send attempts to verified destinations. Card verification is required before number allocation; the clock starts when allocation succeeds. There is no monthly reset or automatic paid subscription. Live OTP extraction and outbound calls require Pro. Existing Free accounts retain their assigned monthly allowances. Read the account's offerVersion, trial and limits rather than assuming every Free account has the same offer. Only describe a monthly reset when the account response supplies a non-null resetsAt.\n- Outbound AI voice + call recording require a payment method on file (Pro plan). The API returns 402 with a `setupUrl` if a Pro user has no card. Surface this to the user instead of looping.\n- **403 plan_limit_inbound_ai_trial_exhausted**: New accounts get 300 managed inbound AI seconds total within a one-time 72-hour live trial, with card verification before number allocation. Exhaustion or expiry stops new trial calls; it does not create paid overage or a monthly reset. Existing Free accounts keep their assigned monthly offer. Read get_plan or GET /v1/account before quoting limits. Before quoting allowances or taking a paid action, call get_plan (or GET /v1/account) and use the returned offerVersion, trial, limits, billingStatus and summary. New live_trial_72h_v1 accounts have a one-time 72-hour trial starting at successful number allocation, 300 managed inbound AI seconds total and five verified-destination SMS attempts; card verification is required first. No monthly reset, automatic upgrade or Free overage. Existing free_monthly_v1 accounts retain assigned monthly allowances. Live OTP extraction, outbound calls, BYOK and Premium Voice require Pro for new trial accounts. Explain payment_method_required, payment_recovery_required, trial expiry and quota errors; stop retrying them. Share the returned setup/upgrade link when the user wants to proceed, let the human complete card/payment steps, then reread get_plan before retrying. Do not assume saving a card upgrades the account, or promise a released number can be recovered. Pro is $19.99/month plus number rental and usage. Do not auto-offer upgrade_to_pro only if the user requests an upgrade just because another tool failed. Honor the user's authorization for any real-world action. Read https://api.agentcall.co/llms.txt for the current reference.\n- Every `plan_limit_*` error carries `upgradeUrl` (https://agentcall.co/billing) and `upgradeToolName` (`upgrade_to_pro`). When one comes back, tell the user what the feature costs (Pro is $19.99/mo plus usage), and only if they say yes run `upgrade_to_pro` and show them the checkout link it returns. That tool starts a Stripe Checkout session; nothing is charged until the human completes the form themselves. Never call it speculatively, and never call it more than once per conversation.\n- Redial cap: a destination can be dialed at most 3 times per UTC day (numbers the account owns or has verified are exempt). A 429 `redial_limit_exceeded` means stop dialing that number today; do not retry or try variations.\n- Rate limits: 100 req/min global; per-route limits on expensive endpoints (10 req/min on AI voice, 20 req/hour on uploads).\n- 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.\n\n### Inbound AI Configuration: Enable Only After Explicit User Confirmation; Monitor Usage; Disable When No Longer Needed\n\n`configure_inbound_ai` and `POST /v1/numbers/:id/inbound-config` with `mode: \"ai\"` should follow this procedure every time:\n\n**Pre-flight checklist (require the user to confirm each before invocation):**\n1. The exact E.164 number to configure. Read it back if the user has more than one number.\n2. The system prompt content. Read back at least the WHAT WE DO and PRICING sections so the user can correct anything inaccurate before invocation.\n3. The recording setting (`record: true` or `false`). Default to `false`. Confirm explicit opt-in if the user wants recording.\n4. The notification email and/or text (`notify.emailTo`, `notify.smsTo`). Confirm the destination belongs to the user and that they want post-call summaries delivered to it.\n5. The shortest practical call duration (`maxDurationSecs`). Pick the smallest value that fits the use case rather than relying on the 600-second default.\nNew accounts get 300 managed inbound AI seconds total within a one-time 72-hour live trial, with card verification before number allocation. Exhaustion or expiry stops new trial calls; it does not create paid overage or a monthly reset. Existing Free accounts keep their assigned monthly offer. Read get_plan or GET /v1/account before quoting limits. New live trials include five SMS send attempts total to verified destinations during the trial. Failed or ambiguous sends consume an attempt. Existing Free accounts keep their assigned monthly SMS allowance; read get_plan or GET /v1/account. Pro outbound SMS is $0.015/message, subject to account and destination restrictions.\n\n**Post-configuration responsibility:**\n- Monitor usage: periodically call `get_usage` or point the user at the dashboard at /billing.\n- Disable as soon as the configuration is no longer needed: proactively offer `disable_inbound_ai` (or `DELETE /v1/numbers/:id/inbound-config`) when the user's stated goal has been met (testing finished, campaign over, business closed for the season).\n- If the user reports unexpected calls or charges, call `disable_inbound_ai` first, then investigate.\n\nIf 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.\n\n## Phone Numbers\n\n**Provision a number:**\n```\nPOST /v1/numbers/provision\nBody: { \"type\": \"local\", \"country\": \"US\", \"label\": \"my-agent\" }\nTypes: 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).\nResponse: { \"id\": \"num_xxx\", \"number\": \"+12125551234\", \"type\": \"local\", ... }\n```\n\n**List numbers:**\n```\nGET /v1/numbers\nQuery: ?limit=20&country=US&type=local\n```\n\n**Get number details:**\n```\nGET /v1/numbers/:id\n```\n\n**Release a number (irreversible):**\n```\nDELETE /v1/numbers/:id\n```\n\n**Rename a number or change its inbound AI voice/language (partial update, preserves all other inbound config):**\n```\nPATCH /v1/numbers/:id\nBody: { \"label\": \"Hermes assistant\" }                  // rename only\nBody: { \"voice\": \"marin\" }                             // voice only (requires inbound AI already configured)\nBody: { \"language\": \"es\" }                             // language only (requires inbound AI already configured)\nBody: { \"label\": \"Hermes\", \"voice\": \"coral\", \"language\": \"fr\" }  // any combination\nVoices: alloy, ash, ballad, cedar, coral, echo, marin, sage, shimmer, verse\nLanguages: auto, en, es, fr, de, it, pt, nl, ja, ko, zh, hi, ar, ru, id, tr, pl, uk, vi, ta, ms, ro, el, cs, sv, hu, da, fi, no, sk, hr, bg  (31 languages plus auto)\nResponse: full number object including updated `inbound` block.\n```\nUse this when the user wants to change the voice or language on an existing receptionist. Do NOT call `POST /v1/numbers/:id/inbound-config` for a voice or language change. That endpoint replaces the entire inbound config and would wipe the system prompt, first message, recording flag, and notify block.\n\n## Inbound AI Voice (72-hour live trial; Pro Managed $0.40/min or BYOK $0.10/min)\n\nConfigure a phone number so incoming calls are answered autonomously by an AI voice agent. The AI follows the system prompt you set.\n\nAfter 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.\n\n**Configure inbound AI on a number:**\n```\nPOST /v1/numbers/:numberId/inbound-config\nBody: {\n  \"mode\": \"ai\",\n  \"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.\",\n  \"voice\": \"shimmer\",\n  \"language\": \"auto\",\n  \"firstMessage\": \"Hi, thanks for calling Acme Plumbing. How can I help?\",\n  \"maxDurationSecs\": 300,\n  \"transferTo\": \"+14155551234\",\n  \"notify\": {\n    \"emailTo\": \"owner@acmeplumbing.com\",\n    \"smsTo\": \"+14155551234\",\n    \"businessName\": \"Acme Plumbing\",\n    \"agencyName\": \"Acme Plumbing\"\n  }\n}\n```\n\nThe `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. Set `notify.smsTo` (E.164 phone) to also receive a short text summary of each call (caller, what they wanted, urgency, callback time), US-local senders only, one text per call (spam skipped), reply STOP to opt out, billed as one outbound SMS ($0.015). `emailTo` and `smsTo` are independent: set either, both, or neither. The MCP `configure_inbound_ai` tool also accepts `notify`: agents in Claude Desktop, Cursor, Windsurf, etc. can configure the email and text destinations in the same call as the system prompt, no dashboard handoff needed.\n\n**Transfer to a human (optional):** set `transferTo` (an E.164 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; whoever answers sees the caller's number, not the AgentCall number. If nobody picks up within about 25 seconds, the AI resumes and takes a message instead, so the caller is never dropped. Works with no webhook or tool setup and coexists with declared `tools`. AI minutes stop at the handoff; the human portion of the call bills at the standard $0.035/min voice rate. Transfers show as `transferredTo` / `transferredAt` on the call record. Omit or pass `null` for no transfer (the AI takes a message, the default). Confirm the transfer destination with the user before configuring it: it is a real phone that will ring on live calls.\n\n**Spoken language (optional, default 'auto'):** the `language` field controls what language the AI answers in. `'auto'` matches the caller's language naturally and is what existing receptionists do today. Pass a specific ISO-639-1 code to make the AI respond ONLY in that language even if the caller speaks another, useful when the business serves a specific language community. Supported (31 languages plus auto): `auto`, `en` (English), `es` (Spanish), `fr` (French), `de` (German), `it` (Italian), `pt` (Portuguese), `nl` (Dutch), `ja` (Japanese), `ko` (Korean), `zh` (Chinese Mandarin), `hi` (Hindi), `ar` (Arabic), `ru` (Russian), `id` (Indonesian), `tr` (Turkish), `pl` (Polish), `uk` (Ukrainian), `vi` (Vietnamese), `ta` (Tamil), `ms` (Malay), `ro` (Romanian), `el` (Greek), `cs` (Czech), `sv` (Swedish), `hu` (Hungarian), `da` (Danish), `fi` (Finnish), `no` (Norwegian), `sk` (Slovak), `hr` (Croatian), `bg` (Bulgarian). Premium Voice covers the same 31 languages plus `auto`. The directive is added at session-build time so the customer's `systemPrompt` stays unchanged when language is swapped. Use `update_number_language` to change just the language without touching anything else.\n\n**Pre-call context webhook (optional):** add a `contextWebhook` block to wire a live context source onto the number. When set, AgentCall POSTs to your HTTPS URL on every inbound call connect (HMAC-signed with `signingSecret`); your endpoint responds with `{\"contextBlock\":\"...\"}` and AgentCall merges that string onto the system prompt before the AI answers. Useful for injecting today's brief, current priorities, or recent email signals so the AI speaks with up-to-date data instead of a static prompt. Example:\n```\n\"contextWebhook\": {\n  \"url\": \"https://hermes.your-domain.com/agentcall/precall\",\n  \"signingSecret\": \"<32+ char shared secret>\",\n  \"timeoutMs\": 1200\n}\n```\nFail-open: any error in the webhook leaves the call running with the static prompt. Walkthrough at https://agentcall.co/docs/hermes.\n\n**Optional call recording (Pro plan, $0.01/min on top of the AI voice rate):**\nAdd `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.\n\n**Get current inbound config:**\n```\nGET /v1/numbers/:numberId/inbound-config\n```\n\n**Disable inbound AI (calls hang up at carrier):**\n```\nDELETE /v1/numbers/:numberId/inbound-config\n```\n\n### Voice billing mode: Managed vs BYOK (per number)\n\nEach Pro number with inbound AI configured chooses one of two billing modes for its AI voice minutes:\n\n- **Managed** (default): $0.40/min. AgentCall holds the AI provider key on the customer's behalf. Simplest setup; no key handling on the customer side.\n- **BYOK**: $0.10/min. The customer provides their own AI provider key; AgentCall bills only the platform overhead. The same number's system prompt, voice, recording flag, and notify block are preserved across mode switches.\n\nMemory, transcripts, post-call email and text summaries, the `call.transcript` and `call.report.ready` webhook events, and call recording all work identically on both modes.\n\n**Switch a number to BYOK (set or rotate the key):**\n```\nPOST /v1/numbers/:numberId/byok-key\nBody: { \"openaiApiKey\": \"sk-...\" }\nResponse: { \"voiceMode\": \"byok\", \"hasByokKey\": true, \"byokOpenaiApiKeyPreview\": \"sk-...abcd\" }\n```\n\n**Switch a number back to Managed (revert billing mode):**\n```\nDELETE /v1/numbers/:numberId/byok-key\nResponse: { \"voiceMode\": \"managed\", \"hasByokKey\": false, \"byokOpenaiApiKeyPreview\": null }\n```\n\n**Inspect the current mode** (the existing inbound-config response now includes voiceMode + hasByokKey + byokOpenaiApiKeyPreview):\n```\nGET /v1/numbers/:numberId/inbound-config\nResponse: {\n  ...inbound config fields...,\n  \"voiceMode\": \"managed\" | \"byok\",\n  \"hasByokKey\": boolean,\n  \"byokOpenaiApiKeyPreview\": \"sk-...abcd\" | null\n}\n```\n\nThe stored key is write-only; the GET response surfaces a redacted preview (last 4 chars) and a boolean, never the full value. Rotating is a re-POST to `byok-key` with the new value; AgentCall replaces the stored value atomically.\n\n## Browse Voices and Prompt Templates (no auth)\n\nBoth endpoints are public. Call them before configuring AI voice to avoid hallucinated business details and to pick a voice that fits the use case.\n\n**List the 10 voices with samples:**\n```\nGET /v1/calls/voices\nReturns: { voices: [{ id, name, trait, description, bestFor, sampleUrl? }, ...], defaultVoice: \"shimmer\" }\n```\nThe newest natural-sounding picks are `marin` (soft, natural) and `cedar` (warm, grounded). The original 8 (`shimmer`, `sage`, `ash`, `ballad`, `coral`, `echo`, `verse`, `alloy`) ship with sample MP3s; marin and cedar are live-preview only for now.\n\n**List the premium voices (`list_premium_voices`):**\n```\nGET /v1/calls/premium-voices\nReturns: { voices: [{ id, name, description, gender, accent, sampleUrl }, ...], pricing: { premiumVoice: \"$0.59/minute\" } }\n```\nPremium Voice is the higher-quality, brandable tier for inbound AI receptionists: a curated voice library, the same 31 languages as the standard voice plus auto-detect, and full caller memory, a Pro add-on at $0.59/min.  Each entry's `id` is the voiceId; preview it via the returned `sampleUrl`. Enable it on a number with `set_premium_voice` (numberId + voiceId), or from the dashboard (a number's inbound AI settings, then the Premium Voice section); revert with `disable_premium_voice`. As a billable add-on, confirm the user accepts the $0.59/min premium rate on the specific number before enabling.\n\n**List ready-made prompt templates:**\n```\nGET /v1/calls/prompt-templates\nReturns 5 templates with [BRACKETED] placeholders to fill in:\n- receptionist (Front Desk). Recommends shimmer voice\n- lead-qualifier (Sales, BANT-style). Coral\n- appointment-booker. Sage\n- customer-support (FAQ Deflection). Ash\n- call-screener (Anti-Spam). Verse\nEach entry includes: id, title, description, recommendedVoice, maxDurationSecs, firstMessage, systemPrompt.\n```\n\nFor a comprehensive prompt-writing guide: https://agentcall.co/docs/voice-prompts\n\n## New-Account Outbound Restriction (read before the first outbound text or call)\n\nA new account may not *call* an arbitrary number, and a Pro account under 7 days old may only text new numbers within its starter allowance (below). Attempting anything past that returns `403 destination_not_verified`. This is enforced on every outbound path, including proactive schedules (which never use the starter allowance). Retrying does not help.\n\nNew live trials include five SMS send attempts total to verified destinations during the trial. Failed or ambiguous sends consume an attempt. Existing Free accounts keep their assigned monthly SMS allowance; read get_plan or GET /v1/account. Pro outbound SMS is $0.015/message, subject to account and destination restrictions. New live trials do not use the legacy starter-destination exception. Existing Free and new Pro accounts can have separate starter allowances; read account and verification status. Never retry destination restrictions in a loop.\n\nA restricted account CAN already:\n- contact any number the account owns (agent-to-agent testing works immediately)\n- reply to anyone who contacted it first, within the last 30 days (inbound threads and callbacks are unaffected)\n- contact any number verified individually: `POST /v1/verified-destinations` with `{ \"phone\": \"+14155551234\" }` sends a 6-digit code there, then `POST /v1/verified-destinations/:id/confirm` with `{ \"code\": \"123456\" }`. Cap 25 on Pro, 5 on Free.\n\nNone of the three paths above consume a starter slot. Only a text to a brand-new stranger does.\n\nTo lift the restriction entirely (Pro only), the account owner submits a business verification:\n```\nPOST /v1/business-verification\nBody: {\n  \"legalName\": \"Ridgeline Painting LLC\",\n  \"website\": \"https://ridgelinepainting.com\",   // website OR ein required\n  \"contactName\": \"Dana Whitfield\",\n  \"useCase\": \"Payment reminders to existing customers with unpaid invoices, including a pay link.\",\n  \"sampleMessage\": \"Invoice 4021 for $840 is 12 days past due. Pay here: example.com/pay/4021. Reply STOP to opt out.\"\n}\nGET /v1/business-verification    # returns grantsOutboundPilot: can this account contact strangers now?\n```\nThis lifts the restriction on submission (a human reviews afterwards). A daily cap on distinct NEW recipients applies while the account is under 7 days old, starting at 25 on day one. After 7 days on Pro the restriction lifts automatically regardless.\n\n**If you are an AI agent and hit this error:** do not retry, do not try other numbers to find one that works, and do not attempt to work around it. Report it to the user and tell them the two routes above. Submitting the business verification requires the user's own business details, so ask them for those rather than inventing any.\n\n## SMS\n\n**Send SMS:**\n```\nPOST /v1/sms/send\nBody: { \"from\": \"num_xxx\", \"to\": \"+14155551234\", \"body\": \"Hello!\" }\n\"from\" can be a number ID or E.164 phone string\n```\n\n**Get inbox:**\n```\nGET /v1/sms/inbox/:numberId\nQuery: ?limit=20&otpOnly=true\n```\n\n**Get a specific message:**\n```\nGET /v1/sms/:messageId\n```\n\n**Wait for OTP code (long-polls up to 60 seconds):**\n```\nGET /v1/sms/otp/:numberId\nQuery: ?timeout=60000\nResponse: { \"otp\": \"482913\", \"message\": { ... } }\n```\n\n## Two-Way AI SMS and Relay Mode\n\nA number can answer inbound texts, not just parse OTPs. Set this on the same inbound config endpoint that sets up the AI receptionist (POST /v1/numbers/:numberId/inbound-config) via the `smsMode` field:\n\n- `smsMode: \"ai\"`: AgentCall's AI answers each inbound text following your prompt, remembers the contact across voice and SMS, and can return real quotes by calling tools you declare. Declare them with `tools` and host them at `actionWebhook` (HMAC-signed, the same security model as the pre-call context webhook). The AI calls your tool, you return the real value, the AI texts it back instead of guessing. Pro plan, managed only, billed as one outbound text per reply.\n- `smsMode: \"relay\"`: AgentCall runs no AI of its own. It forwards each inbound text to your own agent at `agentWebhook` (HMAC-signed), and your agent replies on its own schedule, so you can text your own agent on a real number. Use `allowedSenders` (E.164 array, up to 20) to restrict which numbers can reach the agent, so a personal agent answers only its owner. Billed as plain texts, no relay fee.\n\nConfig fields on configure_inbound_ai: `smsMode` (\"off\" | \"ai\" | \"relay\"), `smsSystemPrompt`, `actionWebhook`, `tools`, `agentWebhook`, `allowedSenders`.\n\nThe same `tools` + `actionWebhook` pair also powers in-call VOICE tool calling: on an inbound AI voice call, the agent can call the declared tools mid-call (check real calendar availability, look up an order) and the JSON result feeds back into the live conversation. Each tool call is HMAC-POSTed to the actionWebhook with `context.channel` set to \"voice\" and `context.callId` populated. Errors degrade gracefully (the agent says it could not complete the action rather than inventing a result). The per-call count appears as `toolCallCount` on the call record and in the call report. Works alongside the pre-call context webhook.\n\n**Read SMS threads:**\n```\nGET /v1/sms-conversations            # list threads (paginated)\nGET /v1/sms-conversations/:id        # one thread + last 50 messages + context\n```\nMCP tools: list_sms_conversations, get_sms_conversation.\n\nThe thread detail also returns a `context` object that classifies those same messages by age, and you should use it for anything about recency. `messages` is the last 50 texts on the thread, which on a quiet thread can span months, so treating them as a recent conversation makes you describe a months-old exchange as something you just talked about. `context.recentMessages` covers the last 7 days, `context.recentSubstantiveMessages` is that list with plain greetings removed, and `context.olderMessages` is background only. Answer \"what did we recently talk about?\" from `recentSubstantiveMessages` alone; when it is empty, say there has been no recent substantive text discussion rather than reaching into `olderMessages`, durable memory, or call history and presenting any of them as a recent text conversation. `context.freshness` carries the window and the reference time it was measured against.\n\n**Reply into a thread (relay mode):**\n```\nPOST /v1/sms-conversations/:id/reply\nBody: { \"body\": \"3 emails need you today.\", \"idempotencyKey\": \"turn_8842\" }\n```\nYour own agent calls this when it has an answer; AgentCall sends and threads the text. Opt-out-checked (refuses to text someone who sent STOP) and idempotent on `idempotencyKey` for 24 hours so a retried agent never double-texts. MCP tool: reply_to_sms_conversation. Billed as one outbound text.\n\nThe relay push to your `agentWebhook` carries the same freshness-classified thread as an additive `smsContext` field beside `message`, `conversation`, and `context`, so your agent gets the recency split without a second API call. An endpoint written against the earlier payload keeps working unchanged.\n\nSTOP and UNSUBSCRIBE are always honored before either mode runs. Both modes are reactive: they handle texts that arrive. To open a conversation yourself, send the first message with `POST /v1/sms/send` (`send_sms`) or set a proactive schedule (below); the contact's reply lands on the same thread and is handled by whichever mode the number is in.\n\n## Proactive Scheduling (the agent texts first)\n\nTwo-way AI SMS is reactive: the number answers when someone texts it. Proactive scheduling makes a number's agent reach out FIRST on a schedule, so it can send appointment reminders, payment follow-ups, and recurring digests without the contact messaging in. Pro plan only (proactive sends never fire on Free). The send itself works on any provisioned number; set `smsMode: \"ai\"` when you want the contact's reply answered automatically on the same thread, so a one-word answer like \"C\" is understood in context. Each fire is billed as one standard outbound text, is skipped for anyone who has sent STOP, and is capped at 200 per number per day.\n\n```\nPOST   /v1/numbers/:numberId/schedules     # create a schedule\nGET    /v1/numbers/:numberId/schedules      # list schedules (?status= optional)\nDELETE /v1/numbers/:numberId/schedules/:id  # cancel + remove\n```\n\nEach schedule is one of two timings and one of two message styles:\n- Timing: `fireAt` (a one-time ISO 8601 instant in the future, for reminders) OR `recurrence` (`{ frequency: \"daily\" | \"weekly\", hour, minute, dayOfWeek }` interpreted in `timezone`, for digests). Provide exactly one.\n- Message: `template` (sent verbatim, with `{{placeholders}}` filled from `payload`) OR `promptHint` (the agent composes the message using its memory of the contact). Provide exactly one.\n\nPass `dedupeKey` to make a re-create safe: a duplicate key on the same number returns 409, so a calendar sync can create the same reminder repeatedly without duplicating it.\n\n```\nPOST /v1/numbers/num_abc/schedules\nBody: {\n  \"kind\": \"reminder\",\n  \"contactPhone\": \"+14155551234\",\n  \"fireAt\": \"2026-06-09T19:00:00Z\",\n  \"template\": \"Hi {{name}}, reminder: your {{service}} is tomorrow at {{time}}. Reply C to confirm.\",\n  \"payload\": { \"name\": \"Marcus\", \"service\": \"cleaning\", \"time\": \"2pm\" },\n  \"dedupeKey\": \"reminder:appt_8841:24h\"\n}\n```\n\nMCP tools: create_schedule, list_schedules, cancel_schedule. A calendar integration is just a client of create_schedule: post one reminder per appointment with a stable dedupeKey. Each send is billed as one outbound text ($0.015 on Pro); confirm recipient, message, and timing with the user before scheduling, and offer cancel_schedule when it is no longer needed.\n\n## Outbound Voice Calls\n\n**Start a standard outbound call:**\n```\nPOST /v1/calls/initiate\nBody: { \"from\": \"num_xxx\", \"to\": \"+14155551234\", \"record\": false }\n```\n\n**Start an outbound AI voice call (Pro plan, $0.40/min. Billable, contacts real human, confirm with user first):**\nThe AI handles the entire conversation autonomously based on your systemPrompt.\n```\nPOST /v1/calls/ai\nBody: {\n  \"from\": \"num_xxx\",\n  \"to\": \"+14155551234\",\n  \"systemPrompt\": \"You are calling to schedule a dentist appointment for Tuesday afternoon.\",\n  \"voice\": \"shimmer\",\n  \"language\": \"auto\",\n  \"firstMessage\": \"Hi, I'd like to schedule an appointment please.\",\n  \"maxDurationSecs\": 600,\n  \"record\": false\n}\n```\nAdd `record: true` to capture an mp3 of the call. Adds $0.01/min on top.\n\nOptional fields for orchestrators:\n- `metadata`: a string-to-string map (at most 24 keys, 64-char keys, 512-char values, 2KB serialized) echoed on the call object and in every subsequent webhook payload (call.status, call.transcript, call.recording, call.report.ready). When the destination is another number on the same account, the linked inbound leg carries the same metadata. Use it to tag calls with your own IDs (showId, segmentId) instead of joining on callId.\n- `liveTranscript: true`: stream the transcript live. Each finalized utterance fires a `transcript.partial` webhook during the call ({ callId, sequence, role, text, timestamp }, sequence is monotonic per call) within a second or two of speech. Requires a webhook subscribed to `transcript.partial`. The final `call.transcript` stays unchanged and authoritative.\n- Calls between two numbers on the same account expose `peerCallId` on both call records and in webhook payloads, linking the outbound and inbound legs.\n\n**Spoken language on outbound calls (optional, default 'auto'):** the `language` field controls what language the AI speaks during the call. `'auto'` lets the AI match the recipient's language naturally. Pass a specific ISO-639-1 code to make the AI respond ONLY in that language. Useful for booking appointments or requesting info on behalf of someone in another language, e.g. `language: 'es'` to call a Spanish-speaking doctor's office on behalf of a customer who doesn't speak Spanish. Supported (31 languages plus auto): `auto`, `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `ja`, `ko`, `zh`, `hi`, `ar`, `ru`, `id`, `tr`, `pl`, `uk`, `vi`, `ta`, `ms`, `ro`, `el`, `cs`, `sv`, `hu`, `da`, `fi`, `no`, `sk`, `hr`, `bg`. The `firstMessage` stays verbatim, so if you want the greeting in Spanish, write the firstMessage in Spanish yourself; the language setting only governs the AI's responses after.\n\n**Outbound prompt templates** (no auth, public): fetch `GET /v1/calls/prompt-templates?direction=outbound` for three ready-made outbound templates with `[BRACKETED]` placeholders to fill in: `outbound-appointment-booker` (book an appointment on behalf of someone), `outbound-info-request` (call to ask a specific question on behalf of someone), `outbound-callback-confirmation` (follow up on something).\n\nVoices (10 total, default: shimmer; preview the original 8 via GET /v1/calls/voices, marin and cedar are live-preview only):\n- marin: soft, natural. New top pick for receptionist, support, conversational small business\n- cedar: warm, grounded. New. Advisory, healthcare, trust-building calls\n- shimmer: bright, energetic. Long-running default\n- sage: calm, authoritative, confident. Healthcare, finance, advisory\n- ash: warm, conversational. Customer service, support lines\n- ballad: expressive, melodic. Engaging, narrative conversations\n- coral: clear, professional. B2B calls, sales\n- echo: resonant, deep. Formal inquiries, executive comms\n- verse: smooth, articulate. Premium or luxury, executive communication\n- alloy: neutral, balanced. Generic notifications, IVR-style flows\n\n### Saved outbound AI agent per number (Pro plan)\n\nSave a reusable outbound AI agent on a phone number so repeat outbound calls from the same number reuse the same configuration. The dashboard Place AI call dialog hydrates from this blob; MCP clients can read it back instead of asking the user to retype the prompt every call. This is independent of the inbound AI receptionist on the same number; configuring one does not change the other.\n\nThe saved blob holds: `systemPrompt`, `voice`, `language`, `firstMessage`, `maxDurationSecs`, `record`, and an optional `templateId` (the outbound prompt template used to seed it, when applicable).\n\n**Save the outbound agent on a number:**\n```\nPOST /v1/numbers/:numberId/outbound-defaults\nBody: {\n  \"systemPrompt\": \"You are calling on behalf of Acme Plumbing to confirm tomorrow's 10am appointment.\",\n  \"voice\": \"shimmer\",\n  \"language\": \"auto\",\n  \"firstMessage\": \"Hi, calling to confirm tomorrow's appointment.\",\n  \"maxDurationSecs\": 300,\n  \"record\": false,\n  \"templateId\": \"outbound-callback-confirmation\"\n}\n```\n\n**Read the saved outbound agent (returns null if none set):**\n```\nGET /v1/numbers/:numberId/outbound-defaults\n```\n\n**Remove the saved outbound agent:**\n```\nDELETE /v1/numbers/:numberId/outbound-defaults\n```\n\nThe MCP tools `set_outbound_defaults`, `get_outbound_defaults`, and `clear_outbound_defaults` mirror these endpoints. `list_numbers` and `get_number` responses include an `outbound` field alongside the existing `inbound` field, so a single fetch surfaces both per-number configurations.\n\n### Hydrating from the saved outbound agent and replay-safe retries\n\n`POST /v1/calls/ai` (MCP `initiate_ai_call`) accepts two optional input fields designed for CSV-driven outbound runs.\n\n**`useSavedAgent: boolean`**: when true, AgentCall hydrates the omitted call fields (`systemPrompt`, `voice`, `language`, `firstMessage`, `maxDurationSecs`, `record`) from the saved outbound agent on the `from` number. Per-call values in the same request always win, so the saved persona can be inherited while `firstMessage` is personalized per recipient. If the `from` number has no saved outbound agent, the API returns 400 with code `no_saved_agent`; call `set_outbound_defaults` first or supply the fields inline.\n\n**`idempotencyKey: string`** (1 to 200 chars, scoped per phone number): a duplicate request to `POST /v1/calls/ai` with the same `from` + `idempotencyKey` pair replays the original response and does not place a second carrier call. The replayed response carries an `X-AgentCall-Idempotency-Replayed: true` header. Uniqueness is enforced at the database layer, so concurrent retries are race-safe.\n\n**Canonical CSV-runner pattern** (one row per call, replay-safe across retries, persona stored once on the number):\n```\n{\n  \"from\": \"num_xxx\",\n  \"to\": \"+14155551234\",\n  \"useSavedAgent\": true,\n  \"idempotencyKey\": \"batch-2026-05-25:row-0042\",\n  \"firstMessage\": \"Hi Jamie, calling to confirm tomorrow's 10am appointment.\"\n}\n```\n\nThis is the recommended shape for CSV-driven outbound on a Hermes-style runner. The persona lives on the number via `set_outbound_defaults`; each row supplies only the recipient, a per-row `idempotencyKey`, and an optional per-row override.\n\n**List call history:**\n```\nGET /v1/calls\nQuery: ?limit=20\n```\n\n**Get call details:**\n```\nGET /v1/calls/:callId\n```\n\n**Get AI call transcript:**\n```\nGET /v1/calls/:callId/transcript\nResponse: { \"entries\": [{ \"role\": \"ai\" | \"human\", \"text\": \"...\", \"timestamp\": \"...\" }], \"summary\": \"...\", \"duration\": 111 }\n```\n\n**Hang up an active call:**\n```\nPOST /v1/calls/:callId/hangup\n```\n\n## Standalone Text to Speech (Pro plan, $0.03 per 1,000 characters)\n\nTurn text into spoken audio in the SAME 10 voices the AI uses on calls, so a number's voice identity carries off-call to IVR prompts, voicemail greetings, generated show segments, and social clips.\n\n```\nPOST /v1/tts\nBody: { \"text\": \"Thanks for calling Acme. We're open 9 to 5.\", \"voice\": \"marin\", \"format\": \"mp3\" }\nReturns: raw audio bytes (audio/mpeg or audio/wav) + x-agentcall-tts-characters header\n```\n\nFields: `text` (1-4096 characters, required; chunk longer copy), `voice` (one of the 10 call voices, default shimmer), `format` (\"mp3\" default or \"wav\"), `language` (optional ISO-639-1 hint). Billed per character of input text; confirm the text and approximate cost with the user before synthesizing large batches. MCP tool: `synthesize_speech` (returns the audio inline). SDK: `client.tts.synthesize({ text, voice, format })`.\n\n## AgentFM Callback\n\nAgentFM is a live podcast powered by AgentCall outbound premium voice. Guests request a callback and the AI host calls them back to record a short conversation.\n\n**Request a callback (no auth required):**\n```bash\ncurl -X POST https://api.agentcall.co/v1/agentfm/callback-request \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"phone\":\"+15551234567\",\"persona\":\"I build AI agents and want to discuss voice interfaces.\"}'\n```\n\nResponse: `{ \"status\": \"queued\" }` or `{ \"status\": \"already_pending\" }` (24h dedup per phone).\n\nMCP tool: `request_agentfm_callback(phone, persona?)`. No AgentCall account or plan required to call this tool. Rate limit: 3 requests per hour per IP. Deduplicated per phone per 24 hours so calling this multiple times for the same number is safe.\n\nWeb form for guests: https://agentcall.co/agentfm\n\n## Webhooks\n\n> **Important: webhooks here are for OUTBOUND event delivery, NOT inbound call routing.**\n> AgentCall POSTs to your URL when events fire (SMS received, OTP detected, call completed,\n> recording ready, etc.). Webhooks are NOT how you make a phone number answer incoming calls.\n> To configure how a number answers when called, use the **Inbound AI Voice** section above\n> (`POST /v1/numbers/:numberId/inbound-config`). Not webhooks. (If you're coming from Twilio:\n> AgentCall replaces Twilio's inbound voice webhook URL with `configure_inbound_ai`.)\n\n**Register a webhook:**\n```\nPOST /v1/webhooks\nBody: { \"url\": \"https://example.com/hook\", \"events\": [\"sms.inbound\", \"sms.otp\", \"call.status\"] }\nEvents: sms.inbound, sms.otp, sms.ai_reply, call.inbound, call.ringing, call.status, call.recording, call.transcript, call.report.ready, transcript.partial, number.released\n```\n\nCall status values are canonical everywhere (REST and webhooks): `initiated` -> `ringing` -> `in-progress` -> `completed`, with `busy`, `no_answer`, or `failed` for calls that never connect. Call webhook payloads also carry `peerCallId` (the other leg of a same-account agent-to-agent call, or null) and the call's `metadata` map when set on dial.\n\n`transcript.partial` is the live-stream complement to `call.transcript`: opt in with `liveTranscript: true` on `POST /v1/calls/ai` or on a number's inbound-config, and each finalized utterance is delivered during the call as { callId, sequence, role, text, timestamp }.\n\n**List webhooks:**\n```\nGET /v1/webhooks\n```\n\n**Rotate webhook secret:**\n```\nPOST /v1/webhooks/:id/rotate\n```\n\n**Delete a webhook:**\n```\nDELETE /v1/webhooks/:id\n```\n\n### Post-call transcript webhook (`call.transcript`)\n\nWhen the user wants their AI agent to learn from inbound AI calls, subscribe a webhook to the `call.transcript` event. AgentCall POSTs the full transcript and an LLM-extracted summary to the configured URL after each inbound AI call ends.\n\n**Subscribe:**\n```\nPOST /v1/webhooks\nBody: { \"url\": \"https://agent.example.com/agentcall/transcript\", \"events\": [\"call.transcript\"] }\n```\n\n**Payload shape:**\n```\n{\n  \"callId\": \"call_xxx\",\n  \"duration\": 53,\n  \"transcript\": [\n    { \"role\": \"ai\" | \"human\", \"text\": \"...\", \"timestamp\": \"ISO 8601\" }\n  ],\n  \"summary\": {\n    \"summary\": \"1-2 sentence plain English\",\n    \"callerName\": \"string or null\",\n    \"intent\": \"service_request | quote_request | scheduling | complaint | spam | general_inquiry | other\",\n    \"urgency\": \"high | medium | low\",\n    \"callbackBy\": \"string or null\",\n    \"spam\": true | false\n  }\n}\n```\n\n**Required handling on the receiving endpoint:**\n- Verify the HMAC-SHA256 signature in the `X-AgentCall-Signature` header using the webhook's signing secret. Reject mismatches with a non-2xx response.\n- Dedup on `callId`. AgentCall retries with exponential backoff until it receives a 2xx, so a slow first response can produce a duplicate delivery.\n- Acknowledge fast: return 2xx as soon as the payload is verified and persisted. Heavy processing belongs in a background job, not inline on the request.\n\n**Integration patterns:**\n- **Store** the payload to a database row keyed by `callId` and let the agent read it on its own schedule.\n- **Forward** the payload to an agent platform's ingest endpoint for real-time follow-up.\n- **Queue** the payload on a public bridge for a local agent platform to drain on cron. Reference bridge: github.com/Kintupercy/agentcall-hermes-bridge v0.2.0 exposes `POST /agentcall/transcript` (HMAC-verified queue append, max 100 entries, oldest dropped) and `POST /hermes/pull-transcripts` (`X-Hermes-Push-Key` authed read-and-clear).\n\nFull walkthrough with code examples: https://agentcall.co/docs/post-call-webhook.\n\n## Auditable Call Memory\n\nEvery completed AI call can be auto-extracted into structured, source-backed memory: contacts, facts, preferences, commitments, tasks, briefs. Each memory item carries a verbatim transcript quote as evidence and a full audit timeline. Cross-call memory means an inbound or outbound AI call can be aware of what was said in prior calls from the same number, automatically.\n\nMemory is opt-in per agent: set `memoryEnabled: true` on your agent (currently via the dashboard or direct DB update; account-level toggle endpoint is planned). Once enabled, every completed AI call produces a `CallReport` and a set of `MemoryCandidate` rows roughly 5 to 30 seconds after the call ends.\n\n### Contacts\n\nA `Contact` is one caller per phone per agent. Created automatically on the first call from or to a new number when memory is enabled. Contains `displayName`, `tags`, `ownerNotes`, `verified`, `blockedAt`, `callCount`, `lastSeenAt`. Caller ID is NOT verified by AgentCall by default; `verified` is owner-set or future STIR/SHAKEN attestation.\n\n**List contacts:**\n```\nGET /v1/contacts?limit=20&cursor=...\n```\n\n**Look up by phone (E.164):**\n```\nGET /v1/contacts/by-phone/+14155551234\n```\n\n**Edit owner fields:**\n```\nPATCH /v1/contacts/:id\nBody: { displayName?, tags?, ownerNotes?, verified?, blockedAt? }\n```\n\n**Right-to-forget** (wipes Memory + MemoryCandidate + Brief; redacts CallReport payloads; preserves Call + transcript audit shell):\n```\nDELETE /v1/contacts/:id\n```\n\nFile v2.13.1:skill-card.md\n\n## Description:\n\nAgentCall gives agents access to real phone numbers for SMS, authorized OTP retrieval, voice calls, AI receptionists, proactive messages, and call memory through the AgentCall API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[kintupercy](https://clawhub.ai/user/kintupercy)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use AgentCall to let an agent provision phone numbers, send and receive SMS, answer or place calls with AI voice, retrieve authorized OTPs, schedule proactive messages, and maintain call memory. It is suited for authorized business communication and agent-to-phone workflows that require user confirmation for real-world actions.\n\n### Deployment Geography for Use:\n\nGlobal; telephony features depend on AgentCall's documented carrier and destination support.\n\n## Known Risks and Mitigations:\n\nRisk: The skill can make real-world calls, send SMS messages, and trigger billing.\n\nMitigation: Review costs and require explicit user confirmation before outbound calls, texts, number provisioning, premium voice, recording, schedules, or other paid actions.\n\nRisk: OTP retrieval can be misused against services the user does not control.\n\nMitigation: Use OTP workflows only for systems the user owns or is authorized to test.\n\nRisk: Call recording and call memory can retain sensitive communications.\n\nMitigation: Confirm recording consent, monitor retained call memory, and disable or purge configurations when no longer needed.\n\nRisk: Persistent AI receptionists, schedules, and webhooks can continue acting after initial setup.\n\nMitigation: Monitor active configurations and disable receptionists, schedules, webhooks, or memory when the user's task is complete.\n\n## Reference(s):\n\n- [AgentCall ClawHub Skill Page](https://clawhub.ai/kintupercy/skills/agentcall)\n- [AgentCall API Reference](https://api.agentcall.co/llms.txt)\n- [AgentCall Billing](https://agentcall.co/billing)\n- [AgentCall Voice Prompt Guide](https://agentcall.co/docs/voice-prompts)\n- [AgentCall Pre-Call Context Webhook Walkthrough](https://agentcall.co/docs/hermes)\n- [AgentCall Post-Call Webhook Walkthrough](https://agentcall.co/docs/post-call-webhook)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with API paths, JSON examples, shell commands, and configuration instructions]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires AGENTCALL_API_KEY for authenticated AgentCall API actions; some actions can bill money, contact real people, create persistent configurations, or retain call data and must be confirmed with the user.]\n\n## Skill Version(s):\n\n2.13.1 (source: evidence.release.version and artifact/claw.json version; changelog dated 2026-09-08)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.13.1:claw.json\n\n{\n  \"name\": \"agentcall\",\n  \"version\": \"2.13.1\",\n  \"summary\": \"Phone numbers, SMS, two-way AI SMS plus relay mode (text your own agent on a real number), proactive scheduling (the agent texts first: appointment reminders and recurring digests), AI voice agents (Managed $0.40/min, BYOK $0.10/min, or Premium Voice $0.59/min on inbound + outbound) with 31 languages plus auto-detect, and Auditable Call Memory (cross-call contacts, structured call reports, the next-call context block) for AI agents. 62 tools. VoIP-routed via licensed US carriers.\",\n  \"description\": \"Phone numbers, SMS, voice calls, inbound + outbound AI voice with multilingual support, AND Auditable Call Memory for AI agents. Provision US/CA numbers, send/receive texts, extract OTP codes for apps you control, configure phone numbers to be answered by an AI voice agent (with plain-English email summaries and optional MP3 recordings after every call), or place autonomous AI-powered outbound calls. Inbound texts can be answered too: set smsMode to 'ai' so AgentCall's AI replies and pulls real quotes by calling tools you host through the action bridge, or set smsMode to 'relay' so AgentCall runs no AI and forwards each text to your own agent and sends its reply back, letting you text your own agent on a real number. AI voice supports 31 languages plus auto-detect on both directions: 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. Default is auto (matches the caller naturally); pin a specific language to keep the AI in that language even if the other party speaks another, useful for businesses serving a specific language community or for outbound errands like booking a Spanish doctor's appointment on behalf of someone. Inbound AI voice ships in two billing modes per number: Managed at $0.40/min (AgentCall holds the AI provider key, simplest setup) or BYOK at $0.10/min (customer provides their own AI provider key, AgentCall bills only the platform overhead). Premium Voice is an opt-in Pro add-on that answers inbound calls with a more natural, brandable voice from a curated library, in the same 31 languages as the standard voice plus auto-detect, with full caller memory, at $0.59/min only on numbers where it is enabled. Enable it per number from the dashboard or programmatically via the set_premium_voice MCP tool (disable_premium_voice to revert, list_premium_voices to browse). Memory is included on every plan and every voice mode. Every completed AI call auto-extracts into structured, source-backed memory: contacts, facts, preferences, commitments, tasks, briefs. Cross-call memory means a returning caller is recognized and the AI starts with what was said last time. Ask AgentCall what is known about any phone number before placing a call via get_next_call_context. Numbers are VoIP-routed via licensed US carriers and not intended for consumer-platform signup verification (Stripe, WhatsApp, banks, etc.). A number's AI agent can also text first on a schedule: create_schedule sets up one-time appointment reminders or recurring digests, a reply to a proactive text threads back into the same AI conversation, and a calendar integration is just a client of create_schedule. Tools that cost money, contact real people, or wipe memory are explicitly flagged so agents confirm with the user before invoking.\",\n  \"author\": \"agentcall\",\n  \"license\": \"MIT-0\",\n  \"permissions\": [\n    \"network\"\n  ],\n  \"entry\": \"instructions.md\",\n  \"tags\": [\n    \"phone\",\n    \"sms\",\n    \"voice\",\n    \"otp\",\n    \"verification\",\n    \"calls\",\n    \"ai-voice\",\n    \"inbound-ai\",\n    \"ai-receptionist\",\n    \"telephony\",\n    \"numbers\",\n    \"call-memory\",\n    \"cross-call-memory\",\n    \"contacts\",\n    \"memory\"\n  ],\n  \"models\": [\n    \"claude-*\",\n    \"gpt-*\",\n    \"gemini-*\"\n  ],\n  \"minOpenClawVersion\": \"0.8.0\",\n  \"credentials\": {\n    \"AGENTCALL_API_KEY\": {\n      \"description\": \"AgentCall API key (starts with ac_live_). Get one free at https://agentcall.co\",\n      \"required\": true\n    },\n    \"AGENTCALL_BASE_URL\": {\n      \"description\": \"Override the API base URL. Defaults to https://api.agentcall.co. Set for staging environments, on-prem deployments, or custom routing setups.\",\n      \"required\": false\n    },\n    \"AGENTCALL_TIMEOUT_MS\": {\n      \"description\": \"Per-request timeout in milliseconds. Defaults to 30000 (30 seconds). Increase for long-running endpoints like waitForOTP or slow upstream networks.\",\n      \"required\": false\n    }\n  },\n  \"billing\": {\n    \"notice\": \"New accounts receive a one-time 72-hour live trial with one US/Canada local number, 300 managed inbound AI seconds (five minutes) total, and five SMS send attempts to verified destinations. Card verification is required before number allocation; the clock starts when allocation succeeds. There is no monthly reset or automatic paid subscription. Live OTP extraction and outbound calls require Pro. Existing Free accounts retain their assigned monthly allowances. Read the account's offerVersion, trial and limits rather than assuming every Free account has the same offer. Only describe a monthly reset when the account response supplies a non-null resetsAt. Pro is $19.99/month plus number rental and usage: local/mobile numbers $2/month each, toll-free $2.50/month, outbound SMS $0.015/message, standard outbound voice $0.035/min, managed AI voice $0.40/min, BYOK voice $0.10/min plus your AI provider's charges, or Premium Voice $0.59/min. AI calls round up to whole minutes per call. New-account destination/business verification can still apply after upgrading. After trial expiry, the number is held for at least 48 hours before release, with a successful expiry notice before release becomes eligible. A delayed notice extends the hold. Trial expiry and number retention are separate; stored configuration and results remain available. Upgrading during the hold preserves the number.\",\n    \"hasFreeTier\": true,\n    \"paidFeatures\": [\n      \"outbound AI voice ($0.40/min Managed, $0.10/min BYOK)\",\n      \"inbound AI voice after the assigned trial allowance or expiry (Pro plan only; Managed $0.40/min or BYOK $0.10/min, no monthly cap)\",\n      \"Premium Voice on inbound + outbound calls ($0.59/min, opt-in per number, Pro add-on; 12 curated voices, 31 languages plus auto-detect, full caller memory)\",\n      \"opt-in call recording with dashboard playback ($0.01/min, 1-year retention)\",\n      \"unlimited numbers, toll-free, mobile types\"\n    ]\n  },\n  \"webhooks\": {\n    \"notice\": \"This skill can register webhook endpoints to receive real-time events (inbound SMS, OTP codes, call status, recordings, AI call transcripts). Webhooks here are for OUTBOUND event delivery, NOT for routing inbound calls. To make a phone number answer incoming calls, use POST /v1/numbers/:numberId/inbound-config (the AgentCall equivalent of Twilio's inbound voice webhook URL), not webhook registration. Webhooks require an HTTPS URL you control.\",\n    \"events\": [\n      \"sms.inbound\",\n      \"sms.otp\",\n      \"call.inbound\",\n      \"call.ringing\",\n      \"call.status\",\n      \"call.recording\",\n      \"call.transcript\",\n      \"call.report.ready\",\n      \"number.released\"\n    ]\n  },\n  \"changelog\": \"v2.13.1 (2026-09-08): One-time 72-hour card-verified live trial, five minutes total, five verified-destination SMS attempts, no reset or automatic upgrade. Existing monthly Free offers are preserved. Read get_plan first. MCP 0.17.1 aligns hosted, stdio and HTTP instructions. Historical entries below describe past releases, not current offers.\\n\\nv2.13.0 (2026-08-25): Two new tools so an agent can help its human upgrade: get_plan reads the plan, Free limits, and free AI minutes left with a read-aloud summary; upgrade_to_pro returns a Stripe Checkout link (nothing is charged until the human completes it; run only on explicit request). Every plan_limit_* error now carries upgradeUrl and upgradeToolName. Plain outbound calls (initiate_call) are Pro only, callers hear a short message instead of dead air when a Free number is out of trial minutes, and a 3-per-day redial cap per destination returns 429 redial_limit_exceeded. Free SMS allowance corrected to 20/month in the guardrails. 62 tools. v2.12.9 (2026-08-11): Provisioning failures no longer lock you out. The hourly provisioning budget now counts numbers you actually received, so a carrier error or an empty area code costs nothing; previously every failed attempt burned a slot and three bad tries could block provisioning for a full hour without ever handing over a number. A 429 now carries Retry-After with the exact wait. provision_number is also no longer retried automatically after an ambiguous failure, because a replay could buy a second number you get billed for: on a carrier error or timeout, call list_numbers first to see whether the number actually landed, then retry at most once. New error codes documented: provisioning_rate_limit, no_numbers_in_area_code, and carrier_error on provisioning. No new tools; still 60.\\n\\nv2.12.8 (2026-08-11): SMS threads now come with recency built in. get_sms_conversation returns a context object that splits the thread into recentMessages (last 7 days), recentSubstantiveMessages (that list minus plain greetings), and olderMessages, each with its timestamp and age in days, plus a freshness block naming the window and the reference time. Use it for any question about what was discussed recently: the messages array is the last 50 texts, which on a quiet thread can span months, and treating those as recent made agents describe a months-old exchange as something the user had just talked about. When recentSubstantiveMessages is empty the honest answer is that there has been no recent substantive text discussion, not a summary drawn from older texts, durable memory, or call history. Relay mode gets the same classified thread pushed to agentWebhook as an additive smsContext field, so a relay agent needs no second call; endpoints written against the earlier payload keep working. No new tools; still 60.\\n\\nv2.12.7 (2026-08-10): Free-tier and SMS-plan facts corrected. The Free monthly allowance is now 20 outbound SMS (was 10). Relay mode (smsMode 'relay', text your own agent) works on the FREE plan: an agent's replies draw from that same 20, so texting your agent and texting other people share one allowance. Two-way AI SMS (smsMode 'ai') remains Pro only, because AgentCall runs a managed model on every reply. configure_inbound_ai now states the plan for each mode and warns that setting 'ai' on a Free account is accepted but then silently never answers, so agents should check the plan and say so rather than leave the user debugging silence. Unchanged and often confused with it: the lifetime cap of 10 DISTINCT new destination numbers a Free account may ever text, which relay replies never consume because the recipient texted you first. No new tools; still 60.\\n\\nv2.12.6 (2026-08-09): Know whether a text was actually delivered. get_message now returns a real delivery outcome: status moves queued to sent to delivered or failed, with errorCode set when a carrier rejected the message. A 201 from send_sms only means the carrier accepted it, so agents should re-read the message when delivery matters. get_number gains a messaging object carrying the number A2P (10DLC) registration state: registered, pending (still provisioning with carriers, typically about two hours), action_needed (failed, retried automatically every 15 minutes), not_applicable, or unknown. New troubleshooting guidance ties the two together: an errorCode of 40010 means the SENDING number is not registered yet, not that anything is wrong with the recipient, so agents should check messaging.state and tell the user the number is still activating rather than retrying in a loop or switching numbers. No new tools; still 60.\\n\\nv2.12.5 (2026-08-09): Transfer to a human on inbound AI voice. configure_inbound_ai gains an optional transferTo field (E.164): when set, the AI hands the live call to a real person whenever the caller asks for one or the AI cannot help, saying a short handoff line first; whoever answers sees the caller's number. If nobody picks up within about 25 seconds the AI resumes and takes a message, so the caller is never dropped. Works with no webhook or tool setup and coexists with declared tools. AI minutes stop at the handoff; the human portion bills at the standard $0.035/min voice rate. Transfers surface as transferredTo / transferredAt on the call record. Agent guidance: confirm the transfer destination with the user before configuring it, since it is a real phone that rings on live calls. No new tools; still 60. v2.12.4 (2026-08-09): Documents the Free-tier SMS starter allowance. A Free account may now text up to 10 DISTINCT new numbers, lifetime (SMS only, content-screened); re-texting a number already counted consumes nothing further. Corrects the New-Account Outbound Restriction section, which previously stated that no new account may contact an arbitrary number: still true for voice and for Pro accounts under 7 days old, no longer true for Free SMS. Adds the new 403 sms_starter_exhausted code to the Error Codes reference with explicit do-not-retry and do-not-probe guidance, matching the existing handling for destination_not_verified. Clarifies that owned, prior-inbound, and individually verified destinations never consume a starter slot. No new tools; still 60. v2.12.3 (2026-08-08): Premium Voice language parity: the shared premium agent now has all 31 language presets provisioned (verified by config readback plus a live Hungarian premium call), so Premium Voice copy moves from 12 languages to the same 31 as the standard voice. No new tools; still 60. v2.12.2 (2026-08-06): Documents the new-account outbound restriction, which was previously undocumented on every public surface. A new account cannot contact an arbitrary number and gets 403 destination_not_verified; it CAN contact numbers it owns, anyone who contacted it first within 30 days, and numbers verified individually by code. New section explains the two ways to clear it: a business verification (POST /v1/business-verification, Pro, lifts the restriction on submission) or per-number code verification, plus the automatic 7-day expiry. Adds explicit agent guidance not to retry, not to probe other numbers, and to ask the user for their real business details rather than inventing them. Also adds the error code to the Error Codes reference. v2.12.1 (2026-08-05): Documentation accuracy fix on outbound-initiated SMS. Corrected the claim that two-way AI SMS and relay mode are inbound-only. Both modes handle texts that arrive, but a number can also text someone FIRST: send_sms for an immediate message, create_schedule for one-shot or recurring outreach such as appointment reminders, payment follow-ups, and check-ins. Also removed an incorrect precondition on create_schedule that said the number must have smsMode 'ai'; the scheduler gates on plan only, and smsMode 'ai' governs whether the recipient's reply is auto-answered rather than whether the send fires. Consent and spend guardrails on the proactive path are now documented explicitly rather than left implicit: Pro plan only (proactive sends never fire on Free), every send is skipped for a contact who has sent STOP, each fire is billed as one standard outbound text, and a hard cap of 200 proactive sends per number per day bounds a runaway integration. Free-plan figures corrected to 10 outbound SMS per month with received texts not counting. No new tools; still 60. v2.12.0 (2026-06-11): AgentFM callback flow, outbound Premium Voice parity, 62 tools. (1) New request_agentfm_callback tool (tool 60): queues a podcast guest callback to AgentFM, no AgentCall account required, deduplicated per phone per 24 hours. The AI host calls the guest back using outbound premium voice. Mirrors the public POST /v1/agentfm/callback-request endpoint (3 requests/hour/IP rate limit, honeypot, 24h dedup). (2) Outbound Premium Voice: when Premium Voice is enabled on a number (set_premium_voice), POST /v1/calls/ai outbound calls from that number now also use the premium voice at $0.59/min. Previously Premium Voice applied only to inbound calls; both directions are now covered. (3) DB migration: agentfm_callbacks table (RLS enabled, Prisma-only access). (4) Runner script npm run script:agentfm-callbacks (dry-run by default, --apply to dial, --limit N). (5) Public web form at agentcall.co/agentfm. Total tools now 60 (was 59). Ships with @agentcall/mcp-server@0.16.0 and agentcall@0.9.2; hosted MCP at api.agentcall.co/mcp synced in lockstep. Smithery needs manual Publish click. v2.11.0 (2026-06-10): Agent-to-agent calling polish plus four new capabilities, shipped across REST, MCP, and SDK. (1) New synthesize_speech MCP tool and POST /v1/tts endpoint: standalone text to speech in the same 10 voices calls use, mp3 or wav, 4096 chars per request, $0.03 per 1,000 characters, Pro plan; confirm text and approximate cost with the user before large batches. Total tools now 59 (was 58). (2) initiate_ai_call gains metadata (string map, max 24 keys / 2KB, echoed on the call object and every call webhook, copied to the linked agent-to-agent inbound leg) and liveTranscript (each finalized utterance fires the new transcript.partial webhook event during the call: callId, sequence, role, text, timestamp; the post-call call.transcript stays authoritative). (3) Agent-to-agent calls between two numbers on one account now expose peerCallId on both call records and all call webhook payloads. (4) The action bridge is now channel-agnostic in production: the same tools + actionWebhook that power two-way AI SMS let the inbound AI VOICE agent call customer tools mid-call (context.channel \\\"voice\\\", callId populated, fail-soft on errors); the per-call count ships as toolCallCount on the call record and report. Also: canonical call status vocabulary everywhere (initiated, ringing, in-progress, completed, busy, no_answer, failed), the call report is delivered in one canonical shape on both GET /v1/calls/:id/report (report) and the call.report.ready webhook (data.report) with facts[].quote (the raw payload field is deprecated for one release), and call recording on inbound AI numbers is fixed end-to-end (record_start timing, recording storage, and per-minute billing all verified live). Ships with @agentcall/mcp-server@0.15.0 and agentcall@0.9.2; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.10.0 (2026-06-08): Proactive scheduling. A number's AI agent can now text first on a schedule: one-time appointment reminders and recurring digests. Three new MCP tools: create_schedule (numberId, contactPhone, exactly one of fireAt | recurrence, exactly one of template | promptHint, optional payload, timezone, dedupeKey), list_schedules, cancel_schedule. New REST endpoints POST /v1/numbers/:id/schedules, GET /v1/numbers/:id/schedules, DELETE /v1/numbers/:id/schedules/:scheduleId. fireAt is a one-time ISO 8601 instant; recurrence is { frequency 'daily' | 'weekly', hour, minute, dayOfWeek } interpreted in an IANA timezone. template is sent verbatim with {{placeholders}} filled from payload; promptHint lets the agent compose the message from its memory of the contact. dedupeKey makes a re-create return 409 so a calendar sync never duplicates a reminder. A reply to a proactive message threads into the same two-way AI SMS conversation, so a one-word answer is understood in context. Pro plan, the number must have smsMode 'ai', each send is billed as one outbound text. Total tools now 58 (was 55). Ships with @agentcall/mcp-server@0.14.0 and agentcall@0.9.1; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.9.0 (2026-06-06): Two-way AI SMS and relay mode, plus three SMS conversation tools. configure_inbound_ai gains six optional fields: smsMode ('off' | 'ai' | 'relay'), smsSystemPrompt, actionWebhook, tools, agentWebhook, allowedSenders. With smsMode 'ai', inbound texts to the number get an AI reply that follows the prompt, remembers the contact across voice and SMS, and can call customer-declared tools through the action bridge (actionWebhook, HMAC-signed, the same security model as the pre-call context webhook) to return real values instead of guessing; managed-only, Pro, billed as one outbound text per reply. With smsMode 'relay', AgentCall runs no LLM of its own and forwards each inbound text to the customer's own agent at agentWebhook (HMAC-signed); the agent replies on its own schedule, so a user can text their own agent on a real number; allowedSenders (E.164, max 20) restricts which numbers can reach the agent; billed as plain texts, no relay fee. STOP is honored before either mode runs, and both modes handle texts that arrive (to text someone first, use send_sms or create_schedule). Three new MCP tools: list_sms_conversations and get_sms_conversation read the threads; reply_to_sms_conversation (conversationId, body, optional idempotencyKey) sends the relay reply, is opt-out-checked, and is idempotent for 24 hours so a retried agent never double-texts. New REST endpoints GET /v1/sms-conversations, GET /v1/sms-conversations/:id, POST /v1/sms-conversations/:id/reply. New webhook event sms.ai_reply fires on each AI reply. Total tools now 55 (was 52). Ships with @agentcall/mcp-server@0.13.0 and agentcall@0.9.0; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.8.2 (2026-06-05): The configure_inbound_ai notify block gains an optional smsTo field so the owner can also receive a one-line call summary by text in addition to the email summary (US notification numbers, one SMS per call, spam skipped, reply STOP to disable, billed as one outbound SMS at $0.015). No new tools (still 52). Ships with @agentcall/mcp-server@0.12.2 and agentcall@0.8.2; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.8.1 (2026-06-02): Patch release from a post-ship review pass. No tool, schema, or behavior changes (still 52 tools). SDK PremiumVoice.gender tightened to the 'female' | 'male' union, the setPremiumVoice / disablePremiumVoice docstrings now document the 404 number_not_found error, and the npm server startup banner reports the correct tool count. Ships with @agentcall/mcp-server@0.12.1 and agentcall@0.8.1; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.8.0 (2026-06-02): Agents can now enable Premium Voice, not just browse it. Three new MCP tools: set_premium_voice (numberId, voiceId) enables Premium Voice on a number or changes its premium voice; disable_premium_voice (numberId) reverts to the standard voice; list_premium_voices returns the catalog. set_premium_voice is a billable Pro add-on ($0.59/min) so its description instructs the agent to confirm the exact numberId, the chosen voice, and the $0.59/min rate with the user before invoking, and to surface the 403 (not Pro) / 402 (no card) / 409 (inbound AI not configured) errors rather than retry. Requires the number to already have inbound AI configured; never wipes the rest of the inbound config; idempotent. Mirrors the existing dashboard self-serve flow and the new SDK methods client.numbers.setPremiumVoice / disablePremiumVoice and client.calls.premiumVoices. Total tools now 52 (was 49). Ships with @agentcall/mcp-server@0.12.0 and agentcall@0.8.0; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.7.1 (2026-06-02): Documented the public Premium Voice catalog endpoint in the Browse Voices section so agents can list premium voices the same way they list standard ones: GET /v1/calls/premium-voices (no auth) returns { voices: [{ id, name, description, gender, accent, sampleUrl }], pricing }. Each id is the voiceId to enable per number. v2.7.0 (2026-06-02): Premium Voice. Inbound AI receptionists can now answer with Premium Voice (powered by ElevenLabs): a curated library of 12 more natural, brandable voices, all 13 languages, and full caller memory, billed at $0.59/min only on the numbers where it is enabled. The 10 standard voices stay the default at $0.40/min, so the right voice is chosen per number. Premium Voice is enabled self-serve per number from the dashboard (a number's inbound AI settings); preview the catalog at the public GET /v1/calls/premium-voices endpoint (no auth). update_number_voice now describes the Premium Voice tier. As a billable add-on, confirm the user accepts the $0.59/min premium rate on the specific number before enabling. Ships with @agentcall/mcp-server@0.11.0; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.6.0 (2026-05-25): Two new optional input fields on initiate_ai_call (POST /v1/calls/ai). useSavedAgent: boolean hydrates systemPrompt, voice, language, firstMessage, maxDurationSecs, and record from the saved outbound agent on the from-number (set via set_outbound_defaults) so CSV runners don't re-spread the prompt on every row; per-call overrides win, so firstMessage can stay personalized per recipient while inheriting the saved persona. Returns code no_saved_agent if the from-number has no saved outbound agent. idempotencyKey: string (1 to 200 chars) scoped per phone number; a duplicate request with the same from + idempotencyKey pair replays the original response (with header X-AgentCall-Idempotency-Replayed: true) and does not place a second carrier call. Uniqueness is enforced at the database layer so concurrent retries are race-safe. The canonical CSV-runner row is {from, to, useSavedAgent: true, idempotencyKey: 'batch-id:row-id', firstMessage: '...'}. Tool count remains 49. Ships with @agentcall/mcp-server@0.10.0 and agentcall@0.7.0; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.5.0 (2026-05-25): Added set_outbound_defaults, get_outbound_defaults, clear_outbound_defaults tools. Save a reusable outbound AI agent (systemPrompt, voice, language, firstMessage, maxDurationSecs, record, optional templateId) on a phone number so the dashboard Place AI call dialog and any MCP client can hydrate from it instead of retyping for every outbound call from the same number. Pro-only. Independent of the inbound AI receptionist on the same number. The `outbound` field is now also returned on every list_numbers and get_number response alongside the existing `inbound` field. Total tools now 49 (was 46). Ships with @agentcall/mcp-server@0.9.0; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.4.1 (2026-05-26): New follow-up-on-call MCP prompt. Walks the agent through calling back the person from a previous inbound call: load the original call detail, load the structured report (intent, summary, commitments, tasks, unresolved questions, spam flag, caller name), confirm with the user, then place an outbound AI call with a stitched prompt grounded in what the caller actually said. Stops on spam-flagged calls. Optional `reason` parameter lets the user pin a specific follow-up purpose (e.g. 'tell them their estimate is ready') instead of letting the AI infer from open items. Mirrors the new 'Follow up with AI' button on the dashboard call detail page so agents on Claude Desktop, Cursor, and OpenClaw have parity with the dashboard surface. Total prompts now 5 (was 4). Ships with @agentcall/mcp-server@0.8.1; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.4.0 (2026-05-25): Multilingual AI voice on inbound and outbound. New optional `language` field on configure_inbound_ai and initiate_ai_call accepts 'auto' (default, matches the caller naturally) plus 12 ISO-639-1 codes: en, es, fr, de, it, pt, nl, ja, ko, zh, hi, ar. When a specific code is set, the runtime prepends a 'respond exclusively in {language}' directive to the system prompt at session-build time and pins the speech-to-text language hint for cleaner transcription. The customer's systemPrompt stays unchanged so swapping language never wipes the prompt. PATCH /v1/numbers/:id now accepts language alongside label and voice for partial updates. New MCP tool update_number_language mirrors update_number_voice for language-only edits. Three new outbound prompt templates ('outbound-appointment-booker', 'outbound-info-request', 'outbound-callback-confirmation') with placeholders for booking-on-behalf-of use cases. The /v1/calls/prompt-templates endpoint now accepts an optional ?direction=inbound or ?direction=outbound query filter. The firstMessage stays verbatim regardless of language setting, so callers should translate the greeting themselves if non-English. Total tools now 45 (was 44). Ships with @agentcall/mcp-server@0.8.0 and agentcall@0.5.0; hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.3.1 (2026-05-19): Schema-drift fix on 5 MCP tool output shapes. Customers using Claude Desktop and Cursor occasionally saw validation errors on calls that completed successfully; this release aligns the declared shapes with the live API responses. webhook rotate now returns the full Webhook row instead of just secret; webhook create includes isActive in the response; get_call_report candidates expose reportId, contactId, resolvedAt, resolvedBy; get_call_transcript returns 202 for in-progress calls so it doesn't collide with the documented 200 transcript shape; PATCH /v1/memory/:id projects the updated row to the declared memory shape. Plus drops 4 top-level BYOK status fields from inboundAiConfigOutputSchema (voiceMode, hasByokKey, byokOpenaiApiKeyPreview, byokConfiguredAt). These have always lived inside `config` and were incorrectly declared at the top level. SDK consumers now read these as result.config.hasByokKey etc. Ships with @agentcall/mcp-server@0.7.1 and agentcall@0.4.1. v2.3.0 (2026-05-18): added set_byok_openai_key + disable_byok tools. configure_inbound_ai response now exposes voiceMode + hasByokKey + byokOpenaiApiKeyPreview. Inbound AI voice is per-number configurable in two billing modes: Managed ($0.40/min, AgentCall holds the AI provider key) or BYOK ($0.10/min, customer provides their own AI provider key). Memory is included on both modes and on every plan. Total tools now 44. Ships with @agentcall/mcp-server@0.7.0 and the hosted MCP at api.agentcall.co/mcp synced in lockstep. v2.2.3 (2026-05-16): Customer-controlled cross-call memory toggle. New PATCH /v1/account endpoint accepting { memoryEnabled: boolean } so customers can enable or disable Auditable Call Memory themselves from the dashboard or programmatically. GET /v1/account now returns memoryEnabled. SDK adds client.account.get() and client.account.setMemoryEnabled(true|false). New MCP tool set_memory_enabled (43 tools total, was 42). Available on Free + Pro; Free volume is naturally capped by the 5-min/month inbound AI trial so extraction cost stays trivial. Toggling off does NOT delete existing memory; use purge_contact for that. Ships with @agentcall/mcp-server@0.6.3 and agentcall@0.3.1. v2.2.2 (2026-05-16): Smithery quality score work. Added two optional config entries to credentials (AGENTCALL_BASE_URL, AGENTCALL_TIMEOUT_MS) wired through to the AgentCall SDK so MCP-marketplace listings show a richer configuration UX. Swept 9 input-parameter descriptions that were missing on the new memory tools (update_contact, update_memory, list_call_reports, list_briefs) so every tool's input fields are fully documented. No tool behavior change. Ships with @agentcall/mcp-server@0.6.2 and the hosted MCP at api.agentcall.co/mcp synced. v2.2.1 (2026-05-16): Tightened the outputSchema on two memory tools (get_call_report.payload and get_memory_timeline.events[].before/after) from z.unknown() to fully-typed Zod object shapes mirroring the actual API response. Field-level descriptions added on the rest of the CallReport surface. No behavior change; tool callers see the same JSON. Ships with @agentcall/mcp-server@0.6.1 and the hosted MCP at api.agentcall.co/mcp synced in the same release. v2.2.0 (2026-05-16): Auditable Call Memory feature. Every completed AI call auto-extracts into a structured CallReport plus MemoryCandidate rows: facts, preferences, decisions, commitments, tasks, risks, the nextCallContext paragraph, an ownerBrief block when the call needs attention. High-confidence candidates auto-promote into Memory (Current Truth) via a per-agent policy; lower-confidence and decision/task candidates stay proposed for manual review. The Bob-vs-Robert handler resolves same-slot contradictions: corroborate on same text, supersede on >0.15 confidence delta, otherwise keep existing and reject the new candidate. Every change writes a MemoryEvent so the audit trail is queryable. 20 new endpoints: GET /v1/contacts, GET /v1/contacts/:id, GET /v1/contacts/by-phone/:phone, GET /v1/contacts/:id/next-call-context (the killer tool: render the Memory block the AI would receive on the next call), GET /v1/memory/current, GET /v1/memory/:id, GET /v1/memory/:id/timeline, GET /v1/memory/candidates, GET /v1/reports, GET /v1/calls/:id/report, GET /v1/briefs, PATCH /v1/contacts/:id, DELETE /v1/contacts/:id (right-to-forget; cascades Memory + Candidate + Brief; redacts CallReport.payload), PATCH /v1/memory/:id, DELETE /v1/memory/:id, POST /v1/memory/candidates/:id/approve, POST /v1/memory/candidates/:id/reject, POST /v1/briefs/:id/ack, POST /v1/briefs/:id/resolve. 10 new MCP tools mirror the read surface (list_contacts, get_contact, get_contact_by_phone, get_next_call_context, get_current_memory, get_memory, get_memory_timeline, list_memory_candidates, list_call_reports, get_call_report); 9 new MCP tools mirror the write surface (update_contact, purge_contact, update_memory, delete_memory, approve_memory_candidate, reject_memory_candidate, list_briefs, acknowledge_brief, resolve_brief). purge_contact and delete_memory carry destructiveHint=true so MCP clients prompt for confirmation. Hosted MCP at api.agentcall.co/mcp and the npm @agentcall/mcp-server bumped in lockstep to 0.6.0 with 42 tools total. New webhook event call.report.ready fires after the extractor completes, ~5 to 30 seconds after the call ends, alongside the existing call.transcript event. Inbound AI configure_inbound_ai now accepts contextSource (none / agentcall_memory / webhook / merge) to route the pre-call context block. SDK agentcall@0.3.0 adds client.contacts.*, client.memory.*, client.reports.*, client.briefs.* plus client.calls.getReport. Feature is opt-in per agent via Agent.memoryEnabled (default false), so existing customers see zero behavior change until the flag is flipped. v2.1.19 (2026-05-14): Fixed an outputSchema drift on list_calls. The /v1/calls list endpoint deliberately omits `recordingUrl` and substitutes a cheap `hasRecording` boolean per row (avoids minting a signed URL per row, which would burn rate limit on every page fetch). The MCP list_calls outputSchema used the detail-call shape which required `recordingUrl`, so list_calls responses failed strict validation when consumers like Hermes ran them. Now there are two shapes: the detail shape (used by get_call, initiate_call, initiate_ai_call) still has `recordingUrl`; the list shape (used by list_calls) has `hasRecording: boolean` instead. Consumers fetch the actual URL via get_call or `GET /v1/calls/:id/recording`. Ships with @agentcall/mcp-server@0.4.19 and the hosted MCP at api.agentcall.co/mcp updated in the same release. v2.1.18 (2026-05-13): Post-call transcript webhook is documented end-to-end in the Webhooks section. Subscribe to the `call.transcript` event to receive the full transcript and LLM-extracted summary (callerName, intent, urgency, callbackBy, spam) after every inbound AI call ends. Payload is HMAC-SHA256 signed in the `X-AgentCall-Signature` header. Receiving endpoints verify the signature, dedup on `callId`, and acknowledge with 2xx as soon as the payload is persisted; AgentCall retries with exponential backoff on non-2xx. Three integration patterns are documented (store, forward, queue-for-local-agent). Reference public bridge github.com/Kintupercy/agentcall-hermes-bridge v0.2.0 now exposes `POST /agentcall/transcript` (HMAC-verified queue append, bounded at 100) and `POST /hermes/pull-transcripts` (read-and-clear) for agent platforms that run locally and can't accept inbound HTTPS. Full walkthrough at https://agentcall.co/docs/post-call-webhook. v2.1.17 (2026-05-13): configure_inbound_ai now officially accepts an optional `contextWebhook` block alongside the existing fields. When set, AgentCall POSTs to your HTTPS URL on every inbound call connect (HMAC-signed); the response's contextBlock string is merged onto the systemPrompt before the AI answers. Use this to inject a live brief, current priorities, or recent emails so the AI speaks \n\nArchive v2.13.0: 5 files, 64140 bytes\n\nFiles: claw.json (45615b), instructions.md (59655b), skill-card.md (3281b), SKILL.md (59655b), _meta.json (129b)\n\nArchive v2.12.9: 5 files, 62013 bytes\n\nFiles: claw.json (45035b), instructions.md (57253b), skill-card.md (3108b), SKILL.md (57253b), _meta.json (129b)\n\nArchive v2.12.8: 5 files, 60983 bytes\n\nFiles: claw.json (44233b), instructions.md (56333b), skill-card.md (3179b), SKILL.md (56333b), _meta.json (129b)\n\nArchive v2.12.7: 5 files, 59639 bytes\n\nFiles: claw.json (43205b), instructions.md (55110b), skill-card.md (3288b), SKILL.md (55110b), _meta.json (129b)\n\nArchive v2.12.6: 5 files, 59532 bytes\n\nFiles: claw.json (42335b), instructions.md (55110b), skill-card.md (3786b), SKILL.md (55110b), _meta.json (129b)\n\nArchive v2.12.5: 5 files, 57852 bytes\n\nFiles: claw.json (41320b), instructions.md (53858b), skill-card.md (3014b), SKILL.md (53858b), _meta.json (129b)\n\nArchive v2.12.4: 5 files, 57046 bytes\n\nFiles: claw.json (42261b), instructions.md (52957b), skill-card.md (2833b), SKILL.md (52957b), _meta.json (129b)\n\nArchive v2.12.3: 5 files, 56208 bytes\n\nFiles: claw.json (41493b), instructions.md (51886b), skill-card.md (3592b), SKILL.md (51886b), _meta.json (129b)\n\nArchive v2.12.2: 5 files, 56059 bytes\n\nFiles: claw.json (41282b), instructions.md (52142b), skill-card.md (3032b), SKILL.md (52142b), _meta.json (129b)","readmeExcerpt":"Skill: AgentCall Owner: kintupercy Summary: Give your agent real phone numbers for SMS, OTP verification, and voice calls via the AgentCall API. Tags: ai-voice:2.0.0, api:2.0.0, calls:2.0.0, latest:2.13.1, otp:2.0.0, phone:2.0.0, sms:2.0.0, verification:2.0.0, voice:2.0.0 Version history: v2.13.1 | 2026-09-08T17:59:43.811Z | user Align all agents with the card-verified 72-hour live trial, five inbound AI minutes tota","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"POST /v1/numbers/provision\nBody: { \"type\": \"local\", \"country\": \"US\", \"label\": \"my-agent\" }\nTypes: 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).\nResponse: { \"id\": \"num_xxx\", \"number\": \"+12125551234\", \"type\": \"local\", ... }"},{"language":"text","snippet":"GET /v1/numbers\nQuery: ?limit=20&country=US&type=local"},{"language":"text","snippet":"GET /v1/numbers/:id"},{"language":"text","snippet":"DELETE /v1/numbers/:id"},{"language":"text","snippet":"PATCH /v1/numbers/:id\nBody: { \"label\": \"Hermes assistant\" }                  // rename only\nBody: { \"voice\": \"marin\" }                             // voice only (requires inbound AI already configured)\nBody: { \"language\": \"es\" }                             // language only (requires inbound AI already configured)\nBody: { \"label\": \"Hermes\", \"voice\": \"coral\", \"language\": \"fr\" }  // any combination\nVoices: alloy, ash, ballad, cedar, coral, echo, marin, sage, shimmer, verse\nLanguages: auto, en, es, fr, de, it, pt, nl, ja, ko, zh, hi, ar, ru, id, tr, pl, uk, vi, ta, ms, ro, el, cs, sv, hu, da, fi, no, sk, hr, bg  (31 languages plus auto)\nResponse: full number object including updated `inbound` block."},{"language":"text","snippet":"POST /v1/numbers/:numberId/inbound-config\nBody: {\n  \"mode\": \"ai\",\n  \"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.\",\n  \"voice\": \"shimmer\",\n  \"language\": \"auto\",\n  \"firstMessage\": \"Hi, thanks for calling Acme Plumbing. How can I help?\",\n  \"maxDurationSecs\": 300,\n  \"transferTo\": \"+14155551234\",\n  \"notify\": {\n    \"emailTo\": \"owner@acmeplumbing.com\",\n    \"smsTo\": \"+14155551234\",\n    \"businessName\": \"Acme Plumbing\",\n    \"agencyName\": \"Acme Plumbing\"\n  }\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"# AgentCall: Phone Numbers for AI Agents\n\n<!-- BEGIN GENERATED OFFER POLICY -->\n## Current offer and agent behavior\n\nNew accounts receive a one-time 72-hour live trial with one US/Canada local number, 300 managed inbound AI seconds (five minutes) total, and five SMS send attempts to verified destinations. Card verification is required before number allocation; the clock starts when allocation succeeds. There is no monthly reset or automatic paid subscription. Live OTP extraction and outbound calls require Pro.\n\nExisting Free accounts retain their assigned monthly allowances. Read the account's offerVersion, trial and limits rather than assuming every Free account has the same offer. Only describe a monthly reset when the account response supplies a non-null resetsAt.\n\nPro is $19.99/month plus number rental and usage: local/mobile numbers $2/month each, toll-free $2.50/month, outbound SMS $0.015/message, standard outbound voice $0.035/min, managed AI voice $0.40/min, BYOK voice $0.10/min plus your AI provider's charges, or Premium Voice $0.59/min. AI calls round up to whole minutes per call. New-account destination/business verification can still apply after upgrading.\n\nAfter trial expiry, the number is held for at least 48 hours before release, with a successful expiry notice before release becomes eligible. A delayed notice extends the hold. Trial expiry and number retention are separate; stored configuration and results remain available. Upgrading during the hold preserves the number.\n\nBefore quoting allowances or taking a paid action, call get_plan (or GET /v1/account) and use the returned offerVersion, trial, limits, billingStatus and summary. New live_trial_72h_v1 accounts have a one-time 72-hour trial starting at successful number allocation, 300 managed inbound AI seconds total and five verified-destination SMS attempts; card verification is required first. No monthly reset, automatic upgrade or Free overage. Existing free_monthly_v1 accounts retain assigned monthly allowances. Live OTP extraction, outbound calls, BYOK and Premium Voice require Pro for new trial accounts. Explain payment_method_required, payment_recovery_required, trial expiry and quota errors; stop retrying them. Share the returned setup/upgrade link when the user wants to proceed, let the human complete card/payment steps, then reread get_plan before retrying. Do not assume saving a card upgrades the account, or promise a released number can be recovered. Pro is $19.99/month plus number rental and usage. Do not auto-run upgrade_to_pro just because another tool failed. Honor the user's authorization for any real-world action. Read https://api.agentcall.co/llms.txt for the current reference.\n<!-- END GENERATED OFFER POLICY -->\n\nYou 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.\n\n## Authentication\n\nAll authenticated requests require: `Authorization: "},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7d072cygf11v6hx13rfnmmcx81nwys\",\n  \"slug\": \"agentcall\",\n  \"version\": \"2.13.1\",\n  \"publishedAt\": 1788890383811\n}"},{"path":"instructions.md","content":"# AgentCall: Phone Numbers for AI Agents\n\n<!-- BEGIN GENERATED OFFER POLICY -->\n## Current offer and agent behavior\n\nNew accounts receive a one-time 72-hour live trial with one US/Canada local number, 300 managed inbound AI seconds (five minutes) total, and five SMS send attempts to verified destinations. Card verification is required before number allocation; the clock starts when allocation succeeds. There is no monthly reset or automatic paid subscription. Live OTP extraction and outbound calls require Pro.\n\nExisting Free accounts retain their assigned monthly allowances. Read the account's offerVersion, trial and limits rather than assuming every Free account has the same offer. Only describe a monthly reset when the account response supplies a non-null resetsAt.\n\nPro is $19.99/month plus number rental and usage: local/mobile numbers $2/month each, toll-free $2.50/month, outbound SMS $0.015/message, standard outbound voice $0.035/min, managed AI voice $0.40/min, BYOK voice $0.10/min plus your AI provider's charges, or Premium Voice $0.59/min. AI calls round up to whole minutes per call. New-account destination/business verification can still apply after upgrading.\n\nAfter trial expiry, the number is held for at least 48 hours before release, with a successful expiry notice before release becomes eligible. A delayed notice extends the hold. Trial expiry and number retention are separate; stored configuration and results remain available. Upgrading during the hold preserves the number.\n\nBefore quoting allowances or taking a paid action, call get_plan (or GET /v1/account) and use the returned offerVersion, trial, limits, billingStatus and summary. New live_trial_72h_v1 accounts have a one-time 72-hour trial starting at successful number allocation, 300 managed inbound AI seconds total and five verified-destination SMS attempts; card verification is required first. No monthly reset, automatic upgrade or Free overage. Existing free_monthly_v1 accounts retain assigned monthly allowances. Live OTP extraction, outbound calls, BYOK and Premium Voice require Pro for new trial accounts. Explain payment_method_required, payment_recovery_required, trial expiry and quota errors; stop retrying them. Share the returned setup/upgrade link when the user wants to proceed, let the human complete card/payment steps, then reread get_plan before retrying. Do not assume saving a card upgrades the account, or promise a released number can be recovered. Pro is $19.99/month plus number rental and usage. Do not auto-run upgrade_to_pro just because another tool failed. Honor the user's authorization for any real-world action. Read https://api.agentcall.co/llms.txt for the current reference.\n<!-- END GENERATED OFFER POLICY -->\n\nYou 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.\n\n## Authentication\n\nAll authenticated requests require: `Authorization: "},{"path":"skill-card.md","content":"## Description:\n\nAgentCall gives agents access to real phone numbers for SMS, authorized OTP retrieval, voice calls, AI receptionists, proactive messages, and call memory through the AgentCall API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[kintupercy](https://clawhub.ai/user/kintupercy)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use AgentCall to let an agent provision phone numbers, send and receive SMS, answer or place calls with AI voice, retrieve authorized OTPs, schedule proactive messages, and maintain call memory. It is suited for authorized business communication and agent-to-phone workflows that require user confirmation for real-world actions.\n\n### Deployment Geography for Use:\n\nGlobal; telephony features depend on AgentCall's documented carrier and destination support.\n\n## Known Risks and Mitigations:\n\nRisk: The skill can make real-world calls, send SMS messages, and trigger billing.\n\nMitigation: Review costs and require explicit user confirmation before outbound calls, texts, number provisioning, premium voice, recording, schedules, or other paid actions.\n\nRisk: OTP retrieval can be misused against services the user does not control.\n\nMitigation: Use OTP workflows only for systems the user owns or is authorized to test.\n\nRisk: Call recording and call memory can retain sensitive communications.\n\nMitigation: Confirm recording consent, monitor retained call memory, and disable or purge configurations when no longer needed.\n\nRisk: Persistent AI receptionists, schedules, and webhooks can continue acting after initial setup.\n\nMitigation: Monitor active configurations and disable receptionists, schedules, webhooks, or memory when the user's task is complete.\n\n## Reference(s):\n\n- [AgentCall ClawHub Skill Page](https://clawhub.ai/kintupercy/skills/agentcall)\n- [AgentCall API Reference](https://api.agentcall.co/llms.txt)\n- [AgentCall Billing](https://agentcall.co/billing)\n- [AgentCall Voice Prompt Guide](https://agentcall.co/docs/voice-prompts)\n- [AgentCall Pre-Call Context Webhook Walkthrough](https://agentcall.co/docs/hermes)\n- [AgentCall Post-Call Webhook Walkthrough](https://agentcall.co/docs/post-call-webhook)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with API paths, JSON examples, shell commands, and configuration instructions]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires AGENTCALL_API_KEY for authenticated AgentCall API actions; some actions can bill money, contact real people, create persistent configurations, or retain call data and must be confirmed with the user.]\n\n## Skill Version(s):\n\n2.13.1 (source: evidence.release.version and artifact/claw.json version; changelog dated 2026-09-08)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before rely"},{"path":"claw.json","content":"{\n  \"name\": \"agentcall\",\n  \"version\": \"2.13.1\",\n  \"summary\": \"Phone numbers, SMS, two-way AI SMS plus relay mode (text your own agent on a real number), proactive scheduling (the agent texts first: appointment reminders and recurring digests), AI voice agents (Managed $0.40/min, BYOK $0.10/min, or Premium Voice $0.59/min on inbound + outbound) with 31 languages plus auto-detect, and Auditable Call Memory (cross-call contacts, structured call reports, the next-call context block) for AI agents. 62 tools. VoIP-routed via licensed US carriers.\",\n  \"description\": \"Phone numbers, SMS, voice calls, inbound + outbound AI voice with multilingual support, AND Auditable Call Memory for AI agents. Provision US/CA numbers, send/receive texts, extract OTP codes for apps you control, configure phone numbers to be answered by an AI voice agent (with plain-English email summaries and optional MP3 recordings after every call), or place autonomous AI-powered outbound calls. Inbound texts can be answered too: set smsMode to 'ai' so AgentCall's AI replies and pulls real quotes by calling tools you host through the action bridge, or set smsMode to 'relay' so AgentCall runs no AI and forwards each text to your own agent and sends its reply back, letting you text your own agent on a real number. AI voice supports 31 languages plus auto-detect on both directions: 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. Default is auto (matches the caller naturally); pin a specific language to keep the AI in that language even if the other party speaks another, useful for businesses serving a specific language community or for outbound errands like booking a Spanish doctor's appointment on behalf of someone. Inbound AI voice ships in two billing modes per number: Managed at $0.40/min (AgentCall holds the AI provider key, simplest setup) or BYOK at $0.10/min (customer provides their own AI provider key, AgentCall bills only the platform overhead). Premium Voice is an opt-in Pro add-on that answers inbound calls with a more natural, brandable voice from a curated library, in the same 31 languages as the standard voice plus auto-detect, with full caller memory, at $0.59/min only on numbers where it is enabled. Enable it per number from the dashboard or programmatically via the set_premium_voice MCP tool (disable_premium_voice to revert, list_premium_voices to browse). Memory is included on every plan and every voice mode. Every completed AI call auto-extracts into structured, source-backed memory: contacts, facts, preferences, commitments, tasks, briefs. Cross-call memory means a returning caller is recognized and the AI starts with what was said last time. Ask AgentCall what is known about any phone number before placing a call via get_nex"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2517,"uniquenessScore":37,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T05:27:53.685Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T05:27:53.685Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T12:45:30.073Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}