Each agent identity can have one phone number. Agents can place outbound calls, receive inbound calls, and handle audio in real time. Every call is automatically transcribed, giving your agent a searchable record of every conversation it has.

There are two ways to put a brain on a call. The default is to bring your own: Inkbox opens a WebSocket connection to a URL you provide (client_websocket_url) for every call — inbound or outbound. Your agent is the server; Inkbox connects when the call starts and disconnects when it ends.

The alternative is zero setup: let Inkbox Voice AI (beta) take or place the call for you — no WebSocket server, no code. The rest of this section describes the bring-your-own path.

By default, Inkbox handles both speech-to-text (STT) and text-to-speech (TTS) on your behalf. Your agent only deals with text — it receives transcribed caller speech as text and responds with text that Inkbox speaks aloud.

If you want to handle audio directly, you can opt out of either or both by setting X-Use-Inkbox-Speech-To-Text: false or X-Use-Inkbox-Text-To-Speech: false in your WebSocket handshake response. See Media Stream for the full protocol.

For inbound calls, you configure how Inkbox should handle them on the phone number:

• auto_reject — Inkbox rejects the call immediately. This is the default when no action is configured.
• auto_accept — Inkbox answers automatically and connects to your client_websocket_url immediately.
• webhook — Inkbox POSTs the incoming call to your incoming_call_webhook_url first. Your endpoint responds with {"action": "answer"|"reject"}. If answering, include a client_websocket_url in the response and Inkbox will connect to it.
• hosted_agent — Inkbox Voice AI answers. The only answering action that requires no URL at all.

Pass client_websocket_url to stream audio to your agent. The returned call object includes status and rate limit information.

To hand a call to Inkbox instead of running your own WebSocket server, place it with mode="hosted_agent" and a plain-language reason. Inkbox Voice AI works the errand, records action items, and delivers the whole package — transcript, outcome, and action items — on the call.ended webhook. See the Inkbox Voice AI guide for everything it knows and can do.

The agent on a call ends it in-band over the media WebSocket. To end a call from anywhere else — a supervisor process, a test harness, operator tooling — hang it up by ID. This works identically on Inkbox Voice AI calls, where it's the operator kill switch. The carrier confirms the teardown asynchronously, so the returned call may still show its live status for a moment; a call that has already ended answers with a 409.

An agent can place and receive voice calls over its shared iMessage line, in addition to any dedicated number it holds. The agent is blind to which underlying line is used — it never chooses or sees it. The shared line is resolved automatically from the identity's active iMessage assignment to the recipient, and because it is never surfaced, the returned call's local_phone_number is null (and origin is "shared_imessage_number").

To place a call over the shared line, pass origination="shared_imessage_number" and omit from_number. Inbound shared-line calls are governed by the identity's incoming-call configuration.

After a call ends, fetch its transcript to log, summarize, or analyze what was said. Each segment has a party field — "local" is your agent, "remote" is the other person.

To review an agent's recent call history — for example, to build a summary or audit log — iterate calls and fetch their transcripts together.

Rather than polling for finished calls, you can subscribe an agent identity to the call.ended webhook and be handed each call as it wraps up. It's a fire-and-forget, replayable delivery — you get it even when you never held the live call WebSocket.

The payload carries the terminated call (status, duration_seconds, and the resolved contact / agent-identity matches). When the call has transcribed turns it also inlines an abridged transcript so a webhook consumer can act immediately; every payload includes a transcript_url pointing at GET /phone/calls/{id}/transcripts — the authoritative verbatim record, readable with an API key or from the Inkbox Console. For Inkbox Voice AI calls the same event also delivers the outcome and the action items the agent recorded. See Webhooks for the subscription and handler shapes.

Agents can send and receive SMS/MMS text messages on their phone numbers, including 1:1 conversations and beta group MMS conversations through the same API surface. Inbound MMS includes media attachments returned as presigned URLs with a 1-hour expiry.

Beta: Group MMS and conversation sends are beta. Some carriers may reject group chats or MMS from 10DLC numbers even when the sender is ready and recipients have opted in.

Numbers on Inkbox's default 10DLC campaign are capped at 100 recipient sends per rolling 24-hour window. A 3-recipient group message counts as 3 recipient sends. Register your own 10DLC brand and campaign to lift the cap. A newly provisioned local number takes around 10-15 minutes for its 10DLC campaign to propagate, and sends during that window return 409 sender_sms_pending. Recipients also have to opt in by texting START to any of your numbers before you can message them; see the Send text endpoint for the full opt-in / opt-out behavior.

SMS opt-ins

Inkbox tracks consent per-recipient under your org and updates the registry automatically when recipients text START / STOP. Reading the consent state is open to any admin caller, so you can audit who has opted in, build an "opted-out" view, or pre-check before sending.

Writing consent directly — when you captured it through your own channel (a signup form, an in-product flow, a paper waiver) — is restricted to organizations on their own active, customer-managed 10DLC campaign. Orgs on the Inkbox-default campaign share consent state with everyone else on that campaign, so writes from them return 409 customer_campaign_required. See the SMS opt-ins reference for the full schema and error shapes.

Keep unwanted callers and senders from reaching your agents. Inkbox combines a mode — whitelist or blacklist — set on the agent identity, with a list of contact rules scoped to that identity, to decide whether inbound calls and texts are delivered.

Each identity has a phone_filter_mode field with two values:

• blacklist (default). Everything is delivered unless a block rule matches the caller or sender.
• whitelist. Nothing is delivered unless an allow rule matches the caller or sender.

Phone rules match on exact_number — an E.164 phone number. Each rule has an action: allow or block.

phone_filter_mode and phone contact rules only apply to an identity that has a phone number. While the identity has no number, setting phone_filter_mode or creating a rule returns 422, and listing rules returns an empty list — assign a number first.

Most agents start in blacklist mode: accept everyone, add explicit blocks for individual bad actors. Switch to whitelist when you want the opposite — locked down by default, with a known allowlist.

Reviewing blocked calls and texts

When an inbound call or text matches a block rule (or default-blocks under whitelist mode), the row is still persisted with is_blocked=true for audit. Blocked calls are rejected before connecting, and blocked texts do not fire incoming text webhooks. Identity-scoped (agent) API keys never see those rows — the listings, conversation summaries, search results, and conversation threads return only non-blocked rows for them.

Admin-scoped API keys and users in the Inkbox Console see everything by default. Each row carries is_blocked so a UI can render a "Blocked" badge inline. To page through just the blocked rows — e.g. for an admin "Blocked" folder in your console — pass is_blocked=true to the listing endpoints. Pass is_blocked=false to keep an admin search or conversation summary clean of blocked spam.

Most call operations go through the identity, but managing the number resource itself — provisioning, configuring how inbound calls are routed, or searching transcripts across all calls on a number — happens through inkbox.phone_numbers. SMS/MMS event delivery is configured separately — see the Webhooks guide for attaching a subscription to a phone number.