---
canonical_url: "https://docs.composio.dev/toolkits/agentphone"
markdown_url: "https://docs.composio.dev/toolkits/agentphone.md"
product: "platform"
version: null
last_updated: null
---

# AgentPhone

AgentPhone gives AI agents phone numbers for messaging and voice calls, with contacts, conversations, webhooks, usage, sub-accounts, WhatsApp, and integrations.

- **Category:** phone & sms
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 76
- **Triggers:** 0
- **Slug:** `AGENTPHONE`
- **Version:** 00000000_00

## Tools

### Check Verification

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | string | Yes | Sensitive six-digit code entered by the recipient. It is sent only to AgentPhone for this check and is never returned. |
| `verification_id` | string | Yes | Verification ID returned by SEND_VERIFICATION. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Complete WhatsApp Connection

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | string | Yes | Short-lived exchange code returned by Meta Embedded Signup. The code is consumed to authorize and store the WhatsApp connection. |
| `waba_id` | string | No | WhatsApp Business Account ID from the Embedded Signup message event. Omit it when AgentPhone should discover the WABA from the exchanged code. |
| `agent_id` | string | No | AgentPhone agent ID to attach to the onboarded WhatsApp number. |
| `business_id` | string | No | Meta business portfolio ID returned by Embedded Signup. |
| `phone_number_id` | string | No | Meta business phone-number ID to register and onboard. Omit it for a WABA-only connection. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Configure Webhook

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | Callback URL to create or update (maximum 2083 characters). |
| `timeout` | integer | No | Webhook request timeout accepted by AgentPhone; omit to keep the provider default. |
| `agent_id` | string | No | Agent ID whose override to configure; omit to configure the account webhook. |
| `context_limit` | integer | No | Recent messages included in each payload (0-50); omit for the provider default of 10. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Connect WhatsApp Number

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | AgentPhone agent ID to attach to the WhatsApp number after registration. |
| `connection_id` | string | Yes | AgentPhone WhatsApp connection ID for the already-connected WABA. |
| `phone_number_id` | string | Yes | Meta phone-number ID belonging to the connection's WABA. This action registers the number for Meta Cloud API use, which can remove it from the WhatsApp Business app. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Agent

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human-readable agent name. |
| `voice` | string | No | AgentPhone voice ID selected for the agent. |
| `language` | string | No | Supported BCP-47 locale used for speech recognition and pronunciation. |
| `stt_mode` | string ("fast" | "accurate") | No | Speech-to-text preference: fast favors latency and accurate favors accuracy. |
| `model_tier` | string ("turbo" | "balanced" | "max") | No | Hosted model quality and latency tier. |
| `voice_mode` | string ("webhook" | "hosted") | No | How the agent handles conversations: webhook forwards transcripts to your service, while hosted uses AgentPhone's built-in LLM. |
| `description` | string | No | Optional description of the agent's purpose. |
| `voice_speed` | number | No | Speech speed multiplier from 0.5 to 2.0. |
| `custom_tools` | array | No | Up to 20 HTTPS functions available to a hosted agent during calls. |
| `ambient_sound` | string ("none" | "office" | "coffee-shop" | "outdoor") | No | Background ambience played between conversational turns. |
| `begin_message` | string | No | Opening message spoken by a hosted agent. |
| `system_prompt` | string | No | Instructions for the built-in LLM when voice_mode is hosted. |
| `denoising_mode` | string ("noise-cancellation" | "noise-and-background-speech-cancellation") | No | Audio denoising strategy applied to caller audio. |
| `max_silence_ms` | integer | No | Caller silence duration in milliseconds before the call is ended. |
| `transfer_number` | string | No | E.164 destination used when the agent transfers a call. |
| `enable_messaging` | boolean | No | Whether a hosted agent may send and read messages during calls. |
| `voicemail_message` | string | No | Message to leave when voicemail is detected. |
| `enable_backchannel` | boolean | No | Whether the agent uses short acknowledgements while the caller speaks. |
| `call_screening_purpose` | string | No | Purpose stated to an automated call screener. |
| `call_screening_identity` | string | No | Identity stated to an automated call screener. |
| `interruption_sensitivity` | number | No | How easily caller audio interrupts the agent, from 0.0 to 1.0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Contact

**Slug:** `AGENTPHONE_CREATE_CONTACT`

Create an AgentPhone contact from a phone number and name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Contact name. |
| `email` | string | No | Contact email address. |
| `notes` | string | No | Free-form notes about the contact. |
| `phone_number` | string | Yes | Contact phone number, normalized to E.164 by AgentPhone. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create SIP Trunk

**Slug:** `AGENTPHONE_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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Sub-Account

**Slug:** `AGENTPHONE_CREATE_SUB_ACCOUNT`

Create an AgentPhone sub-account with the supplied name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name for the new sub-account. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Web Call

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | AgentPhone agent ID that will handle the browser call. |
| `metadata` | object | No | Optional application metadata to associate with the web call. |
| `variables` | object | No | Optional runtime variables made available to the selected agent. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create WhatsApp Template

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Unique template name on the WABA, using only lowercase letters, digits, and underscores. |
| `category` | string ("MARKETING" | "UTILITY" | "AUTHENTICATION") | Yes | Requested Meta category. Meta may recategorize authored content. |
| `language` | string | No | Meta locale code for this template language variant. |
| `components` | array | No | Authored Meta component array. It must include a BODY component, and every component containing variables must include Meta-compatible examples. Use this instead of library_template_name. |
| `connection_id` | string | Yes | AgentPhone WhatsApp connection ID for the target WABA. |
| `parameter_format` | string ("POSITIONAL" | "NAMED") | No | Placeholder style for authored components: POSITIONAL for {{1}} or NAMED for {{first_name}}. |
| `library_template_name` | string | No | Meta Template Library slug. Use this instead of components; an unchanged library template can skip review and become usable immediately. |
| `library_template_body_inputs` | object | No | Optional body-line settings exposed by the selected Meta library template. Valid only when library_template_name is supplied. |
| `library_template_button_inputs` | array | No | Values required by buttons in the selected Meta library template. Valid only when library_template_name is supplied. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Agent

**Slug:** `AGENTPHONE_DELETE_AGENT`

Permanently delete an AgentPhone agent. Associated phone numbers, conversations, and calls remain, but their agent reference is cleared.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | AgentPhone agent ID to permanently delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Contact

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contact_id` | string | Yes | ID of the saved contact to permanently delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Contact Card

**Slug:** `AGENTPHONE_DELETE_CONTACT_CARD`

Permanently remove the recipient-visible iMessage contact card from an owned AgentPhone number. The number itself is not deleted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `number_id` | string | Yes | Owned AgentPhone number ID whose iMessage contact card to remove. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete SIP Trunk

**Slug:** `AGENTPHONE_DELETE_SIP_TRUNK`

Permanently delete a SIP trunk, remove its upstream routing, and soft-delete its local record. Detach dependent numbers first.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `trunk_id` | string | Yes | SIP trunk ID to permanently delete after dependent numbers have been detached. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Sub-Account

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sub_account_id` | string | Yes | Sub-account ID to permanently delete, including its isolated tenant state. Never use the ID of the tenant targeted by the current connection. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Webhook

**Slug:** `AGENTPHONE_DELETE_WEBHOOK`

Delete the account webhook and stop account delivery, or delete an agent override so that agent falls back to the account webhook.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Agent ID whose override to delete; omit to delete the account webhook. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete WhatsApp Template

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Template name to delete. Meta locks this name against reuse for 30 days after deletion. |
| `hsm_id` | string | No | Meta template ID that narrows deletion to one language variant. Omit only when every language variant under name should be permanently deleted. |
| `connection_id` | string | Yes | AgentPhone WhatsApp connection ID for the target WABA. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Disconnect Supabase

**Slug:** `AGENTPHONE_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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Disconnect WhatsApp

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connection_id` | string | Yes | AgentPhone WhatsApp connection ID to disconnect. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download Call Recording

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `call_id` | string | Yes | Authorized AgentPhone call ID whose complete WAV recording to download. The call ID is a bearer capability and must be kept private. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### End Call

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `call_id` | string | Yes | Active AgentPhone call ID to terminate immediately. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Agent

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Existing AgentPhone agent ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Call

**Slug:** `AGENTPHONE_GET_CALL`

Get full status, timing, metadata, and transcript details for one AgentPhone call by ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `call_id` | string | Yes | AgentPhone call ID to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Call Transcript

**Slug:** `AGENTPHONE_GET_CALL_TRANSCRIPT`

Read the complete stored transcript for a completed or in-progress call. Transcript content may be sensitive.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `call_id` | string | Yes | Call whose complete ordered transcript to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Call Transcript Events

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `call_id` | string | Yes | Completed AgentPhone call whose transcript SSE event replay to download. Live and non-terminal calls are rejected. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contact

**Slug:** `AGENTPHONE_GET_CONTACT`

Get one saved AgentPhone contact by its stable contact ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contact_id` | string | Yes | Existing AgentPhone contact ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contact Capabilities

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `phone_number` | string | Yes | Phone number to check for current messaging reachability; E.164 is preferred. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contact Card

**Slug:** `AGENTPHONE_GET_CONTACT_CARD`

Get the recipient-visible iMessage contact card currently configured for one owned AgentPhone number.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `number_id` | string | Yes | Owned AgentPhone number ID whose iMessage contact card to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Conversation

**Slug:** `AGENTPHONE_GET_CONVERSATION`

Get one conversation by ID with participants, channel state, capabilities, and up to 100 recent messages.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message_limit` | integer | No | Maximum recent messages to include (up to 100). Use LIST_MESSAGES for paginated message history. |
| `conversation_id` | string | Yes | Existing AgentPhone conversation ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Location

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `phone_number` | string | Yes | Known, consented phone number whose current provider location to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Number

**Slug:** `AGENTPHONE_GET_NUMBER`

Get one owned AgentPhone number by ID, including active or released records, with its status and channel configuration.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `number_id` | string | Yes | AgentPhone number ID, including the ID of a released number. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Registration Details

**Slug:** `AGENTPHONE_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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Registration Status

**Slug:** `AGENTPHONE_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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get SIP Trunk

**Slug:** `AGENTPHONE_GET_SIP_TRUNK`

Get one SIP trunk by ID with routing, transfer, encryption, URI, and allowed-IP settings. Passwords and credential objects are omitted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `trunk_id` | string | Yes | Existing AgentPhone SIP trunk ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Supabase Status

**Slug:** `AGENTPHONE_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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Usage

**Slug:** `AGENTPHONE_GET_USAGE`

Get current account quotas, reporting-period bounds, and message, call, SMS segment, and webhook activity totals and rolling windows.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Usage Breakdown

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `period` | string ("week" | "month" | "year") | No | Current calendar period. Required for agent and invalid for number. |
| `group_by` | string ("number" | "agent") | Yes | Breakdown dimension: owned phone number or agent. |
| `timezone` | string | No | IANA timezone used to establish agent period boundaries, such as America/New_York. Valid only for agent breakdowns. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Usage Trends

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `periods` | integer | No | Number of periods to return. Daily defaults to 30 and allows 1-365; monthly defaults to 6 and allows 1-24. |
| `granularity` | string ("daily" | "monthly") | Yes | Group usage into daily or monthly time-series periods. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Webhook

**Slug:** `AGENTPHONE_GET_WEBHOOK`

Get the account webhook or one agent's override without exposing its signing secret.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Agent ID whose webhook override to read; omit to read the account webhook. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Webhook Delivery Stats

**Slug:** `AGENTPHONE_GET_WEBHOOK_DELIVERY_STATS`

Get detailed recent webhook delivery health or lightweight all-time aggregate counts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hours` | integer | No | Recent lookback in hours (1-168); omit for 24. Not valid for all_time. |
| `range` | string ("recent" | "all_time") | No | Use recent for a bounded hourly breakdown or all_time for aggregate counts. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get WhatsApp Status

**Slug:** `AGENTPHONE_GET_WHATSAPP_STATUS`

Inspect whether WhatsApp is enabled and connected and return the account's AgentPhone WhatsApp connection IDs.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Agents

**Slug:** `AGENTPHONE_LIST_AGENTS`

List AI voice agents and their current voice, mode, configuration, and attached numbers.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum agents to return in this page (1-100). |
| `cursor` | string | No | Opaque continuation cursor from a previous response; omit for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Calls

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum calls to return on this page (1-100). |
| `cursor` | string | No | Opaque continuation cursor from a previous response; omit for the first page. |
| `search` | string | No | Match text in the from or to phone number. |
| `status` | string ("completed" | "in-progress" | "failed") | No | Filter by call status. |
| `agent_id` | string | No | AgentPhone agent ID whose calls to list; mutually exclusive with number_id. |
| `call_type` | string ("pstn" | "web") | No | Filter by PSTN or browser web call. |
| `direction` | string ("inbound" | "outbound") | No | Filter by call direction. |
| `number_id` | string | No | Owned AgentPhone number ID whose calls to list; mutually exclusive with agent_id. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Contacts

**Slug:** `AGENTPHONE_LIST_CONTACTS`

Search and list saved contacts used in messaging workflows.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum contacts to return on this page (1-200). Repeat the same value when continuing with a cursor. |
| `cursor` | string | No | Opaque continuation cursor from a previous response. Omit for the first page; when the first request used a non-default limit, repeat that limit. |
| `search` | string | No | Search contact names, phone numbers, or other indexed contact text. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Conversations

**Slug:** `AGENTPHONE_LIST_CONVERSATIONS`

List account-wide or agent-scoped messaging conversations with participants, channels, latest activity, and message counts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum conversations to return on this page (1-100). |
| `cursor` | string | No | Opaque continuation cursor from a previous response; omit for the first page. |
| `agent_id` | string | No | AgentPhone agent ID whose conversations to list; omit for the account. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Messages

**Slug:** `AGENTPHONE_LIST_MESSAGES`

Read one newest-first page of message history for either a conversation or an owned phone number.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `after` | string | No | ISO 8601 timestamp; return messages newer than this time. |
| `limit` | integer | No | Maximum messages to return on this page (1-200). |
| `before` | string | No | ISO 8601 timestamp; return messages older than this time. |
| `cursor` | string | No | Opaque continuation cursor from a previous response. Do not combine it with before or after. |
| `number_id` | string | No | Owned number whose messages to read; provide exactly one selector. |
| `conversation_id` | string | No | Conversation whose messages to read; provide exactly one selector. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Numbers

**Slug:** `AGENTPHONE_LIST_NUMBERS`

List owned AgentPhone numbers with routing, agent assignment, SMS registration, and channel status.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum numbers to return on this page (1-100). |
| `cursor` | string | No | Opaque continuation cursor from a previous response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List SIP Trunks

**Slug:** `AGENTPHONE_LIST_SIP_TRUNKS`

List SIP trunks and their routing, transfer, encryption, URI, and IP configuration. Passwords and credential objects are omitted from results.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Sub-Accounts

**Slug:** `AGENTPHONE_LIST_SUB_ACCOUNTS`

List isolated sub-accounts with optional recent activity statistics.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum sub-accounts to return on this page (1-100). |
| `cursor` | string | No | Opaque continuation cursor from a previous response; omit for the first page. |
| `stats_days` | integer | No | Include usage statistics for this many recent days (1-90). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Voices

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `max_results` | integer | No | Maximum number of voices to include in the response (1-100). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Webhook Deliveries

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hours` | integer | No | Account-only lookback window in hours (1-168). |
| `limit` | integer | No | Maximum deliveries to return (1-100). |
| `cursor` | string | No | Account-only opaque continuation cursor; omit for the first page. |
| `agent_id` | string | No | Agent ID whose recent deliveries to list; omit for account-wide deliveries. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List WhatsApp Numbers

**Slug:** `AGENTPHONE_LIST_WHATSAPP_NUMBERS`

List phone numbers available on a connected WhatsApp Business Account and show which are already connected to AgentPhone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connection_id` | string | Yes | AgentPhone WhatsApp connection ID from Get WhatsApp Status. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List WhatsApp Templates

**Slug:** `AGENTPHONE_LIST_WHATSAPP_TEMPLATES`

List and filter a connected WhatsApp Business Account's message templates, including their language variants and Meta approval status.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Filter to one template name and all of its language variants. |
| `status` | string ("APPROVED" | "PENDING" | "REJECTED" | "PAUSED" | "DISABLED") | No | Filter by Meta approval status. |
| `category` | string ("MARKETING" | "UTILITY" | "AUTHENTICATION") | No | Filter by Meta template category. |
| `language` | string | No | Filter by Meta locale code, such as en_US. |
| `connection_id` | string | Yes | AgentPhone WhatsApp connection ID from Get WhatsApp Status. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Lookup Numbers

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `phone_numbers` | array | Yes | One to 25 E.164 phone numbers to inspect. AgentPhone bills $0.009 for every number submitted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Place Call

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `voice` | string | No | AgentPhone voice ID for this call; omit to use the agent's configured voice. |
| `agent_id` | string | Yes | AgentPhone agent ID that will conduct the outbound call. |
| `to_number` | string | Yes | Consented destination in E.164 format. Calling this number immediately creates an externally visible, metered telephone call. |
| `variables` | object | No | String values substituted into {{variable}} placeholders in the prompt and greeting. Requires system_prompt or a hosted-mode agent. |
| `model_tier` | string ("turbo" | "balanced" | "max") | No | Built-in conversation model tier used when system_prompt is provided; omit to use the agent's configured tier. |
| `system_prompt` | string | No | Per-call instructions for AgentPhone's built-in LLM. When provided, the built-in LLM handles the conversation instead of a webhook. |
| `from_number_id` | string | No | AgentPhone number ID assigned to the agent and used as caller ID. Omit to use the agent's first assigned number. |
| `initial_greeting` | string | No | Greeting spoken when the recipient answers. Pass an empty string to wait silently for the recipient to speak first. |
| `disable_recording` | boolean | No | Set true when audio-recording consent is absent. AgentPhone still captures a transcript even when audio recording is disabled. |
| `call_screening_purpose` | string | No | Purpose stated to an automated call screener. |
| `call_screening_identity` | string | No | Identity stated to an automated call screener. If only a screening purpose is supplied, AgentPhone uses the agent's name as the identity. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Provision Number

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `country` | string ("US" | "CA") | No | Country for the new number. Submitting this request purchases a number and starts a recurring charge of at least $3 per month. |
| `agent_id` | string | No | AgentPhone agent ID to attach immediately after the number is purchased. |
| `area_code` | string | No | Preferred three-digit area code. Inventory is not reserved by a prior search, so availability may change before purchase. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Refresh Locations

**Slug:** `AGENTPHONE_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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Refresh Supabase Token

**Slug:** `AGENTPHONE_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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Release Number

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `number_id` | string | Yes | Owned AgentPhone number ID to release permanently. This cannot be undone, and the number cannot be recovered. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Available Numbers

**Slug:** `AGENTPHONE_SEARCH_AVAILABLE_NUMBERS`

Search unreserved US or Canadian phone-number inventory before provisioning a number. Results are live inventory and are not reserved.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | No | City name; pair with state because support varies by account. |
| `limit` | integer | No | Maximum number candidates to return (1-30). |
| `state` | string | No | Two-letter US state or Canadian province code. |
| `country` | string ("US" | "CA") | No | Country whose inventory to search. |
| `zip_code` | string | No | Five-digit ZIP code; provider support varies by account. |
| `area_code` | string | No | Three-digit area code, the most broadly supported location filter. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send Message

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `body` | string | Yes | Message text delivered to the recipient. Must be non-empty unless template or media_urls is supplied; for a WhatsApp template send, this is only a fallback label in message history. |
| `buttons` | array | No | Up to three WhatsApp reply-button labels, each at most 20 characters. |
| `channel` | string | No | Set to whatsapp to override a dual-channel sender's normal transport. WhatsApp-only senders use WhatsApp automatically. |
| `agent_id` | string | No | AgentPhone agent ID to associate with the outbound message. |
| `template` | object | No | Approved WhatsApp template. Required outside the 24-hour customer service window. |
| `list_menu` | object | No | WhatsApp list-menu definition using simple options or structured sections. |
| `number_id` | string | No | Owned AgentPhone sender number ID. Mutually exclusive with from_number. |
| `to_number` | string | No | One phone number, email address, US short code, or existing iMessage group ID. Mutually exclusive with recipients. |
| `media_urls` | array | No | Public HTTPS URLs for media attached to the message. WhatsApp sends support one attachment; other channels may support multiple attachments. |
| `recipients` | array | No | Two or more phone numbers or email addresses for a new iMessage group. Mutually exclusive with to_number. |
| `send_style` | string ("celebration" | "fireworks" | "lasers" | "love" | "confetti" | "balloons" | "spotlight" | "echo" | "invisible" | "gentle" | "loud" | "slam") | No | Optional expressive effect for an iMessage-capable sender. |
| `from_number` | string | No | Owned sender phone number. Mutually exclusive with number_id. |
| `call_to_action` | object | No | WhatsApp HTTPS link button displayed on an ordinary message. |
| `reply_to_message_id` | string | No | Parent message ID for an inline iMessage or WhatsApp reply. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send Reaction

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reaction` | string | Yes | Classic tapback (love, like, dislike, laugh, emphasize, or question) or a custom emoji supported by the sender line and recipient device. |
| `message_id` | string | Yes | Existing iMessage message ID to react to. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send Typing Indicator

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Active one-to-one or group iMessage conversation ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send Verification

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `phone_number` | string | Yes | Destination phone number in E.164 format. Sending the code incurs the standard outbound SMS rate for its country. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set Agent Number Assignment

**Slug:** `AGENTPHONE_SET_AGENT_NUMBER_ASSIGNMENT`

Attach an owned phone number to an agent or detach it, changing which agent handles that number.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent that should gain or lose the number. |
| `number_id` | string | Yes | Owned AgentPhone number ID to attach or detach. |
| `assignment` | string ("attach" | "detach") | Yes | Whether to attach or detach the number. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set Contact Card

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `last_name` | string | No | Last name for the replacement card. Omit or pass null to leave it unset. |
| `number_id` | string | Yes | Owned AgentPhone number ID whose iMessage contact card to replace. |
| `avatar_url` | string | No | Public avatar URL for the replacement card. Omit or pass null for no avatar. |
| `first_name` | string | No | First name for the replacement card. Omit or pass null to leave it unset. |
| `display_name` | string | No | Display name for the replacement card. Omit or pass null to leave it unset. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Start Supabase Connection

**Slug:** `AGENTPHONE_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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Submit A2P Registration

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ein` | string | No | Sensitive EIN or tax ID required for standard_brand and high_volume. It is sent only to AgentPhone for carrier registration and is never returned. |
| `city` | string | Yes | Business city. |
| `email` | string | Yes | Registration contact's email address. |
| `state` | string | Yes | Business state or region. |
| `volume` | string ("low" | "high") | No | Expected message volume. |
| `country` | string | No | Business country code. |
| `includes` | array | No | Content types included in campaign messages. |
| `industry` | string | No | Business industry, such as technology, retail, or healthcare. |
| `zip_code` | string | Yes | Business postal code. |
| `last_name` | string | Yes | Registration contact's last name. |
| `use_cases` | array | Yes | One to five specific carrier campaign use cases. |
| `brand_name` | string | No | Public-facing brand name when different from business_name. |
| `first_name` | string | Yes | Registration contact's first name. |
| `description` | string | Yes | What the business does, who it messages, and what messages it sends. |
| `link_sample` | string | No | Example URL when campaign messages contain links. |
| `website_url` | string | No | Business website URL. |
| `consent_flow` | string | Yes | How recipients explicitly opt in to receive the campaign's messages. |
| `phone_number` | string | Yes | Registration contact's phone number in E.164 format. |
| `business_name` | string | No | Legal business name; required for standard_brand and high_volume. |
| `contact_title` | string ("ceo" | "cfo" | "cto" | "coo" | "vp" | "gm" | "director" | "other") | No | Registration contact's role; required for standard_brand and high_volume. |
| `street_address` | string | Yes | Primary business street address. |
| `message_samples` | array | Yes | Two to five 20-1024 character examples that include the brand name. |
| `planned_numbers` | integer | No | Number of phone numbers planned for this campaign. |
| `business_regions` | array | No | Regions where the business operates. |
| `opt_in_image_url` | string | Yes | Public HTTPS URL to a PNG, JPG, WEBP, or GIF screenshot of the opt-in flow, no larger than 2 MB. |
| `street_address_2` | string | No | Secondary business address line. |
| `organization_type` | string ("sole_proprietor" | "private_corporation" | "public_corporation" | "llc" | "partnership" | "non_profit" | "co_op" | "government") | No | Legal organization type; required for standard_brand and high_volume. |
| `registration_type` | string ("sole_proprietor" | "standard_brand" | "high_volume") | Yes | Registration tier: sole_proprietor costs $25, standard_brand costs $25, and high_volume costs $70 and includes external brand vetting. |
| `create_sub_account` | boolean | No | Whether to create a dedicated sub-account for this campaign. The fee is always charged to the parent account. |
| `privacy_policy_url` | string | No | Privacy policy URL; required for standard_brand and high_volume. |
| `contact_title_other` | string | No | Custom contact role, required when contact_title is other. |
| `terms_of_service_url` | string | No | Terms-of-service URL; required for standard_brand and high_volume. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Test Webhook

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `target` | string ("account" | "agent") | No | Send through the account webhook or one agent's webhook override. |
| `agent_id` | string | No | For target=agent, the required agent webhook owner. For target=account, an optional agent ID to include in the fake message payload. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update A2P Registration

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `volume` | string ("low" | "high") | No | Replacement expected message volume. |
| `includes` | array | No | Replacement campaign content-type list. |
| `use_cases` | array | No | Replacement list of one to five carrier campaign use cases. |
| `brand_name` | string | No | Replacement public-facing brand name. |
| `description` | string | No | Replacement description of the business and its messaging activity. |
| `link_sample` | string | No | Replacement example URL for messages that contain links. |
| `website_url` | string | No | Replacement business website URL. |
| `consent_flow` | string | No | Replacement explanation of how recipients opt in. |
| `business_name` | string | No | Replacement legal business name. |
| `message_samples` | array | No | Replacement set of two to five brand-bearing message examples. |
| `opt_in_image_url` | string | No | Replacement public HTTPS screenshot URL documenting the opt-in flow. |
| `privacy_policy_url` | string | No | Replacement privacy policy URL. |
| `terms_of_service_url` | string | No | Replacement terms-of-service URL. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Agent

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New agent name. |
| `voice` | string | No | Replacement provider voice ID. |
| `agent_id` | string | Yes | AgentPhone agent ID to update. |
| `language` | string | No | New supported BCP-47 speech locale. |
| `stt_mode` | string ("fast" | "accurate") | No | New speech-to-text mode. |
| `model_tier` | string ("turbo" | "balanced" | "max") | No | New hosted model tier. |
| `voice_mode` | string ("webhook" | "hosted") | No | New execution mode; switching to hosted re-provisions the voice agent. |
| `description` | string | No | New agent description. Omit null values; the API ignores them. |
| `voice_speed` | number | No | New speech speed from 0.5 to 2.0. |
| `custom_tools` | array | No | Replacement set of up to 20 hosted tools; [] clears all tools and omission preserves them. |
| `ambient_sound` | string ("none" | "office" | "coffee-shop" | "outdoor") | No | New background ambience. |
| `begin_message` | string | No | Replacement opening message. |
| `system_prompt` | string | No | Replacement hosted-mode system prompt. |
| `denoising_mode` | string ("noise-cancellation" | "noise-and-background-speech-cancellation") | No | New denoising strategy. |
| `max_silence_ms` | integer | No | New silence timeout from 10000 to 3600000 milliseconds. |
| `transfer_number` | string | No | Replacement E.164 transfer destination. |
| `enable_messaging` | boolean | No | Enable or disable hosted in-call messaging. |
| `voicemail_message` | string | No | Replacement voicemail message. |
| `enable_backchannel` | boolean | No | Enable or disable short spoken acknowledgements. |
| `call_screening_purpose` | string | No | Replacement screening purpose. |
| `call_screening_identity` | string | No | Replacement screening identity. |
| `interruption_sensitivity` | number | No | New interruption sensitivity from 0.0 to 1.0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Chat Background

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image_url` | string | No | Required for operation=set and forbidden for remove. Public HTTPS URL of a JPEG, PNG, GIF, WebP, or HEIC image no larger than 10 MB. |
| `operation` | string ("set" | "remove") | Yes | Set a new custom image or remove the current custom background. |
| `conversation_id` | string | Yes | One-to-one or group iMessage conversation ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Contact

**Slug:** `AGENTPHONE_UPDATE_CONTACT`

Update explicitly supplied fields of an existing AgentPhone contact.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Replacement contact name. |
| `email` | string | No | Replacement email address. Pass null explicitly to clear it. |
| `notes` | string | No | Replacement notes. Pass null explicitly to clear them. |
| `contact_id` | string | Yes | Existing contact ID to update. |
| `phone_number` | string | No | Replacement phone number, normalized to E.164 by AgentPhone. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Conversation

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `metadata` | object | No | Replacement custom context surfaced to webhooks as conversationState. Pass null explicitly to clear it; omitting it leaves it unchanged. |
| `group_name` | string | No | Replacement display name for an iMessage group and its underlying thread. Pass null explicitly to clear it; omit for 1:1 chats or to leave it unchanged. |
| `conversation_id` | string | Yes | Existing conversation ID to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update SIP Trunk

**Slug:** `AGENTPHONE_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Replacement display name, up to 64 characters. |
| `trunk_id` | string | Yes | Existing AgentPhone SIP trunk ID. |
| `transfers` | string ("all" | "sip" | "none") | No | Which transfers the trunk permits. |
| `origination_uris` | array | No | Complete replacement list of inbound SIP destinations. An empty list clears them and is allowed only when no numbers are attached. |
| `transfer_caller_id` | string ("transferee" | "transferor") | No | Caller ID presented on a transferred call leg. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Sub-Account

**Slug:** `AGENTPHONE_UPDATE_SUB_ACCOUNT`

Rename an existing AgentPhone sub-account.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | New name for the sub-account. |
| `sub_account_id` | string | Yes | Existing sub-account ID to rename. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |
