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.

For every call — inbound or outbound — Inkbox opens a WebSocket connection to a URL you provide (client_websocket_url). Your agent is the server; Inkbox connects when the call starts and disconnects when it ends.

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.

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

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.

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.

Outbound messaging is supported from local numbers only today; toll-free numbers are receive-only. 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 from reaching your agents' numbers. Inkbox combines a mode — whitelist or blacklist — with a list of contact rules to decide whether inbound calls and texts are delivered.

Every phone number has a filter_mode field with two values:

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

Phone rules match on exact_number — an E.164 phone number. Rules carry an action (allow or block) and a status (active or paused) — paused rules reserve the target slot without taking effect, which is useful for staging policy changes.

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.