agentcall
Programmable phone numbers for AI agents.
От сообщества: Добавлен пользователем или импортирован; проверьте владельца перед подключениемРаботаетНужен API-ключГлобальныйБесплатноМожет изменять данные
Что умеет
- Provision Number: Provision a new phone number for your AI agent. Returns the number details including the phone number string and ID.
- List Numbers: List all phone numbers provisioned for this agent. Returns an array of number objects with IDs, phone strings, types, and status.
- Get Number: Get details of a specific phone number by its ID. Returns the full number object including status and monthly rate.
Какие данные видит
Нужен ли аккаунт
Нужен API-ключ из настроек сервиса
Programmable phone numbers for AI agents. Provision numbers, send/receive SMS, extract OTP codes, configure AI voice receptionists for inbound calls, and place autonomous outbound AI voice calls.
Список инструментов сервера (60)
Технические названия из tools/list. Нужны только разработчикам.
| provision_number | Provision a new phone number for your AI agent. Returns the number details including the phone number string and ID. |
| list_numbers | List all phone numbers provisioned for this agent. Returns an array of number objects with IDs, phone strings, types, and status. |
| get_number | Get details of a specific phone number by its ID. Returns the full number object including status and monthly rate. |
| configure_inbound_ai | Set up an AI voice agent to autonomously answer incoming calls to a phone number. This is the AgentCall equivalent of an inbound voice webhook URL: instead of pointing the number at a webhook you host, you give AgentCall a system prompt and AgentCall handles the call with an AI voice agent. Use this (NOT 'create_webhook') when you want a phone number to answer calls. Set the system prompt, voice, and optional first message; when someone calls the number, the AI picks up and follows the prompt. Pass `notify.emailTo` to also receive a plain-English summary of every call (caller, intent, urgency, callback time) so small-business owners do not need to read transcripts. 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. Available on US and Canada numbers. Before writing systemPrompt from scratch, fetch GET https://api.agentcall.co/v1/calls/prompt-templates (no auth) for pre-built templates: receptionist, lead qualifier, appointment booker, customer support, call screener. Preview voices via GET https://api.agentcall.co/v1/calls/voices. IMPORTANT (persistent config: confirm before enabling, monitor after): this is NOT a one-shot tool call. Once configured, the number autonomously answers every incoming call from then on, accumulates per-minute charges (at $0.40/min on Pro under the account's paid plan), and keeps doing so until disable_inbound_ai is called. Before invoking, get the user's explicit confirmation on: (1) exact E.164 number to configure (read it back), (2) systemPrompt content (read back at least the WHAT WE DO and PRICING sections so the user can correct invented facts before any caller hears them), (3) record setting (default false; recording adds $0.01/min and 1-year retention), (4) notify.emailTo (confirm the address is theirs and that they want every call summarized), (5) maxDurationSecs (use the smallest value that fits the use case so a stuck call cannot run for an hour), (6) budget expectations (new trial: five inbound AI minutes total over 72 hours, then stop, or Pro $0.40/min with no monthly cap). After enabling, periodically check get_usage so the user sees consumption, and proactively offer to call disable_inbound_ai when their stated goal is met (testing finished, campaign over, business closed for the season). On reports of unexpected charges or unexpected calls, disable_inbound_ai first then debug. Both managed and BYOK modes include caller Memory. Use set_byok_openai_key to enable BYOK on a number. |
| disable_inbound_ai | Disable inbound AI on a phone number. Future incoming calls will be hung up by the carrier until re-configured. Does not release the number — billing for the number itself continues. |
| update_number_label | Rename a phone number by updating its label. The label is a human-readable name shown in the dashboard and number listings (e.g. 'Hermes assistant', 'Ace Plumbing line'). Pass null to clear the label. Does not change the phone number itself — only the label. |
| update_number_voice | Change the voice an inbound AI receptionist uses without touching anything else about its configuration. Use this when the user says something like 'change Laura's voice to coral' or 'switch the receptionist over to marin'. Do not re-run configure_inbound_ai for a voice-only change. configure_inbound_ai replaces the full inbound config and would wipe the system prompt, first message, context webhook, recording flag, and email-notify block. Voice options (alphabetical): alloy: neutral, balanced. Best for generic notifications, IVR-style flows. ash: warm, conversational. Best for customer service. ballad: expressive, melodic. Best for engaging, narrative conversations. cedar (new): warm, grounded. Best for chief of staff, advisory, trust-building calls. coral: clear, professional. Best for B2B calls, sales. echo: resonant, deep. Best for formal inquiries, executive comms. marin (new): soft, natural. Best for receptionist, support, conversational small business. sage: calm, authoritative. Best for healthcare, finance, advisory. shimmer (default): bright, energetic. Best for sales, outreach, high-energy brands. verse: smooth, articulate. Best for premium, executive communication. Preview audio at GET https://api.agentcall.co/v1/calls/voices. Requires the number to already have inbound AI configured; if not, call configure_inbound_ai first. Confirm the voice name with the user before invoking. They typically remember a vibe ('warmer', 'softer', 'less robotic'), not the catalog name. These are the 10 standard voices. AgentCall also offers Premium Voice: a curated library of even more natural, brandable voices for inbound AI receptionists, a Pro add-on at $0.59/min. Enable it with the set_premium_voice tool (or from the dashboard: Numbers, then a number's inbound AI settings, then the Premium Voice section); browse the catalog with list_premium_voices or GET https://api.agentcall.co/v1/calls/premium-voices. |
| update_number_language | Change the language an inbound AI receptionist speaks without touching anything else about its configuration. Use this when the user says something like 'switch the receptionist to Spanish' or 'make Laura answer in French'. Do not re-run configure_inbound_ai for a language-only change. configure_inbound_ai replaces the full inbound config and would wipe the system prompt, first message, voice, context webhook, recording flag, and email-notify block. Language options: auto: match the caller's language naturally (default — same as before this feature shipped). 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 When a specific code is set, the AI responds ONLY in that language even if the caller speaks another. Useful for businesses serving a specific language community. The language directive is added at call time so the customer's system prompt stays unchanged. Requires the number to already have inbound AI configured; if not, call configure_inbound_ai first. |
| set_byok_openai_key | Save a customer-provided OpenAI API key for a phone number and switch its voice billing to BYOK mode. AgentCall validates the key against the voice API before saving (atomic: only commits if the test passes). Once saved, every inbound and outbound AI call on this number uses the customer's key. AgentCall bills $0.10/min on Pro (down from $0.40/min managed) and the customer pays OpenAI directly for the underlying voice usage. The key is encrypted at rest (AES-256-GCM) and is never returned in any response. Only a redacted preview (e.g. 'sk-...AbCd') is exposed for confirmation. Pro plan only ($19.99/mo plus usage); a 403 plan_limit_byok means offer upgrade_to_pro only if the user requests an upgrade. IMPORTANT (sensitive credential: confirm before saving): before invoking, get the user's explicit confirmation on: (1) the exact numberId being switched to BYOK, (2) that the key is theirs and they accept paying OpenAI directly for voice tokens, (3) that they have enough OpenAI credit to cover expected call volume (an exhausted OpenAI account will silently fail calls on that number until the customer refills or disables BYOK). Treat the key as a credential: do not echo it back in your reply, do not log it, and prefer asking the user to paste it into the dashboard if your client transcript could be archived. Use disable_byok to revert to managed mode. |
| disable_byok | Clear the saved BYOK key on a number and flip voice billing back to managed mode. After this, inbound and outbound AI calls on the number bill at $0.40/min on Pro and AgentCall pays the underlying voice provider. Preserves every other inbound config field (systemPrompt, voice, firstMessage, notify, contextWebhook, record) so disabling BYOK does not wipe the number's setup. |
| list_premium_voices | List the Premium Voice library: a curated set of higher-quality, brandable voices a Pro customer can use for an inbound AI receptionist. Each entry has a neutral display name, a one-line description, gender, accent, and a sample MP3 URL. Enable one on a number with set_premium_voice (the id from this list is what you pass). Premium Voice is a Pro add-on that bills at $0.59/min on top of the plan. No authentication or plan gate on listing — use it to let the user pick a voice before enabling. |
| set_premium_voice | Enable Premium Voice on a phone number, or change which premium voice it uses. Premium Voice answers inbound calls with a higher-quality, more natural and brandable voice than the standard voices. The same call both enables premium (first time) and swaps the voice (subsequent calls), so it is idempotent and safe to retry. Pick a voiceId from list_premium_voices (or GET https://api.agentcall.co/v1/calls/premium-voices). The number must already have inbound AI configured (run configure_inbound_ai first); enabling premium never wipes the system prompt, first message, language, or any other inbound config. IMPORTANT (billable Pro add-on: confirm the rate before enabling). Premium Voice bills at $0.59/min on top of the Pro plan, and once enabled the number autonomously answers every incoming call at that rate until disable_premium_voice is called. Before invoking, get the user's explicit confirmation on: (1) the exact numberId to change (read it back), (2) the specific voice they want (read back the voice name from list_premium_voices), and (3) that they accept the $0.59/min premium rate. Requires the Pro plan AND a payment method on file AND inbound AI already configured; if any is missing the tool returns a clear error (403 plan_limit_premium_voice with an upgrade link, 402 payment_method_required with a setup link, or 409 inbound_ai_required) — surface that message to the user and stop, do not loop or retry. Use disable_premium_voice to revert to the standard voice. |
| disable_premium_voice | Disable Premium Voice on a phone number, reverting it to the standard inbound AI voice. After this, inbound calls are answered by the standard voice and the $0.59/min premium add-on stops accruing. Preserves every other inbound config field (systemPrompt, voice, firstMessage, language, notify, contextWebhook, record) so disabling premium does not wipe the number's setup. Idempotent: disabling an already-standard number is a no-op. Pro plan only ($19.99/mo plus usage). |
| set_outbound_defaults | Save a reusable outbound AI agent persona on this number (system prompt + voice + language + first message + duration + recording defaults). The dashboard Place AI call dialog hydrates from this blob, so the customer doesn't retype the prompt for every outbound call from the same number. Use this when the user wants the AI to keep the same persona across many outbound calls from a given number (e.g. an appointment-booker that calls a list of doctors). Each phone number can have ONE saved agent; saving overwrites. Independent of the inbound AI receptionist on the same number. Saving here never touches inbound config, and configure_inbound_ai never touches this. Both can be set on the same number (inbound answers incoming calls; the saved outbound agent pre-fills the dashboard for outbound calls). Pro plan only ($19.99/mo plus usage) because outbound AI itself is Pro; a 403 plan_limit_voice_ai means offer upgrade_to_pro only if the user requests an upgrade. Voice options (alphabetical): alloy, ash, ballad, cedar, coral, echo, marin, sage, shimmer, verse. Preview at https://api.agentcall.co/v1/calls/voices. Language: 'auto' (matches recipient) or an ISO-639-1 code (en/es/fr/de/it/pt/nl/ja/ko/zh/hi/ar) that pins the AI to that language. templateId is a short friendly label (e.g. 'appointment-booker') shown on the dashboard numbers row as the agent badge. |
| get_outbound_defaults | Read the saved outbound AI agent on this number. Returns the systemPrompt + voice + language + firstMessage + maxDurationSecs + record + templateId + updatedAt blob, or null if none is configured. The dashboard Place AI call dialog hydrates from this same blob. |
| clear_outbound_defaults | Clear the saved outbound AI agent on this number. The Place AI call dialog then falls back to generic defaults (blank prompt + default voice) when opened from this number's row. Does not affect the inbound AI receptionist on the same number, the BYOK key, or any other config. |
| release_number | Release a phone number, deactivating it and stopping billing. This action is irreversible. |
| send_sms | Send an SMS right now from one of your provisioned numbers, to anyone. Use this to start a conversation, not just to answer one: outbound-initiated outreach is fully supported. For outreach that should go out later or repeat on a cadence, use 'create_schedule' instead. If the number has smsMode 'ai', the recipient's reply lands on the same thread and the AI answers it in context. US and Canada destinations. 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. New accounts can text right away: a starter allowance covers up to 10 different new numbers on Free (lifetime) and up to 25 on a new Pro account (while it is under 7 days old), straight after provisioning (content-screened; re-texting the same numbers stays free of the allowance). A 403 with code `sms_starter_exhausted` means that allowance is spent; a 403 with code `destination_not_verified` means the account is restricted (a voice call, or a non-starter path) and can only reach numbers it owns, numbers that contacted it first, or individually verified numbers. To fix either on Pro, submit a business verification (POST /v1/business-verification, or the Verification page in the dashboard); that lifts the restriction in minutes. Returns the message object with ID and delivery status. |
| get_inbox | Get inbound SMS messages for a phone number. Can filter to show only messages containing OTP codes. |
| get_message | Get a specific SMS message by its ID. Returns the full message including body, OTP (if extracted), and its delivery outcome: status is 'queued', 'sent', 'delivered', or 'failed', with errorCode set when a carrier rejected it. Use this to confirm an outbound text actually reached the recipient, because the 201 from send_sms only means the carrier accepted it. An errorCode of '40010' means the sending number is not registered for A2P texting yet: check that number's messaging.state with get_number. |
| wait_for_otp | Wait for an OTP verification code to arrive via SMS on a phone number. Polls the inbox until an OTP is detected or timeout is reached. Returns the extracted code string. |
| list_sms_conversations | List the two-way AI SMS conversation threads this agent is handling, newest activity first. Each thread is one contact texting one of your numbers that has smsMode='ai'. |
| get_sms_conversation | Get a single two-way AI SMS conversation thread by ID, including its recent messages (up to the last 50, oldest first) and a `context` object that classifies those messages by freshness. Use `context` when the question is about recency: `messages` is the last 50 texts on the thread, which on a quiet thread can span months, so treating them as "recent" will make you describe a months-old exchange as something you just talked about. `context.recentSubstantiveMessages` is the only place to answer "what did we recently talk about?"; when it is empty, say there has been no recent substantive SMS discussion instead of reaching into `context.olderMessages`. |
| reply_to_sms_conversation | Send a reply into a two-way SMS conversation thread. This is the reply path for LLM-direct-text / relay numbers (smsMode: 'relay'): your agent received the inbound text via your relay webhook, and calls this to answer. AgentCall sends + threads the SMS. Blocked if the recipient opted out (STOP). Pass idempotencyKey to make retries safe (a duplicate returns status 'duplicate' without sending again). |
| initiate_call | Start a plain (non-AI) outbound phone call from one of your provisioned numbers. Pro plan only ($19.99/mo plus usage): a 403 with code `plan_limit_standard_calls` means the account is on Free; offer upgrade_to_pro only if the user requests an upgrade and share the link it returns, or configure inbound AI on the number instead. The callee hears a short automated line identifying the call as coming from an AI agent through AgentCall; there is no live audio behind it, so use initiate_ai_call when the agent needs to talk. Optionally enable call recording ($0.01/min). A 403 with code `destination_not_verified` means the account is still restricted (Free, or Pro under 7 days old) and can only call numbers it owns, numbers that contacted it first, or individually verified numbers. Do not retry or probe other destinations. To fix it on Pro, submit a business verification (POST /v1/business-verification, or the Verification page in the dashboard); that lifts the restriction in minutes. |
| list_calls | List call history for this agent. Returns calls with their status, duration, and recording URLs. |
| get_call | Get details of a specific call by ID, including status, duration, and recording URL. |
| hangup_call | Terminate an active phone call. The call must be in progress. |
| initiate_ai_call | Start an AI-powered voice call where AI handles the conversation autonomously. The AI will speak using the specified voice and follow the system prompt instructions. Pro plan only ($19.99/mo plus usage, AI voice calls $0.40/min): a 403 with code `plan_limit_voice_ai` means the account is on Free; offer upgrade_to_pro only if the user requests an upgrade, show the human the link it returns, and retry this call once they have subscribed (about a minute). Available on US and Canada numbers. Pass `language` to make the AI speak a specific language for the call (useful for booking on behalf of someone in another language). Before writing systemPrompt from scratch, fetch GET https://api.agentcall.co/v1/calls/prompt-templates?direction=outbound (no auth) for outbound-flavored templates (appointment booker on behalf of, info request, callback) with placeholders to fill in. A 403 with code `destination_not_verified` means the account is still restricted (Free, or Pro under 7 days old) and can only call numbers it owns, numbers that contacted it first, or individually verified numbers. Do not retry or probe other destinations. To fix it on Pro, submit a business verification (POST /v1/business-verification, or the Verification page in the dashboard); that lifts the restriction in minutes. For CSV / batch calling, pass `useSavedAgent: true` to hydrate systemPrompt + voice + language + firstMessage + maxDurationSecs + record from the saved outbound agent on the from-number (set via set_outbound_defaults). The agent will use the saved persona for every call from that number without re-typing the prompt. Per-call overrides still win, so you can pass firstMessage='Hi Dr. Smith' to personalize while inheriting the saved prompt + voice. Pass `idempotencyKey` to make retries safe: a duplicate request with the same key replays the original response and does NOT place a second carrier call. The canonical Hermes CSV row pattern is `{from, to, useSavedAgent: true, idempotencyKey: 'batch-id:row-id'}`. |
| get_call_transcript | Get the transcript of a completed AI voice call. Returns the full conversation with timestamps, a summary, and call duration. |
| synthesize_speech | Turn text into spoken audio using the SAME 10 voices the AI uses on calls, so the voice identity carries off-call to IVR prompts, voicemail greetings, generated show segments, or social clips. Pro plan only ($19.99/mo plus usage); a 403 plan_limit_tts means offer upgrade_to_pro only if the user requests an upgrade. Metered at $0.03 per 1,000 characters. Returns the audio inline (base64) plus the billed character count. Text is capped at 4096 characters per call. |
| create_webhook | Subscribe to outbound event delivery: AgentCall POSTs to your HTTPS URL when events fire (SMS received, OTP detected, call completed, etc.). NOT for handling inbound calls — to make a phone number answer incoming calls, use 'configure_inbound_ai' instead. The URL must use HTTPS. |
| rotate_webhook_secret | Rotate the signing secret for a webhook. The old secret is immediately invalidated and a new one is generated. Store the new secret securely — it is only shown once. |
| delete_webhook | Deactivate and remove a webhook endpoint. It will immediately stop receiving events. |
| list_webhooks | List all registered webhook endpoints and their subscribed events. |
| get_usage | Get usage and cost breakdown for a billing period. Returns numbers provisioned, SMS sent/received, call minutes, recording minutes, and total cost. |
| get_plan | Show which plan the account behind this API key is on (Free or Pro), the Free limits, the remaining AI allowance and actual trial expiry or legacy reset, and a one-sentence `summary` you can read to the user. Call this before explaining any `plan_limit_*` error, and whenever the user asks what plan they are on, what it costs, or what is left this month. Read-only and safe to call any time. Pro is $19.99/mo plus usage; offer upgrade_to_pro only if the user requests an upgrade to get a checkout link. |
| upgrade_to_pro | Start an AgentCall Pro upgrade for the account that owns this API key. Returns a secure checkout link the human clicks to subscribe. Pro is $19.99/mo plus usage (AI voice calls $0.40/min, SMS $0.015). Call this the moment any tool fails with a `plan_limit_*` code, then show the human the link exactly as returned. Takes about a minute; the failed action can be retried right after. |
| list_contacts | List the callers (contacts) seen across this agent's phone numbers. Returns the most recently active first, with display name (if known), call count, owner-set tags, and timestamps. Use this to browse who has called and who has been called. |
| get_contact | Get a single contact by ID. Returns display name, tags, owner notes, verified flag, blocked status, call count, and timestamps. |
| get_contact_by_phone | Look up a contact by their E.164 phone number. Returns 404 if no contact exists for this phone yet (e.g. a number we've never called or received a call from). |
| get_next_call_context | THE killer tool for cross-call memory: render the compact Memory paragraph that would be injected into the next AI call from or to this contact. Use BEFORE placing an AI call to know who the caller is, what was discussed, and what's still open. Returns isEmpty=true and an empty contextBlock when there's no useful memory yet (first call from this contact, or AgentCall Memory not yet enabled on this agent). |
| get_current_memory | Return the active Memory rows ("Current Truth") for a contact or scope. Memory is the structured, source-backed memory layer extracted from prior calls. Each row has a slug (the concept handle), text (the value), confidence (0..1), and the IDs of the CallReports that corroborate it. Use get_next_call_context if you want the rendered text block instead of raw rows. |
| get_memory | Get a single Memory row by ID. |
| get_memory_timeline | Append-only audit log for one Memory slot. Every proposed / applied / corroborated / superseded / rejected event with the linked CallReport and the before/after states. The audit trail that backs the memory. |
| list_memory_candidates | List MemoryCandidate rows. The post-call extractor produces these for every completed AI call; high-confidence ones auto-promote into Memory based on the agent's memoryPolicy. Use this to inspect what was proposed and why (status=proposed for unreviewed, status=rejected for contradictions caught by the Bob-vs-Robert handler). |
| list_call_reports | List CallReport rows across all calls. Each report is the structured analysis the extractor produced for a completed AI call (summary, intent, urgency, extracted facts, etc). Use get_call_report to fetch a single report's full payload + candidates. Filter by contactId to see all reports for one caller, or briefWorthy=true to see just the calls flagged for owner attention. |
| update_contact | Owner-edit a contact's mutable fields. Pass only the fields to change. displayName, ownerNotes, and blockedAt accept null to clear. At least one field is required. |
| purge_contact | DESTRUCTIVE. Wipes a caller's Memory + MemoryCandidate + Brief rows, redacts every CallReport.payload that referenced them, and deletes the Contact. Underlying Call rows and raw CallTranscript stay (billing/TCPA evidence). Returns wipe counts. Idempotent on missing contacts (returns zero counts). Use only when the caller has formally requested erasure. |
| update_memory | Owner-edit a Memory row's text or expiry. Writes an 'edited' MemoryEvent to the audit trail so the change is traceable. Pass null to expiresAt to clear an expiry. |
| delete_memory | Soft-delete a Memory row: sets active=false and writes an 'expired' MemoryEvent. The row stays in the DB for audit but no longer appears in Current Truth or pre-call context. To wipe entirely, use purge_contact on the linked Contact. |
| approve_memory_candidate | Manually promote a proposed MemoryCandidate to Memory. Bypasses the auto-promotion policy (used for types like task / decision that don't auto-approve, or for candidates below the confidence threshold). When the same Memory slot has a different value, the approval SUPERSEDES it (owner-set always wins contradictions, unlike auto-policy which requires a 0.15 confidence margin). |
| reject_memory_candidate | Manually reject a proposed MemoryCandidate. Marks it status='rejected' and writes a 'rejected' MemoryEvent. The candidate row stays in the DB for the audit trail. |
| list_briefs | List Brief items (owner-facing digest of calls needing attention). Defaults to open + acknowledged briefs. Filter by status, urgency, or contactId. Briefs are produced by the extractor when a call has ownerBrief in its payload or when intent+urgency together flag the call as briefWorthy. |
| acknowledge_brief | Mark a brief as acknowledged ('I have seen this'). Acknowledged briefs stay in the working set (use resolve_brief to close them out). Idempotent: re-acking an acknowledged brief returns the existing acknowledgedAt timestamp. |
| resolve_brief | Close out a brief: status=resolved with resolvedAt stamped. For items the owner has finished acting on. Idempotent. |
| set_memory_enabled | Owner-toggle for the Auditable Call Memory feature. When enabled=true, every completed AI call writes a Contact, runs the post-call extractor (gpt-4o-mini), and populates the Memory + Briefs tables. When enabled=false, AI calls behave the way they did pre-feature. Toggling off does NOT delete existing Memory rows; use purge_contact to wipe a caller. Caller memory is available on Free and Pro within the account's voice allowance. New trials have five inbound AI minutes total over 72 hours; existing Free accounts retain their assigned monthly offer. Stored memory remains available after a trial ends. Memory does not add a separate usage fee. Returns the new memoryEnabled value. |
| get_call_report | Get the full structured analysis for a completed AI call. Includes the summary, intent, urgency, extracted facts/preferences/decisions/commitments/tasks, the nextCallContext paragraph, and all MemoryCandidate rows linked to this call. Reports become available 5-30 seconds after the call ends (the extractor runs in a background queue); returns isError when the call is still in progress. |
| create_schedule | Make a number's agent text someone FIRST, on a schedule: appointment reminders, payment follow-ups, check-ins, recurring digests. Use this (NOT 'send_sms') whenever the outreach should happen at a future time or on a repeating cadence; use 'send_sms' for a one-off text to send right now. Provide EITHER fireAt (a one-shot ISO 8601 time in the future) OR recurrence (a recurring spec). And EITHER template (sent verbatim, with {{placeholders}} filled from payload) OR promptHint (the agent composes the message using its memory). The recipient's reply lands on the same SMS thread, so if the number has smsMode 'ai' the reactive agent answers it in context and a follow-up like 'C' is understood. Pro plan only ($19.99/mo plus usage; schedules never fire on Free, so offer upgrade_to_pro only if the user requests an upgrade first for a Free account). The send works on any provisioned number; smsMode 'ai' is what makes the reply get answered automatically. Billed as one outbound SMS when it fires, always skipped for a contact who has sent STOP, and capped at 200 sends per number per day. Pass dedupeKey to make a re-create safe (a duplicate key returns a 409). |
| list_schedules | List the proactive message schedules on a number, soonest nextRunAt first. Optionally filter by status. |