Phone

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.

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.