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"|"ignore"}. 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 and MMS text messages on their phone numbers, group conversations by remote number, and mark messages as read. Inbound MMS includes media attachments returned as presigned URLs (1-hour expiry).

Outbound SMS is text-only and is supported from local numbers only today (toll-free is receive-only). Numbers on Inkbox's default 10DLC campaign are capped at 20 outbound texts per rolling 24-hour window; register your own 10DLC brand and campaign to lift the cap. Every send returns the rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset), with Retry-After added on 429. A newly provisioned local number takes around 10–15 minutes for its 10DLC campaign to propagate — 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.

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, paused, or deleted) — 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.

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.