Phone

Each agent identity can have one phone number. Agents can place outbound calls, receive inbound calls, and handle audio in real time. Inkbox Voice AI calls are automatically transcribed. For calls handled through your own WebSocket, Inkbox captures transcripts when it handles speech processing; otherwise, your agent supplies them. Forwarded calls have forwarding history on the call record instead of transcripts.

Connecting your agent

New identities use Inkbox Voice AI (beta) to answer incoming calls by default. It requires no WebSocket server or code. You can also handle calls with your own agent. Inkbox connects to your client_websocket_url when a call starts and disconnects when it ends. Configure this URL for incoming calls or provide it when placing an outbound call. The rest of this section describes that setup.

Speech and text

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.

Inbound call routing

For inbound calls, you configure how Inkbox should handle them on the agent identity. The action applies to every dedicated phone or iMessage line routed to that identity:

auto_reject — Inkbox rejects the call immediately. Set this explicitly if you do not want incoming calls answered.
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. This is the default and requires no URL.
forward — Inkbox sends the call to one E.164 phone number or complete SIP URI. No media WebSocket is required. See Incoming calls.

Forwarding applies to every inbound phone or iMessage line routed to the agent identity. Call history shows the destination and whether the forwarding attempt is still dialing, succeeded, or failed. The ordinary call status remains separate and continues through answered and completed.

Placing a call

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

call = identity.place_call(
    to_number="+15551234567",
    client_websocket_url="wss://your-agent.example.com/ws",
)
print(call.status, call.rate_limit.calls_remaining)

const call = await identity.placeCall({
  toNumber: "+15551234567",
  clientWebsocketUrl: "wss://your-agent.example.com/ws",
});
console.log(call.status, call.rateLimit.callsRemaining);

inkbox phone call -i my-agent \
--to +15551234567 \
--ws-url wss://your-agent.example.com/ws

Inkbox Voice AI

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.

call = identity.place_call(
    to_number="+15551234567",
    mode="hosted_agent",
    reason="Call the dental office and book a cleaning next week, mornings preferred.",
)

const call = await identity.placeCall({
  toNumber: "+15551234567",
  mode: "hosted_agent",
  reason: "Call the dental office and book a cleaning next week, mornings preferred.",
});

inkbox phone call -i my-agent \
--to +15551234567 \
--hosted \
--reason "Call the dental office and book a cleaning next week, mornings preferred."

Hanging up a call

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.

call = identity.hangup_call(call_id)
print(call.status, call.hangup_reason)  # "local" — or "remote" if the call ended on its own first

const call = await identity.hangupCall(callId);
console.log(call.status, call.hangupReason);  // "local" — or "remote" if the call ended on its own first

inkbox phone hangup CALL_ID -i my-agent

iMessage voice calls

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.

call = identity.place_call(
    to_number="+15551234567",
    origination="shared_imessage_number",
)
print(call.origin, call.local_phone_number)  # local_phone_number is None

import { CallOrigin } from "@inkbox/sdk"

const call = await identity.placeCall({
  toNumber: "+15551234567",
  origination: CallOrigin.SHARED_IMESSAGE_NUMBER,
})
console.log(call.origin, call.localPhoneNumber)  // localPhoneNumber is null

Reading transcripts

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.

# List recent calls
calls = identity.list_calls(limit=10, offset=0)
for call in calls:
    print(call.id, call.direction, call.remote_phone_number, call.status)

# Fetch transcript for a specific call
segments = identity.list_transcripts(calls[0].id)
for t in segments:
    print(f"[{t.party}] {t.text}")  # party: "local" (your agent) or "remote" (caller)

# Filter to only what the other person said
for t in identity.list_transcripts(calls[0].id):
    if t.party == "remote":
        print(t.text)

// List recent calls
const calls = await identity.listCalls({ limit: 10, offset: 0 });
for (const c of calls) {
  console.log(c.id, c.direction, c.remotePhoneNumber, c.status);
}

// Fetch transcript for a specific call
const segments = await identity.listTranscripts(calls[0].id);
for (const t of segments) {
  console.log(`[${t.party}] ${t.text}`);  // party: "local" (your agent) or "remote" (caller)
}

// Filter to only what the other person said
const remoteOnly = segments.filter(t => t.party === "remote");
for (const t of remoteOnly) console.log(t.text);

# List recent calls
inkbox phone calls -i my-agent --limit 10

# Fetch transcript for a specific call
inkbox phone transcripts call_abc123 -i my-agent

# Search transcripts for keywords
inkbox phone search-transcripts -i my-agent -q "refund" --party remote

Reading across calls

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

for call in identity.list_calls(limit=10):
    segments = identity.list_transcripts(call.id)
    if not segments:
        continue
    print(f"\n--- Call {call.id} ({call.direction}) ---")
    for t in segments:
        print(f"  [{t.party:6}] {t.text}")

const recentCalls = await identity.listCalls({ limit: 10 });
for (const call of recentCalls) {
  const segs = await identity.listTranscripts(call.id);
  if (!segs.length) continue;
  console.log(`\n--- Call ${call.id} (${call.direction}) ---`);
  for (const t of segs) {
      console.log(`  [${t.party.padEnd(6)}] ${t.text}`);
  }
}

# List recent calls and fetch transcripts for each
inkbox phone calls -i my-agent --limit 10
inkbox phone transcripts call_abc123 -i my-agent

Post-call handover

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.

Text messages (SMS/MMS)

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.

# Send a 1:1 text
sent = identity.send_text(to="+15551234567", text="Your order has shipped.")
print(sent.id, sent.delivery_status, sent.conversation_id)

# Send beta group MMS with optional media
group = identity.send_text(
    to=["+15551234567", "+12125550199"],
    text="The appointment moved to 3:30.",
    media_urls=["https://example.com/updated-calendar.png"],
)
print(group.conversation_id)
for r in group.recipients or []:
    print(r.recipient_phone_number, r.delivery_status)

# Reply to an existing conversation by UUID
reply = identity.send_text(
    conversation_id=group.conversation_id,
    text="Following up in the same conversation.",
)

# List text messages
texts = identity.list_texts(limit=20, offset=0)
for t in texts:
    print(t.id, t.direction, t.conversation_id, t.remote_phone_number, t.text)

# Filter to unread only
unread = identity.list_texts(is_read=False)

# Get a single text message
text = identity.get_text("text-uuid")
print(text.type)   # "sms" or "mms"
if text.media:     # MMS media attachments
    for m in text.media:
        print(m.content_type, m.size, m.url)

# List conversation summaries, including group conversations
convos = identity.list_text_conversations(limit=20, include_groups=True)
for c in convos:
    print(c.id, c.participants, c.is_group, c.latest_has_media, c.latest_text)

# Get messages in a 1:1 conversation by remote number
msgs = identity.get_text_conversation("+15551234567", limit=50)

# Get messages in a group conversation by UUID
group_msgs = identity.get_text_conversation(group.conversation_id, limit=50)

# Mark a text as read
identity.mark_text_read("text-uuid")

# Mark all messages in a conversation as read
result = identity.mark_text_conversation_read("+15551234567")
print(result["updated_count"])

# Group conversations are marked by UUID
identity.mark_text_conversation_read(group.conversation_id)

# Org-level: search
results = inkbox.texts.search(identity.phone_number.id, q="invoice", limit=20)

// Send a 1:1 text
const sent = await identity.sendText({ to: "+15551234567", text: "Your order has shipped." });
console.log(sent.id, sent.deliveryStatus, sent.conversationId);

// Send beta group MMS with optional media
const group = await identity.sendText({
  to: ["+15551234567", "+12125550199"],
  text: "The appointment moved to 3:30.",
  mediaUrls: ["https://example.com/updated-calendar.png"],
});
console.log(group.conversationId);
for (const r of group.recipients ?? []) {
  console.log(r.recipientPhoneNumber, r.deliveryStatus);
}

// Reply to an existing conversation by UUID
const reply = await identity.sendText({
  conversationId: group.conversationId,
  text: "Following up in the same conversation.",
});

// List text messages
const texts = await identity.listTexts({ limit: 20, offset: 0 });
for (const t of texts) {
  console.log(t.id, t.direction, t.conversationId, t.remotePhoneNumber, t.text);
}

// Filter to unread only
const unread = await identity.listTexts({ isRead: false });

// Get a single text message
const fetched = await identity.getText("text-uuid");
console.log(fetched.type);   // "sms" or "mms"
if (fetched.media) {          // MMS media attachments
  for (const m of fetched.media) {
      console.log(m.contentType, m.size, m.url);
  }
}

// List conversation summaries, including group conversations
const convos = await identity.listTextConversations({ limit: 20, includeGroups: true });
for (const c of convos) {
  console.log(c.id, c.participants, c.isGroup, c.latestHasMedia, c.latestText);
}

// Get messages in a 1:1 conversation by remote number
const msgs = await identity.getTextConversation("+15551234567", { limit: 50 });

// Get messages in a group conversation by UUID
const groupMsgs = await identity.getTextConversation(group.conversationId!, { limit: 50 });

// Mark a text as read
await identity.markTextRead("text-uuid");

// Mark all messages in a conversation as read
const result = await identity.markTextConversationRead("+15551234567");
console.log(result.updatedCount);

// Group conversations are marked by UUID
await identity.markTextConversationRead(group.conversationId!);

// Org-level: search
const results = await inkbox.texts.search(identity.phoneNumber!.id, { q: "invoice", limit: 20 });

# Send a 1:1 text
inkbox text send -i my-agent --to +15551234567 --text "Your order has shipped."

# Send beta group MMS with optional media
inkbox text send -i my-agent \
--to +15551234567,+12125550199 \
--text "The appointment moved to 3:30." \
--media-url https://example.com/updated-calendar.png

# Reply to an existing conversation by UUID
inkbox text send -i my-agent \
--conversation-id e0bc45d2-7478-4b3b-9b7c-cfc73f1ba201 \
--text "Following up in the same conversation."

# List text messages
inkbox text list -i my-agent --limit 20

# Get a single text message
inkbox text get text-uuid -i my-agent

# List conversation summaries, including group conversations
inkbox text conversations -i my-agent --include-groups

# Get messages in a 1:1 conversation
inkbox text conversation +15551234567 -i my-agent

# Get messages in a group conversation
inkbox text conversation e0bc45d2-7478-4b3b-9b7c-cfc73f1ba201 -i my-agent

# Search texts
inkbox text search -i my-agent -q "invoice"

# Mark a text as read
inkbox text mark-read text-uuid -i my-agent

# Mark all messages in a conversation as read
inkbox text mark-conversation-read +15551234567 -i my-agent

# Mark all messages in a group conversation as read
inkbox text mark-conversation-read e0bc45d2-7478-4b3b-9b7c-cfc73f1ba201 -i my-agent

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.

from inkbox import SmsOptInStatus

# List the org's consent rows (newest-updated first)
rows = inkbox.sms_opt_ins.list(limit=50)
for r in rows:
    print(r.receiver_number, r.status, r.source)

# Filter to opted-out only
opted_out = inkbox.sms_opt_ins.list(status=SmsOptInStatus.OPTED_OUT)

# Look up one recipient — 404 if no row exists
row = inkbox.sms_opt_ins.get("+15551234567")
print(row.status, row.opted_in_at, row.opted_out_at)

# Record consent captured outside of STOP/START (your own channel)
inkbox.sms_opt_ins.opt_in("+15551234567")

# Honor an opt-out collected outside of inbound STOP
inkbox.sms_opt_ins.opt_out("+15551234567")

import { SmsOptInStatus } from "@inkbox/sdk";

// List the org's consent rows (newest-updated first)
const rows = await inkbox.smsOptIns.list({ limit: 50 });
for (const r of rows) {
  console.log(r.receiverNumber, r.status, r.source);
}

// Filter to opted-out only
const optedOut = await inkbox.smsOptIns.list({ status: SmsOptInStatus.OPTED_OUT });

// Look up one recipient — 404 if no row exists
const row = await inkbox.smsOptIns.get("+15551234567");
console.log(row.status, row.optedInAt, row.optedOutAt);

// Record consent captured outside of STOP/START (your own channel)
await inkbox.smsOptIns.optIn("+15551234567");

// Honor an opt-out collected outside of inbound STOP
await inkbox.smsOptIns.optOut("+15551234567");

# List the org's consent rows
inkbox sms-opt-in list --limit 50

# Filter to opted-out only
inkbox sms-opt-in list --status opted_out

# Look up one recipient — 404 if no row exists
inkbox sms-opt-in get +15551234567

# Record consent captured outside of STOP/START (your own channel)
inkbox sms-opt-in opt-in +15551234567

# Honor an opt-out collected outside of inbound STOP
inkbox sms-opt-in opt-out +15551234567

Filtering inbound calls and texts

Control incoming and outgoing SMS, calls, and iMessage with a shared mode, whitelist or blacklist, and a list of contact rules. Both belong to the agent identity. Each identity has a phone_filter_mode field with two values:

blacklist (default). Incoming and outgoing communication is permitted unless a block entry matches the number.
whitelist. Incoming and outgoing communication is permitted only when an allow entry matches the number.

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 also govern iMessage. You can configure them before assigning a dedicated phone number. Rule mutations require admin credentials or the Inkbox Console; releasing a number leaves the identity’s permissions intact. The following write examples use an admin API key. See contact communication permissions. 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.

# Switch an identity to whitelist mode using an admin API key
inkbox.get_identity("my-agent").update(phone_filter_mode="whitelist")

# Back to blacklist (the default)
inkbox.get_identity("my-agent").update(phone_filter_mode="blacklist")

# Block an individual caller or sender
inkbox.phone_identity_contact_rules.create(
    "my-agent",
    action="block",
    match_target="+14155550100",
)

# In whitelist mode: allow a trusted contact
inkbox.phone_identity_contact_rules.create(
    "my-agent",
    action="allow",
    match_target="+14445556789",
)

# Change a rule's action
inkbox.phone_identity_contact_rules.update(
    "my-agent", rule_id, action="block",
)

# Rules on one identity
phone_rules = inkbox.phone_identity_contact_rules.list("my-agent")

# Org-wide rules (admin-only) — handy for compliance reviews
all_phone = inkbox.phone_identity_contact_rules.list_all(action="block")

// Switch an identity to whitelist mode using an admin API key
await (await inkbox.getIdentity("my-agent")).update({ phoneFilterMode: "whitelist" });

// Back to blacklist (the default)
await (await inkbox.getIdentity("my-agent")).update({ phoneFilterMode: "blacklist" });

// Block an individual caller or sender
await inkbox.phoneIdentityContactRules.create("my-agent", {
  action: "block",
  matchTarget: "+14155550100",
});

// In whitelist mode: allow a trusted contact
await inkbox.phoneIdentityContactRules.create("my-agent", {
  action: "allow",
  matchTarget: "+14445556789",
});

// Change a rule's action
await inkbox.phoneIdentityContactRules.update("my-agent", ruleId, { action: "block" });

// Rules on one identity
const phoneRules = await inkbox.phoneIdentityContactRules.list("my-agent");

// Org-wide rules (admin-only) — handy for compliance reviews
const allPhone = await inkbox.phoneIdentityContactRules.listAll({ action: "block" });

# Switch an identity to whitelist mode
inkbox identity update my-agent --phone-filter-mode whitelist

# Block a caller or sender
inkbox identity phone-rules create my-agent \
--action block --match-target +14155550100

# Allow a caller (useful in whitelist mode)
inkbox identity phone-rules create my-agent \
--action allow --match-target +14445556789

# List rules on one identity
inkbox identity phone-rules list my-agent

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.

# Use an admin API key to review blocked calls and texts.
blocked_calls = inkbox.calls.list(agent_identity_id=identity.id, is_blocked=True)
blocked_texts = inkbox.texts.list(phone_number.id, is_blocked=True)

# Conversation summaries with blocked-only counterparties hidden,
# and previews/ordering computed from non-blocked rows only
clean_convos = inkbox.texts.list_conversations(phone_number.id, is_blocked=False)

# Search the blocked folder
spam_hits = inkbox.texts.search(phone_number.id, q="crypto", is_blocked=True)

# Each row carries is_blocked so the UI can tag it
for t in inkbox.texts.list(phone_number.id):
    print(t.remote_phone_number, t.text, "BLOCKED" if t.is_blocked else "")

// Use an admin API key to review blocked calls and texts.
const blockedCalls = await inkbox.calls.list({
  agentIdentityId: identity.id,
  isBlocked: true,
});
const blockedTexts = await inkbox.texts.list(phoneNumber.id, { isBlocked: true });

// Conversation summaries with blocked-only counterparties hidden,
// and previews/ordering computed from non-blocked rows only
const cleanConvos = await inkbox.texts.listConversations(phoneNumber.id, {
      isBlocked: false,
});

// Search the blocked folder
const spamHits = await inkbox.texts.search(phoneNumber.id, {
      q: "crypto",
      isBlocked: true,
});

// Each row carries isBlocked so the UI can tag it
const texts = await inkbox.texts.list(phoneNumber.id);
for (const t of texts) {
      console.log(t.remotePhoneNumber, t.text, t.isBlocked ? "BLOCKED" : "");
}

Org-level phone numbers

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.

# List all phone numbers in the organisation
numbers = inkbox.phone_numbers.list()

# Get a specific phone number by ID
number = inkbox.phone_numbers.get("phone-number-uuid")

# Provision a new number (optionally request a specific US state)
number = inkbox.phone_numbers.provision(agent_handle="my-agent")
ny_number = inkbox.phone_numbers.provision(agent_handle="my-agent", state="NY")

# Configure how inbound calls are routed
inkbox.phone_numbers.update(
    number.id,
    incoming_call_action="webhook",
    incoming_call_webhook_url="https://example.com/calls",
)
# Or auto-accept and stream audio to your agent
inkbox.phone_numbers.update(
    number.id,
    incoming_call_action="auto_accept",
    client_websocket_url="wss://example.com/ws",
)
# Or forward every inbound call for the identity to a complete SIP URI
inkbox.phone_numbers.update(
    number.id,
    incoming_call_action="forward",
    forwarding_target_type="sip",
    forwarding_sip_uri="sip:+14155550100@voice.example.com",
)

# Full-text search across all transcripts on a number
hits = inkbox.phone_numbers.search_transcripts(number.id, q="refund", party="remote")
for t in hits:
    print(f"[{t.party}] {t.text}")

# Release a number when it's no longer needed
inkbox.phone_numbers.release(number.id)

import { ForwardingTargetType } from "@inkbox/sdk";

// List all phone numbers in the organisation
const numbers = await inkbox.phoneNumbers.list();

// Get a specific phone number by ID
const number = await inkbox.phoneNumbers.get("phone-number-uuid");

// Provision a new number (optionally request a specific US state)
const num = await inkbox.phoneNumbers.provision({ agentHandle: "my-agent" });
const nyNum = await inkbox.phoneNumbers.provision({ agentHandle: "my-agent", state: "NY" });

// Configure how inbound calls are routed
await inkbox.phoneNumbers.update(num.id, {
  incomingCallAction: "webhook",
  incomingCallWebhookUrl: "https://example.com/calls",
});
// Or auto-accept and stream audio to your agent
await inkbox.phoneNumbers.update(num.id, {
  incomingCallAction: "auto_accept",
  clientWebsocketUrl: "wss://example.com/ws",
});
// Or forward every inbound call for the identity to a complete SIP URI
await inkbox.phoneNumbers.update(num.id, {
  incomingCallAction: "forward",
  forwardingTargetType: ForwardingTargetType.SIP,
  forwardingSipUri: "sip:+14155550100@voice.example.com",
});

// Full-text search across all transcripts on a number
const hits = await inkbox.phoneNumbers.searchTranscripts(num.id, { q: "refund", party: "remote" });
for (const t of hits) {
  console.log(`[${t.party}] ${t.text}`);
}

// Release a number when it's no longer needed
await inkbox.phoneNumbers.release(num.id);

# List all phone numbers in the organisation
inkbox number list

# Get a specific phone number by ID
inkbox number get phone-number-uuid

# Provision a new number (optionally request a specific US state)
inkbox number provision --handle my-agent
inkbox number provision --handle my-agent --state NY

# Configure how inbound calls are routed
inkbox number update phone-number-uuid \
--incoming-call-action webhook \
--incoming-call-webhook-url "https://example.com/calls"
# Or auto-accept and stream audio to your agent
inkbox number update phone-number-uuid \
--incoming-call-action auto_accept \
--client-websocket-url "wss://example.com/ws"
# Or forward every inbound call for the identity to a complete SIP URI
inkbox number update phone-number-uuid \
--incoming-call-action forward \
--forward-to-sip "sip:+14155550100@voice.example.com"

# Search transcripts is available via the identity
inkbox phone search-transcripts -i my-agent -q "refund" --party remote

# Release a number when it's no longer needed
inkbox number release phone-number-uuid

Get started

Capabilities

API keys

MCP

Webhooks

Signing keys

Skills

Integrations

Connecting your agent

Speech and text

Inbound call routing

Placing a call

Inkbox Voice AI

Hanging up a call

iMessage voice calls

Reading transcripts

Reading across calls

Post-call handover

Text messages (SMS/MMS)

SMS opt-ins

Filtering inbound calls and texts

Reviewing blocked calls and texts

Org-level phone numbers

​Connecting your agent

​Speech and text

​Inbound call routing

​Placing a call

​Inkbox Voice AI

​Hanging up a call

​iMessage voice calls

​Reading transcripts

​Reading across calls

​Post-call handover

​Text messages (SMS/MMS)

​SMS opt-ins

​Filtering inbound calls and texts

​Reviewing blocked calls and texts

​Org-level phone numbers

Connecting your agent

Speech and text

Inbound call routing

Placing a call

Inkbox Voice AI

Hanging up a call

iMessage voice calls

Reading transcripts

Reading across calls

Post-call handover

Text messages (SMS/MMS)

SMS opt-ins

Filtering inbound calls and texts

Reviewing blocked calls and texts

Org-level phone numbers