# 1. List conversations
curl -X GET "https://api.wirebox.sh/api/v1/imessage/conversations?status=active" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
# 2. Disconnect a conversation
curl -X POST "https://api.wirebox.sh/api/v1/imessage/conversations/conv_01J8ABC123XYZ/disconnect" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
from wirebox import Wirebox
with Wirebox() as wb:
# List active conversations
res = wb.imessage.conversations.list(status="active", limit=10)
for c in res.conversations:
print(f"[{c.id}] @{c.agent_handle} <-> {c.participant_id}")
# Disconnect session
wb.imessage.conversations.disconnect("conv_01J8ABC123XYZ")
import { Wirebox } from "@wirebox-sh/sdk";
const wb = new Wirebox();
// List active conversations
const res = await wb.imessage.conversations.list({ status: "active", limit: 10 });
for (const c of res.conversations) {
console.log(`[${c.id}] @${c.agent_handle} <-> ${c.participant_id}`);
}
// Disconnect session
await wb.imessage.conversations.disconnect("conv_01J8ABC123XYZ");
# List conversations
wirebox imessage conversations --status active
# Disconnect conversation
wirebox imessage disconnect conv_01J8ABC123XYZ
{
"conversations": [
{
"id": "conv_01J8ABC123XYZ",
"agent_handle": "eva",
"participant_id": "+15551234567",
"status": "active",
"last_message_at": "2026-09-17T10:15:30Z",
"created_at": "2026-09-17T09:00:00Z"
}
],
"next_cursor": null
}
iMessage
Conversations
List stateful iMessage conversation sessions, inspect active participants, and disconnect sessions.
GET
/
api
/
v1
/
imessage
/
conversations
# 1. List conversations
curl -X GET "https://api.wirebox.sh/api/v1/imessage/conversations?status=active" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
# 2. Disconnect a conversation
curl -X POST "https://api.wirebox.sh/api/v1/imessage/conversations/conv_01J8ABC123XYZ/disconnect" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
from wirebox import Wirebox
with Wirebox() as wb:
# List active conversations
res = wb.imessage.conversations.list(status="active", limit=10)
for c in res.conversations:
print(f"[{c.id}] @{c.agent_handle} <-> {c.participant_id}")
# Disconnect session
wb.imessage.conversations.disconnect("conv_01J8ABC123XYZ")
import { Wirebox } from "@wirebox-sh/sdk";
const wb = new Wirebox();
// List active conversations
const res = await wb.imessage.conversations.list({ status: "active", limit: 10 });
for (const c of res.conversations) {
console.log(`[${c.id}] @${c.agent_handle} <-> ${c.participant_id}`);
}
// Disconnect session
await wb.imessage.conversations.disconnect("conv_01J8ABC123XYZ");
# List conversations
wirebox imessage conversations --status active
# Disconnect conversation
wirebox imessage disconnect conv_01J8ABC123XYZ
{
"conversations": [
{
"id": "conv_01J8ABC123XYZ",
"agent_handle": "eva",
"participant_id": "+15551234567",
"status": "active",
"last_message_at": "2026-09-17T10:15:30Z",
"created_at": "2026-09-17T09:00:00Z"
}
],
"next_cursor": null
}
An iMessage conversation represents a stateful session between an external phone number / Apple ID and an agent identity.
Query Parameters
string
Filter conversations by specific agent identity ID or handle.
string
Filter conversations by status:
active, disconnected, or expired.integer
default:"50"
Maximum number of conversations to return (1–100).
string
Opaque cursor for pagination.
Response Fields
array
List of iMessage conversation objects.
Show Conversation Properties
Show Conversation Properties
string
Unique identifier of the conversation (e.g.
conv_01J8ABC123XYZ).string
Handle of the paired agent identity (e.g.
eva).string
E.164 phone number or Apple ID of the user (e.g.
+15551234567).string
Current status:
active, disconnected, or expired.string
ISO 8601 timestamp of the latest message in this conversation.
string
ISO 8601 creation timestamp.
string
Cursor for retrieving the next page of results, or
null if at the end.Disconnecting a Conversation
To explicitly terminate an active conversation session and end routing to the agent:POST https://api.wirebox.sh/api/v1/imessage/conversations/{id}/disconnect
# 1. List conversations
curl -X GET "https://api.wirebox.sh/api/v1/imessage/conversations?status=active" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
# 2. Disconnect a conversation
curl -X POST "https://api.wirebox.sh/api/v1/imessage/conversations/conv_01J8ABC123XYZ/disconnect" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
from wirebox import Wirebox
with Wirebox() as wb:
# List active conversations
res = wb.imessage.conversations.list(status="active", limit=10)
for c in res.conversations:
print(f"[{c.id}] @{c.agent_handle} <-> {c.participant_id}")
# Disconnect session
wb.imessage.conversations.disconnect("conv_01J8ABC123XYZ")
import { Wirebox } from "@wirebox-sh/sdk";
const wb = new Wirebox();
// List active conversations
const res = await wb.imessage.conversations.list({ status: "active", limit: 10 });
for (const c of res.conversations) {
console.log(`[${c.id}] @${c.agent_handle} <-> ${c.participant_id}`);
}
// Disconnect session
await wb.imessage.conversations.disconnect("conv_01J8ABC123XYZ");
# List conversations
wirebox imessage conversations --status active
# Disconnect conversation
wirebox imessage disconnect conv_01J8ABC123XYZ
{
"conversations": [
{
"id": "conv_01J8ABC123XYZ",
"agent_handle": "eva",
"participant_id": "+15551234567",
"status": "active",
"last_message_at": "2026-09-17T10:15:30Z",
"created_at": "2026-09-17T09:00:00Z"
}
],
"next_cursor": null
}