Skip to main content
Configure 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.
agent_handle is the identity handle. A leading @ is optional. Both operations return 200 with the configuration object.

​
Authorization

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

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.
cURL
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. Those rules prepare actual use; they are not required to save the enabled preference.

​
Configuration object

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 for a particular scope and handle consent, membership, and send errors at actual use.

​
Readiness reasons

Treat reasons as extensible strings. A ready iMessage channel does not establish that an externally initiated group is available; see group limitations.

​
SDK and CLI

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.

​
Errors