AgentPhone
AgentPhone gives AI agents phone numbers for messaging and voice calls, with contacts, conversations, webhooks, usage, sub-accounts, WhatsApp, and integrations.
Tools (76)
Check Verification
Check a recipient-provided six-digit code against a pending verification. Each incorrect check consumes one of at most three attempts. An ok or already_verified result incurs a $0.05 verification fee; incorrect, exhausted, and expired results are free. Only submit a code supplied for this verification. After an ambiguous failure, do not automatically repeat the check because an attempt may have been consumed or the paid verification may have succeeded.
Inputs: code, verification_id
Complete WhatsApp Connection
Complete Meta Embedded Signup using a caller-supplied short-lived code. AgentPhone exchanges the code, stores the WABA connection, subscribes webhooks, and, when a phone-number ID is supplied, registers that number and optionally attaches an agent. Registering a number can remove it from the WhatsApp Business app. This mutates external Meta and WhatsApp state; only run it with explicit approval for the selected WABA and number.
Inputs: code, waba_id, agent_id, business_id, phone_number_id
Configure Webhook
Create or update the account webhook or one agent override. Every call rotates and returns a new signing secret once; store it securely before making another webhook call.
Inputs: url, timeout, agent_id, context_limit
Connect WhatsApp Number
Register one existing WABA phone number for Meta Cloud API use and bind it to AgentPhone, optionally attaching an agent. This changes externally managed Meta state and can remove the number from the WhatsApp Business app.
Inputs: agent_id, connection_id, phone_number_id
Create Agent
Create a webhook-mode or hosted AI voice agent. This configures the agent but does not place a call or assign a phone number.
Inputs: name, voice, language, stt_mode, model_tier, voice_mode, description, voice_speed, custom_tools, ambient_sound, begin_message, system_prompt, denoising_mode, max_silence_ms, transfer_number, enable_messaging, voicemail_message, enable_backchannel, call_screening_purpose, call_screening_identity, interruption_sensitivity
Create Contact
Create an AgentPhone contact from a phone number and name.
Inputs: name, email, notes, phone_number
Create SIP Trunk
Create a SIP trunk with provider-generated routing. Configure origination destinations and transfer policy afterward with Update SIP Trunk. Returned passwords and credential objects are omitted.
Create Sub-Account
Create an AgentPhone sub-account with the supplied name.
Inputs: name
Create Web Call
Create a browser-call session and return a secret access token that expires in 30 seconds. The caller must immediately hand the token to the AgentPhone Web SDK and call startCall; this action does not connect audio itself.
Inputs: agent_id, metadata, variables
Create WhatsApp Template
Submit either authored components or one Meta Template Library entry to a connected WABA. This creates externally managed Meta template state. Authored content normally enters review and can remain pending for up to 24 hours; an unchanged library template may skip review. Meta can recategorize or reject content. Only run after the caller approves the exact content and connection. After an ambiguous failure, list templates before retrying to avoid duplicate submissions.
Inputs: name, category, language, components, connection_id, parameter_format, library_template_name, library_template_body_inputs, library_template_button_inputs
Delete Agent
Permanently delete an AgentPhone agent. Associated phone numbers, conversations, and calls remain, but their agent reference is cleared.
Inputs: agent_id
Delete Contact
Permanently delete one saved AgentPhone contact. This destructive, one-shot operation cannot be undone and does not claim to remove existing messages or conversations. Automatic retries are disabled; after an ambiguous failure, check the contact list before deciding whether to try again.
Inputs: contact_id
Delete Contact Card
Permanently remove the recipient-visible iMessage contact card from an owned AgentPhone number. The number itself is not deleted.
Inputs: number_id
Delete SIP Trunk
Permanently delete a SIP trunk, remove its upstream routing, and soft-delete its local record. Detach dependent numbers first.
Inputs: trunk_id
Delete Sub-Account
Permanently delete an AgentPhone sub-account and all isolated tenant state associated with it. This destructive operation cannot be undone. Delete only a known disposable sub-account, never the tenant targeted by the current connection or other pre-existing tenant state.
Inputs: sub_account_id
Delete Webhook
Delete the account webhook and stop account delivery, or delete an agent override so that agent falls back to the account webhook.
Inputs: agent_id
Delete WhatsApp Template
Permanently delete a Meta WhatsApp template. Supplying hsm_id deletes only that language variant; omitting hsm_id deletes EVERY language variant registered under the name. Meta then blocks reuse of the template name for 30 days. Automatic retries are disabled; after an ambiguous failure, list templates before deciding whether to call again.
Inputs: name, hsm_id, connection_id
Disconnect Supabase
Permanently disconnect the AgentPhone account's existing Supabase integration. This removes stored integration authorization and cannot be undone by this action. Automatic HTTP retries are disabled; after an ambiguous result, check Supabase status before deciding whether to call again. No provider response fields are exposed because the upstream schema is unconstrained.
Disconnect WhatsApp
Permanently disconnect a WhatsApp Business Account from AgentPhone and release its AgentPhone numbers. This stops AgentPhone from using the connection but does not delete the customer's WABA, phone numbers, templates, or other Meta assets. Automatic retries are disabled; after an ambiguous failure, inspect WhatsApp status before deciding whether to call again.
Inputs: connection_id
Download Call Recording
Download the complete WAV recording for a completed AgentPhone call as a file. The call ID is a bearer capability, so only use an authorized ID and keep it private. Recording must be enabled and may become available shortly after completion. Recordings require AgentPhone's $5/month recording add-on. Downloads are complete WAV files up to 20 MB; oversized recordings fail instead of returning a partial file.
Inputs: call_id
End Call
Immediately request termination of an active AgentPhone call. AgentPhone accepts the stop request before its asynchronous call-ended update finishes, so the returned status may still be in-progress; retrieve the call afterward to confirm its terminal status.
Inputs: call_id
Get Agent
Get one AgentPhone agent by ID with its voice configuration and attached numbers. Credential-like custom-tool headers are omitted from the result.
Inputs: agent_id
Get Call
Get full status, timing, metadata, and transcript details for one AgentPhone call by ID.
Inputs: call_id
Get Call Transcript
Read the complete stored transcript for a completed or in-progress call. Transcript content may be sensitive.
Inputs: call_id
Get Call Transcript Events
Download up to 1 MB of SSE events for a completed AgentPhone call as a file. The replay preserves documented connected, turn, heartbeat, and ended events, requires a terminal ended event, and rejects active calls. This is not a live stream.
Inputs: call_id
Get Contact
Get one saved AgentPhone contact by its stable contact ID.
Inputs: contact_id
Get Contact Capabilities
Run a live check, without sending a message, for the current iMessage, SMS, and RCS reachability of a phone number. The check usually takes 1-2 seconds and requires an active capable line; null flags mean this account cannot check that channel. Reachability can change after the check.
Inputs: phone_number
Get Contact Card
Get the recipient-visible iMessage contact card currently configured for one owned AgentPhone number.
Inputs: number_id
Get Conversation
Get one conversation by ID with participants, channel state, capabilities, and up to 100 recent messages.
Inputs: message_limit, conversation_id
Get Location
Get the provider's current latitude, longitude, status, and last-update timestamp for one known phone number. Use only with consent because the response may contain precise location-derived data.
Inputs: phone_number
Get Number
Get one owned AgentPhone number by ID, including active or released records, with its status and channel configuration.
Inputs: number_id
Get Registration Details
Read submitted A2P 10DLC brand and campaign content exactly as exposed for review. EIN data is limited to its last four digits. This does not submit or update a registration.
Get Registration Status
Read the current A2P 10DLC campaign status, processing stage, provider message, and resolved sub-account. This does not submit or update a registration.
Get SIP Trunk
Get one SIP trunk by ID with routing, transfer, encryption, URI, and allowed-IP settings. Passwords and credential objects are omitted.
Inputs: trunk_id
Get Supabase Status
Check whether the AgentPhone account has an authenticated Supabase integration and return non-secret project or account metadata. Credential- and token-like fields are removed recursively from the provider response.
Get Usage
Get current account quotas, reporting-period bounds, and message, call, SMS segment, and webhook activity totals and rolling windows.
Get Usage Breakdown
Break down usage by owned phone number or by agent. Agent breakdowns require a calendar period and optionally accept an IANA timezone; number breakdowns do not accept those filters.
Inputs: period, group_by, timezone
Get Usage Trends
Get message, call, and webhook usage as either daily or monthly time-series points. Select exactly one granularity and optionally bound the number of periods.
Inputs: periods, granularity
Get Webhook
Get the account webhook or one agent's override without exposing its signing secret.
Inputs: agent_id
Get Webhook Delivery Stats
Get detailed recent webhook delivery health or lightweight all-time aggregate counts.
Inputs: hours, range
Get WhatsApp Status
Inspect whether WhatsApp is enabled and connected and return the account's AgentPhone WhatsApp connection IDs.
List Agents
List AI voice agents and their current voice, mode, configuration, and attached numbers.
Inputs: limit, cursor
List Calls
List calls account-wide, for one agent, or for one owned number. Account-wide lists can filter by status, direction, call type, and phone-number text.
Inputs: limit, cursor, search, status, agent_id, call_type, direction, number_id
List Contacts
Search and list saved contacts used in messaging workflows.
Inputs: limit, cursor, search
List Conversations
List account-wide or agent-scoped messaging conversations with participants, channels, latest activity, and message counts.
Inputs: limit, cursor, agent_id
List Messages
Read one newest-first page of message history for either a conversation or an owned phone number.
Inputs: after, limit, before, cursor, number_id, conversation_id
List Numbers
List owned AgentPhone numbers with routing, agent assignment, SMS registration, and channel status.
Inputs: limit, cursor
List SIP Trunks
List SIP trunks and their routing, transfer, encryption, URI, and IP configuration. Passwords and credential objects are omitted from results.
List Sub-Accounts
List isolated sub-accounts with optional recent activity statistics.
Inputs: limit, cursor, stats_days
List Voices
List a bounded prefix of voice IDs and metadata available for hosted AgentPhone agents. AgentPhone does not paginate this catalog; total and truncated indicate when the bounded response omits additional voices.
Inputs: max_results
List Webhook Deliveries
List one page of account-wide deliveries or the bounded recent deliveries for one agent. Callback payloads, response bodies, signatures, and credentials are omitted.
Inputs: hours, limit, cursor, agent_id
List WhatsApp Numbers
List phone numbers available on a connected WhatsApp Business Account and show which are already connected to AgentPhone.
Inputs: connection_id
List WhatsApp Templates
List and filter a connected WhatsApp Business Account's message templates, including their language variants and Meta approval status.
Inputs: name, status, category, language, connection_id
Lookup Numbers
Look up line type, country, and RCS intelligence before messaging up to 25 phone numbers. This is a paid operation that costs $0.009 per submitted number, and automatic retries are disabled to prevent duplicate charges.
Inputs: phone_numbers
Place Call
Immediately place one externally visible, metered outbound telephone call from an AgentPhone agent to a consented destination. The recipient may be called and hear the configured greeting or agent. AgentPhone provides no idempotency key, so automatic HTTP retries are disabled. If a timeout, network failure, server error, or other ambiguous result occurs, inspect recent calls before deciding whether to call again to avoid duplicate calls and charges.
Inputs: voice, agent_id, to_number, variables, model_tier, system_prompt, from_number_id, initial_greeting, disable_recording, call_screening_purpose, call_screening_identity
Provision Number
Purchase and provision an AgentPhone number, optionally choosing an area code and attaching an agent. This immediately incurs a charge and creates an ongoing recurring cost of at least $3 per month for the number.
Inputs: country, agent_id, area_code
Refresh Locations
Request one asynchronous refresh of account location data. This mutates provider refresh state but does not return coordinates; wait the returned interval before using Get Location, and do not poll aggressively.
Refresh Supabase Token
Retrieve a valid Supabase credential server-side, refreshing AgentPhone's stored provider credential when needed. Returns only connection, refresh, availability, expiry, and project metadata; raw access tokens, refresh tokens, JWTs, and other credential fields are never returned.
Release Number
PERMANENTLY AND IRREVERSIBLY release an owned AgentPhone number from its upstream provider and mark it released. The number cannot be recovered, and future inbound and outbound use stops. Existing messages and conversation history remain for audit purposes. This also ends the number's recurring resource lifecycle. Automatic retries are disabled; after an ambiguous failure, retrieve the number and inspect its status before taking further action.
Inputs: number_id
Search Available Numbers
Search unreserved US or Canadian phone-number inventory before provisioning a number. Results are live inventory and are not reserved.
Inputs: city, limit, state, country, zip_code, area_code
Send Message
Send one externally visible and potentially billed SMS, MMS, iMessage, RCS-routed, or WhatsApp message. AgentPhone accepts the message for asynchronous delivery; acceptance does not guarantee delivery. This action has no idempotency key and disables automatic HTTP retries. After any timeout, network failure, server error, or other ambiguous result, inspect recent messages before deciding whether to send again to avoid duplicate messages and charges.
Inputs: body, buttons, channel, agent_id, template, list_menu, number_id, to_number, media_urls, recipients, send_style, from_number, call_to_action, reply_to_message_id
Send Reaction
Send one externally visible iMessage tapback or supported custom emoji reaction to an existing message. SMS and other channels are unsupported. This action has no idempotency key and disables automatic HTTP retries; after any ambiguous failure, inspect the conversation before deciding whether to react again.
Inputs: reaction, message_id
Send Typing Indicator
Show a short-lived, externally visible typing indicator in a one-to-one or group iMessage conversation. It auto-expires after a few seconds and has no stop call. This is best-effort and may be silently dropped for inactive chats, non-iMessage recipients, or RCS-routed chats; an accepted response does not prove recipients observed it. Automatic retries are disabled to avoid duplicate signals.
Inputs: conversation_id
Send Verification
Send an external SMS containing a non-configurable six-digit code that expires after 10 minutes and allows at most three checks. Sending immediately incurs AgentPhone's standard outbound SMS rate for the destination country. A later successful check costs an additional $0.05. Only send with authorization for the destination. After an ambiguous failure, do not blindly resend because the recipient may already have received and the account may already have paid for it.
Inputs: phone_number
Set Agent Number Assignment
Attach an owned phone number to an agent or detach it, changing which agent handles that number.
Inputs: agent_id, number_id, assignment
Set Contact Card
Create or fully replace the recipient-visible iMessage contact card for an owned number. This PUT sends all four card fields; omitted fields are sent as null and therefore are not preserved from the previous card.
Inputs: last_name, number_id, avatar_url, first_name, display_name
Start Supabase Connection
Create a one-shot, short-lived Supabase OAuth bootstrap and return a secret connect URL. A human must promptly open the URL in a browser and complete Supabase authorization; this action does not complete OAuth itself, and the code or URL may expire before use.
Submit A2P Registration
Submit legal business, campaign, consent, and sample-message information for external US carrier A2P 10DLC review. This immediately charges a one-time, registration fee: $25 for sole_proprietor or standard_brand, or $70 for high_volume. Approval typically takes 7-10 business days and is not guaranteed. Only submit with authorization to provide the exact legal and campaign information. After an ambiguous failure, check registration status before any new submission to avoid a duplicate charge or carrier submission.
Inputs: ein, city, email, state, volume, country, includes, industry, zip_code, last_name, use_cases, brand_name, first_name, description, link_sample, website_url, consent_flow, phone_number, business_name, contact_title, street_address, message_samples, planned_numbers, business_regions, opt_in_image_url, street_address_2, organization_type, registration_type, create_sub_account, privacy_policy_url, contact_title_other, terms_of_service_url
Test Webhook
Send one externally observable fake message payload to the account webhook or an agent override. This performs real callback I/O and is never retried automatically.
Inputs: target, agent_id
Update A2P Registration
Submit selected changes to an existing A2P 10DLC registration for external carrier review. This endpoint charges no registration fee. An approved campaign keeps sending under its current approval while changes are reviewed, so acceptance does not mean the changes are already approved. Only send exact, authorized legal and campaign updates. After an ambiguous failure, read the registration details before resubmitting.
Inputs: volume, includes, use_cases, brand_name, description, link_sample, website_url, consent_flow, business_name, message_samples, opt_in_image_url, privacy_policy_url, terms_of_service_url
Update Agent
Update one or more selected fields of an existing voice agent. Supply at least one non-null change; null and omitted fields remain unchanged.
Inputs: name, voice, agent_id, language, stt_mode, model_tier, voice_mode, description, voice_speed, custom_tools, ambient_sound, begin_message, system_prompt, denoising_mode, max_silence_ms, transfer_number, enable_messaging, voicemail_message, enable_backchannel, call_screening_purpose, call_screening_identity, interruption_sensitivity
Update Chat Background
Set or remove the recipient-visible custom background for an iMessage chat. Either operation can permanently replace the prior background, and this API does not return the old image needed to restore it. Setting is a safe no-op when the requested image is already set; removing a default background is also a no-op. Recipients on iOS before version 18 silently see the default background. Automatic retries are disabled; reconcile the chat before another update after ambiguity.
Inputs: image_url, operation, conversation_id
Update Contact
Update explicitly supplied fields of an existing AgentPhone contact.
Inputs: name, email, notes, contact_id, phone_number
Update Conversation
Replace a conversation's stored agent context and/or rename an iMessage group. Only explicitly supplied fields change; metadata replaces the entire stored object, and group_name also renames the underlying iMessage thread.
Inputs: metadata, group_name, conversation_id
Update SIP Trunk
Update selected display, transfer, or inbound origination settings on an existing SIP trunk. Supply at least one non-null change. Passwords and credential objects are omitted from the result.
Inputs: name, trunk_id, transfers, origination_uris, transfer_caller_id
Update Sub-Account
Rename an existing AgentPhone sub-account.
Inputs: name, sub_account_id