> ## 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 configuration > Read and update the Companion enabled preference and inspect channel readiness Configure [Companion mode](/docs/capabilities/companion-mode) for one identity. This is a separate boolean preference, not a filter mode or a sender-selection resource. SDK and CLI support requires `0.7.3` or later. ```text theme={null} GET /api/v1/identities/{agent_handle}/companion PATCH /api/v1/identities/{agent_handle}/companion ``` `agent_handle` is the identity handle. A leading `@` is optional. Both operations return `200` with the configuration object. ## Authorization | Caller | GET | PATCH | | :---------------------------------------------------------- | :----------------------------------------------------- | :------------ | | Admin-scoped API key or human session in the Inkbox Console | Full configuration for an identity in the organization | Allowed | | Claimed identity-scoped API key | Own identity only | `403` | | Unclaimed identity-scoped API key | Not supported | Not supported | The configuration response contains enabled state, revision, and channel readiness for every permitted caller. It does not contain sender identifiers. Claimed-agent write restrictions are authorization rules, not a readiness gate on an administrator's toggle. ## Update fields | Field | Type | Meaning | | :-------- | :------ | :-------------------------------------------------------------------- | | `enabled` | boolean | Explicitly enable or disable. Defaults to `false` for a new identity. | Omitting `enabled` is a no-op. A null or non-boolean value and unknown fields return `422`. The request accepts only `enabled`. An authorized administrator can enable the preference **before any eligible sender or channel resource exists**. Missing exact allow rules, a phone number, or a dedicated iMessage line do not make this PATCH fail with a setup-related `403` or `409`. Readiness and all actual-use checks still apply. Enabling never provisions a channel, creates contact rules, or grants consent. ```bash cURL theme={null} curl -X PATCH "https://inkbox.ai/api/v1/identities/xyz/companion" \ -H "X-API-Key: $INKBOX_ADMIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled":true}' ``` Use `{"enabled":false}` to disable. `config_revision` changes only when enabled state changes. A same-value PATCH and an empty object preserve the revision. Disabling and re-enabling does not revive previous activations; a fresh qualifying group message is required. ## Sender eligibility A sender can activate a group only when their actual normalized identifier has **active exact allow rules covering inbound and outbound**. One `both` allow or two separate one-way allows qualify. Email requires `exact_email`; phone/iMessage use the shared `exact_number` policy. Domain allows, blacklist defaults, contact visibility, another address on the same saved contact, and borrowed Companion permission do not confer eligibility. Paused or deleted allows do not qualify. Multiple senders may be eligible. The first qualifying authenticated inbound group message activates the scope and binds the sponsor to its actual author. Later eligible senders' messages in that active scope are live traffic, not repeated initialization. Continued access requires the original author's exact bidirectional allow and current group membership. Revocation does not silently transfer an activation or queued replies to another eligible participant. See [explicit allow and boolean-update examples](/docs/capabilities/companion-mode#example-allow-an-email-sender-and-enable). Those rules prepare actual use; they are not required to save the enabled preference. ## Configuration object | Field | Type | Meaning | | :---------------- | :-------------- | :----------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | Whether the identity has enabled Companion mode. | | `config_revision` | integer | Configuration revision; changes only on enabled-state transitions. | | `readiness` | object | `mail`, `phone`, and `imessage` readiness objects, each containing `ready: boolean` and `reasons: string[]`. | | `notices` | array, optional | Advisory [response notices](/docs/get-started/response-notices). | Channel readiness describes prerequisites, not the enabled preference, an activated conversation, or a guaranteed successful send. Readiness does not require `enabled: true`. An identity can be enabled while every channel reports not ready, or disabled while a channel's prerequisites are met. Read [conversation state](/docs/api/identities/companion-conversations) for a particular scope and handle consent, membership, and send errors at actual use. ### Readiness reasons | Reason | Meaning | | :--------------------------------- | :---------------------------------------------------------------------------- | | `bidirectional_allow_required` | No sender has active exact inbound and outbound allow rules for this channel. | | `channel_unavailable` | The identity lacks an active channel resource. | | `text_messaging_unavailable` | The phone channel is not ready for text messaging. | | `dedicated_imessage_line_required` | Companion groups need an attached dedicated iMessage line. | | `imessage_disabled` | Enable iMessage on the identity. | Treat reasons as extensible strings. A ready iMessage channel does not establish that an externally initiated group is available; see [group limitations](/docs/capabilities/companion-mode#channel-limitations). ## SDK and CLI | Operation | Python | TypeScript | Rust | CLI | | :-------- | :---------------------------------------------- | :--------------------------------------------------- | :-------------------------------------------- | :-------------------------------------------------------------- | | Read | `client.companion.get(handle)` | `client.companion.get(handle)` | `client.companion().get(handle)` | `inkbox identity companion get HANDLE --json` | | Update | `client.companion.update(handle, enabled=True)` | `client.companion.update(handle, { enabled: true })` | `client.companion().update(handle, &options)` | `inkbox identity companion update HANDLE --enabled true --json` | TypeScript and CLI JSON use `configRevision`; Python, Rust, and raw API JSON use `config_revision`. Rust takes `inkbox::companion::CompanionUpdateOptions { enabled: Some(true) }`. The CLI update requires `--enabled`, accepting only `true` or `false`. Use `get` to read readiness without changing the preference. See [SDK configuration examples](/docs/capabilities/companion-mode#enable-companion-mode). ## Errors | Status | Meaning | | :----- | :-------------------------------------------------------------------- | | `403` | The caller lacks management authority or the required identity scope. | | `404` | The identity is unavailable to the caller. | | `422` | Unknown fields, or a null/non-boolean `enabled` value. | ## Related resources * [Directional identity permissions](/docs/api/identities/manage#directional-filter-modes) * [Mail rules](/docs/api/mail/contact-rules), [phone rules](/docs/api/phone/contact-rules), and [iMessage rules](/docs/api/imessage/contact-rules) * [Conversation state](/docs/api/identities/companion-conversations) and [activation history](/docs/api/identities/companion-history)