Companion conversation state

GET /api/v1/identities/{agent_handle}/companion/conversations

Returns a bounded page of visible conversation scopes. See Companion mode for sponsorship semantics and version requirements. Admin-scoped API keys and human sessions can inspect scopes for an identity in their organization, including pending scopes. A claimed identity-scoped key sees only its own ordinarily visible or currently authorized scopes. Hidden pending conversations are not revealed to the agent. Unclaimed keys are not supported.

Query parameters

Parameter	Type	Default	Meaning
`channel`	string	All	`mail`, `phone`, or `imessage`. `phone` covers SMS/MMS, not voice calls.
`limit`	integer	`50`	Page size, `1` through `200`.
`offset`	integer	`0`	Offset, `0` through `10000`.

Response

The 200 response is { "items": [...], "total": 1 }. total counts the visible scopes matching the channel filter, not just this page.

Item field	Type	Meaning
`scope_id`	UUID	Conversation-and-cohort scope. Do not treat it as an access credential.
`conversation_id`	UUID	Canonical email thread, text conversation, or iMessage conversation ID.
`channel`	string	`mail`, `phone`, or `imessage`.
`status`	string	Scope state. Handle unfamiliar values without assuming permission.
`activation_id`	UUID or null	Activation reference, when present. Read its snapshot under current authorization.
`reply_ready`	boolean	Whether current Companion reply prerequisites pass. Not a guarantee of delivery.
`reasons`	string[]	Current reply-readiness reasons.

One email thread can have multiple scopes for different participant cohorts. Key state by scope_id, not just conversation_id. State and visibility can change between requests; neither a stored status nor an activation ID authorizes a future read or send.

Status values

Status	Meaning
`pending`	The scope has no ready activation yet. Do not initialize until a currently authorized snapshot is available.
`active`	The scope has an active sponsorship. Reply readiness is evaluated separately.
`suspended`	An administrator-visible scope currently cannot use its previous activation.
`revoked`	The scope’s sponsorship is no longer valid, including after disabling Companion mode.
`ordinary`	An agent can see the scope through ordinary permission, without current Companion access. Its agent-facing activation reference is null.

Administrators can see an activation reference on an unavailable scope; that does not make its history readable. Recheck the endpoint rather than relying on a cached state. An activation is bound to the sender whose qualifying message triggered it. Continued Companion access depends on that sender’s active exact inbound and outbound allows and verified group membership. Another eligible participant does not automatically take over an unavailable activation. Readiness or a new activation must not rebind an older queued reply. Reply reasons include companion_reply_unavailable, text_sending_unavailable, recipient_consent_required, and recipient_opted_out. Receiving permission and SMS consent are separate. A readable group can have reply_ready: false; activating it does not opt anyone in. See SMS opt-ins.

Examples

The SDK examples use an authenticated client.

page = client.companion.conversations("xyz", channel="mail", limit=50, offset=0)
for scope in page.items:
    print(scope.scope_id, scope.activation_id, scope.reply_ready, scope.reasons)

const page = await client.companion.conversations("xyz", {
  channel: "mail", limit: 50, offset: 0,
});
for (const scope of page.items) {
  console.log(scope.scopeId, scope.activationId, scope.replyReady, scope.reasons);
}

use inkbox::companion::{CompanionChannel, CompanionConversationOptions};
use inkbox::Inkbox;

fn states(client: &Inkbox) -> inkbox::Result<()> {
    let page = client.companion().conversations("xyz", &CompanionConversationOptions {
        channel: Some(CompanionChannel::Mail),
        limit: 50,
        offset: 0,
    })?;
    for scope in page.items {
        println!("{} {} {:?}", scope.scope_id, scope.reply_ready, scope.reasons);
    }
    Ok(())
}

inkbox identity companion conversations xyz --channel mail --limit 50 --offset 0 --json
inkbox identity companion state xyz --channel phone --json

state is a CLI alias for conversations. CLI JSON uses camelCase, including scopeId, activationId, and replyReady. Increase offset by the number of returned items until you have read the visible list. This list is not a stable activation-history snapshot. For polling agents, load any uninitialized current activation with the complete initialization helper, persist its checkpoint, then read new messages through the ordinary channel APIs.

Errors

Status	Meaning
`403` / `404`	Identity scope or visibility does not permit the request.
`413`	Too many group conversations to verify in one request.
`422`	Invalid channel or pagination bounds.
`503`	Current group membership could not be verified in time. Retry later.

See configuration, activation history, and revocation.

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Companion conversation state

Query parameters

Response

Status values

Examples

Errors

​Query parameters

​Response

​Status values

​Examples

​Errors

Query parameters

Response

Status values

Examples

Errors