Phone calls, texts, and numbers

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

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."

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

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

# Dedicated iMessage line
call = identity.place_call(
    to_number="+15551234567",
    origination="dedicated_imessage_number",
)
print(call.origin, call.local_phone_number)  # the dedicated iMessage line

import { CallOrigin } from "@inkbox/sdk"

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

// Dedicated iMessage line
const dedicatedCall = await identity.placeCall({
  toNumber: "+15551234567",
  origination: CallOrigin.DEDICATED_IMESSAGE_NUMBER,
})
console.log(dedicatedCall.origin, dedicatedCall.localPhoneNumber)

# 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.phone_number or 'unknown line'}] {t.text}")

# Keep remote turns, including any conference guest
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.phoneNumber ?? "unknown line"}] ${t.text}`);
}

// Keep remote turns, including any conference guest
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

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

# 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

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

# 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

identity = inkbox.get_identity("my-agent")
identity.update(
    phone_inbound_filter_mode="blacklist",
    phone_outbound_filter_mode="whitelist",
)
rule = inkbox.phone_identity_contact_rules.create(
    "my-agent", action="allow", match_target="+15555550123", direction="outbound",
)

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

const identity = await inkbox.getIdentity("my-agent");
await identity.update({
  phoneInboundFilterMode: "blacklist", phoneOutboundFilterMode: "whitelist",
});
const rule = await inkbox.phoneIdentityContactRules.create("my-agent", {
  action: PhoneRuleAction.ALLOW, matchTarget: "+15555550123", direction: "outbound",
});

inkbox identity update my-agent \
  --phone-inbound-filter-mode blacklist --phone-outbound-filter-mode whitelist
inkbox identity phone-rules create my-agent \
  --action allow --match-target +15555550123 --direction outbound

# 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" : "");
}

# 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