AgentPhone

Kick off agent self-signup. Sends a 6-digit OTP to the human's email. Nothing is provisioned server-side until /v0/agent/verify is called with the code.

Verify the OTP and atomically provision everything. Creates: User + Project (+ mirrored Account) + starter hosted Agent + phone number + first-month charge + API key. Returns the key once — agents must save it.

Return available voices from the configured voice provider.

List all agents for this account.

Create a new agent. An agent represents an AI persona (Support Bot, Sales Agent, etc.) that can have phone numbers attached to it. voiceMode: "webhook" (default) forwards transcripts to your webhook. "hosted" uses a built-in LLM with systemPrompt (no webhook needed).

Get a single agent with its attached numbers.

Update an agent's configuration. Use this to change voice mode, system prompt, greeting, or voice. Switching voiceMode to "hosted" re-provisions the voice agent with built-in LLM.

Delete an agent. Phone numbers, conversations, and calls associated with the agent will have their agent reference cleared (set to null) but will not be deleted themselves.

Attach an existing phone number to an agent. The number must belong to the same account and not be released.

Detach a phone number from an agent (sets agentId to null). The number remains active and can be re-attached to any agent.

List all conversations for an agent.

List all calls for an agent.

List the active phone numbers for this account. Released (deleted) numbers are excluded so the count reflects the numbers the account actually holds. Fetch a single number via GET /{number_id} (which returns it regardless of status). Pass externalId to find the number you tagged with your own identifier.

Provision a new phone number from the account's configured SMS provider (or an iMessage line with type=imessage). Optional externalId tags the number with your own identifier; see PATCH /v1/numbers/{id}.

Search purchasable phone numbers before buying one. Pick a number here, then buy it by passing the same `phoneNumber` to `POST /v1/numbers`. Searching with no criteria returns a page of whatever is currently in stock. **Results are not reserved.** This is live inventory, so a number can be bought by someone else between your search and your purchase. When that happens the purchase returns `409` with fresh alternatives in this same shape; pick another and retry rather than treating it as fatal. Criteria support varies by account, and there is no single rule that holds everywhere: - `areaCode` is the most broadly supported filter. - `city`, `state` and `zip` work on some accounts and not others. Where they aren't supported they are ignored rather than rejected, so check what comes back instead of assuming the filter applied. - `state` on its own is honored on some accounts and rejected with `400` on others. Pair it with `city` for consistent behavior. Returns `404` when number search isn't available on your account at all, and `422` when it isn't configured yet. If you need location search and aren't getting it, contact support. Giving a Canadian area code searches Canada even though `country` defaults to `US`. `country=UK` (or `GB`) returns United Kingdom mobile numbers on accounts where they're available. UK numbers are SMS-only and have no area codes, so location filters are rejected for UK searches. If `widened` is true, your exact criteria were out of stock and these are nearby alternatives instead.

Look up line-type intelligence for phone numbers. Answers "should my agent text this number" before spending a message: mobile (`lineType: "mobile"`) vs landline vs VoIP, country, and whether the handset supports RCS. Up to 25 comma-separated numbers per request. Billed at $0.009 per number looked up.

Get a single phone number owned by this account. Returns the number regardless of status (including released) so detail pages still load for numbers that are no longer active. `ext:<externalId>` in place of the id looks the number up by the tag you set.

Update a number. Only the fields you send are changed. externalId: your own identifier for the number. Send a string to set it, null to clear it, or omit it to leave it unchanged. Must be unique within your account (409 otherwise). Works on any number type. The tag is echoed on every number response and webhook payload and usable for lookup as GET /v1/numbers/ext:<externalId> or GET /v1/numbers?externalId=<externalId>. Fields this endpoint does not support are rejected with 422, never silently ignored.

Release (delete) a phone number. This will: 1. Release the number from its upstream provider when supported 2. Mark the number as "released" in the database 3. Keep all messages and conversation history (for audit purposes) WARNING: This action is irreversible! The number cannot be recovered.

Get messages for a specific phone number. Supports cursor-based pagination via before/after timestamps.

List SIP trunks for the current account.

Create a SIP trunk for routing your numbers' calls to your own SIP infrastructure.

Get a single SIP trunk.

Update a SIP trunk (name, transfers, origination URIs).

Delete a SIP trunk (removes upstream and soft-deletes locally).

Get the master webhook configuration for this account.

Register or update the webhook URL for this account. If a webhook already exists, it will be updated. A new secret is generated each time. contextLimit: Number of recent messages to include in webhook payloads (0-50, default: 10). Set to 0 to disable history in webhooks.

Remove the master webhook for this account.

Get paginated webhook delivery attempts for all account webhooks.

Aggregated delivery stats for the account's webhooks over the last N hours.

Lightweight all-time delivery counts using indexed COUNT queries.

Send a test webhook to verify the endpoint is working. Sends a fake message payload to the configured URL. Pass ?agentId=... to control which agent appears in the payload; otherwise the first agent in the account is used.

Get the webhook configuration for a specific agent.

Register or update a webhook URL for a specific agent. When set, this agent's events are delivered here instead of the account default webhook.

Remove the webhook for a specific agent.

Get recent webhook delivery attempts for a specific agent's webhook.

Send a test webhook to the agent's webhook endpoint.

List all contacts for this account. Optional `search` query filters by name or phone number (case-insensitive contains).

Create a new contact. Phone number is normalized to E.164 format. Returns 409 if a contact with this phone number already exists for the project.

Check which messaging channels a phone number supports, without sending a message. Runs a live check (typically 1-2 seconds), so the result reflects the number right now. Capabilities can still change by the time you send. Requires at least one active iMessage-capable or RCS number on the account; each flag is null when your account holds no line that could act on it (rcs reachability is checked against YOUR agents, so it can differ per account while an agent is pre-launch).

Get a single contact by ID.

Update a contact's fields. If phoneNumber is updated, it's re-normalized and checked for uniqueness (409 on conflict).

Delete a contact.

List all conversations for this account. Sorted by most recent activity (lastMessageAt desc). `total` is served from a short per-account cache (app/services/conversation_totals.py); `hasMore` is computed from the page query itself.

Get a conversation with its recent messages.

Update a conversation. - `metadata`: store custom context for AI agents (customer info, order/ticket ids, session state). Replaces the stored object; surfaced in webhook payloads as `conversationState`. - `group_name`: rename a group conversation (iMessage groups only). Also renames the underlying iMessage thread. Only the fields you include are changed: a rename-only PATCH leaves metadata untouched, and vice versa.

Get paginated messages for a conversation. Use before/after for cursor-based pagination.

Show a typing indicator in the conversation (iMessage only). Works for both 1:1 and group chats: a group id is itself a valid typing target, so every participant sees the indicator. Best-effort: the indicator may be silently dropped if the chat has no recent activity, the recipient isn't on iMessage, or it's RCS-routed (RCS carries no composing state). Auto-expires after a few seconds; no "stop typing" call needed.

Set a custom wallpaper for the chat (iMessage only). Customer sends `image_url`; we fetch (≤10MB, JPEG/PNG/GIF/WebP/HEIC), validate, and forward as multipart to the iMessage provider. Idempotent — re-setting replaces. Recipients on iOS < 18 fall back to the default silently.

Clear the custom wallpaper for the chat (iMessage only). Idempotent: deleting a default-background chat returns 204 (no-op).

List all calls for this account.

Initiate an outbound call. This endpoint allows you to programmatically make phone calls from your agent to any phone number. Use `fromNumberId` to pick which of the agent's numbers to use as caller ID; if omitted, the first assigned number is used. Flow: 1. Validates the agent belongs to your account and has a phone number 2. Initiates a call from the agent's number to the destination 3. When recipient answers, speaks the initial greeting (if provided) 4. Listens for recipient's speech and sends to your webhook 5. Continues conversation using your webhook responses

Create a browser-based web call. Returns an access token that your frontend passes to the AgentPhone Web SDK (`agentphone-web-sdk`) to start the call in the browser. The token expires 30 seconds after creation. Flow: 1. Validates the agent belongs to your account 2. Creates a web call and returns an access token 3. Your client calls `webClient.startCall({ accessToken })` to connect 4. Call lifecycle (transcripts, webhooks) works the same as phone calls

Get a specific call with its transcripts.

Terminate an ongoing call. Works for both hosted-mode and webhook-mode calls. The call_ended webhook from the voice provider updates status/endedAt asynchronously, so this endpoint returns the current call as soon as the stop request is accepted upstream.

Stream the audio recording for a specific call. Public bearer-link endpoint. Forwards the browser's Range request upstream and passes the partial response (206 + Content-Range) back through, so the <audio> element can seek — without it, clicking a timestamp does nothing because the browser can't fetch a byte range.

Get the full transcript for a call. Returns the complete, ordered transcript regardless of the webhook contextLimit setting. Each entry contains the user utterance and the corresponding agent response (when available).

Stream a call's transcript via Server-Sent Events. On connect the server replays all existing transcript turns from the database, then streams new turns in real time as they arrive from the voice provider. A ``: heartbeat`` comment is sent every 15 s to keep proxies alive. The stream closes after sending an ``ended`` event when the call completes (or immediately after replay if the call has already ended). Works for both live and completed calls — same URL either way.

List all calls for a specific phone number.

Get usage statistics for the current account. Returns: - Phone number limits (used/limit/remaining) - Message statistics (total, last 24h, last 7 days, last 30 days) - Call statistics (total, last 24h, last 7 days, last 30 days) - Webhook delivery statistics

Get daily usage breakdown for the last N days (up to 365). Returns per-day counts of messages, calls, and webhook deliveries.

Get monthly usage aggregation for the last N months. Returns per-month totals of messages, calls, and webhook deliveries.

Get usage statistics broken down by phone number, with linked agent info.

Get usage broken down by agent for the current calendar week, month, or year. Includes message count, completed call count, and total call seconds per agent. Calls/messages with no agent attached are bucketed as "Unassigned".

Exchange a one-time connect code and redirect to Supabase OAuth.

Create a short-lived one-time code for initiating the Supabase OAuth flow.

Get a valid Supabase access token, auto-refreshing if expired.

Complete Embedded Signup: exchange the code, store the connection, and onboard the phone number (register + subscribe webhooks).

List the WABA's phone numbers with their connected state, for the add-number picker. Registration is deliberate and per-number: registering a number on the Cloud API kicks it off the WhatsApp Business app, so we never auto-register a whole WABA.

Connect an additional number from an already-connected WABA: validates the number belongs to the WABA, registers it for Cloud API use, and binds it (dual-channel when the E.164 already exists on this account).

List the WABA's message templates and their approval status. Templates are the only way to message someone outside the 24h customer service window. A newly created one is PENDING until Meta reviews it; poll here for the transition to APPROVED (or REJECTED, with a reason).

Submit a template, authored or from Meta's Template Library. An authored template (with `components`) comes back PENDING and can't be sent until it reaches APPROVED — UTILITY usually clears in minutes, MARKETING can take up to 24h. Passing `library_template_name` instead builds from Meta's library, where a template used unchanged skips review and is usable straight away. That makes it the quickest way to get something sendable; the trade is that the copy is Meta's, customizable only through the library button/body inputs.

Delete a template by name. Meta removes EVERY language variant registered under the name, and blocks reuse of that name for 30 days. There is no rename on Meta's side, so this is also the only way to reclaim a name from a typo'd or rejected template.

Disconnect a WABA: mark the connection disconnected and release its numbers. The customer keeps all their Meta assets (we never delete anything on their side); this only stops AgentPhone from using them.

Send an outbound message (SMS or iMessage) via the provider assigned to the number.

Send a tapback reaction to a message (iMessage only). Reactions are available only for iMessage messages. Attempting to react to an SMS message or another channel that does not support tapbacks returns a clear error.

Fetch the iMessage contact card set on this number.

Create or replace the iMessage contact card on this number.

Remove the iMessage contact card from this number.

Check the status of your A2P 10DLC registration. Registrations created with create_sub_account=true (the default) live on a sub-account; this resolves to it automatically when there's exactly one, or honors the X-Sub-Account-Id header.

Retrieve the content of your submitted A2P 10DLC registration. Returns the brand identity and campaign content exactly as it was submitted (business info, description, use case, sample messages, opt-in consent flow, opt-in screenshot URL) so you can review what carriers are reviewing. Internal registry ids, vendor names, and processing state are never exposed; the coarse `stage` mirrors GET /v1/register/status. The EIN is returned as its last 4 digits only. Like the status endpoint, this resolves to a sub-account when the registration lives on one (the default for POST /v1/register) — either automatically when there's exactly one, or via the X-Sub-Account-Id header.

Submit A2P 10DLC registration. Deducts the registration fee ($25 for sole_proprietor / standard_brand, $70 for high_volume) from the parent account's credit balance, creates an optional sub-account, and sends a notification email.

Update an existing A2P 10DLC registration. Send only the fields that changed — everything is optional. There is no fee. Changes are applied after review, and your registration keeps sending under its current approval while an update to an approved registration is reviewed. Registrations created with create_sub_account=true (the default) live on a sub-account; this resolves to it automatically when there's exactly one, or honors the X-Sub-Account-Id header.

Send a 6-digit verification code to a phone number via SMS. Use this instead of sending your own code over `POST /v1/messages`: it routes through carrier-registered sender IDs, so it reaches countries where plain application SMS from a US long code is not deliverable (e.g. Greece, UAE, the Philippines, the UK). The code is always 6 digits, expires after 10 minutes, and allows up to 3 check attempts. None of these are configurable. **Billing.** Sending a code costs the standard outbound SMS rate for the destination country. A successful `POST /v1/verify/check` adds a $0.05 verification fee; failed, expired, and exhausted checks are not charged. **Destination coverage.** A small number of countries are unavailable and return 400. Email founders@agentphone.to if you need access to one.

Check a verification code against a pending verification. Possible results: - `ok` — code is correct, phone number verified - `incorrect` — wrong code, try again (up to 3 attempts) - `exhausted` — too many failed attempts, send a new code - `expired` — verification expired (10 min), send a new code - `already_verified` — this verification was already completed **Billing.** An `ok` or `already_verified` result costs a $0.05 verification fee. Other results are free.

Report an API issue or documentation mismatch, including the request id of the call it is about when you have one. Returns `201` when the feedback is stored, or `200` with `already_submitted: true` when feedback for the same `request_id` was already recorded on this account.