> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Companion conversation state

> List visible Companion scopes and distinguish read access from reply readiness

```text theme={null}
GET /api/v1/identities/{agent_handle}/companion/conversations
```

Returns a bounded page of visible conversation scopes. See [Companion mode](/docs/capabilities/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](/docs/api/phone/sms-opt-ins).

## Examples

The SDK examples use an authenticated `client`.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  }
  ```

  ```rust Rust theme={null}
  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(())
  }
  ```

  ```bash CLI theme={null}
  inkbox identity companion conversations xyz --channel mail --limit 50 --offset 0 --json
  inkbox identity companion state xyz --channel phone --json
  ```
</CodeGroup>

`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](/docs/capabilities/companion-mode#load-complete-initialization), 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](/docs/api/identities/companion), [activation history](/docs/api/identities/companion-history), and [revocation](/docs/capabilities/companion-mode#revocation).