Chatwoot accounts, agents, teams, and bots

Use these 22 capabilities to read the configured account and manage its human agents, teams, team membership, and agent bots. The connector owns the account boundary; an Action cannot select another Chatwoot account through its input.

This page documents the exact routes and the generic AIP request envelope frozen in the reviewed source. It does not invent provider payload fields that the Rust catalogue does not validate.

Family at a glance

All 22 capabilities are Tools. The eight GET operations are low-risk reads. The five POST and five PATCH operations are medium-risk mutations. The four DELETE operations are high-risk mutations.

Every mutation requires approval and an idempotency key. Reads do not require capability-level approval and advertise safe retry support.

Account and agent operations

agent.bulk_create is one provider mutation. The catalogue does not define a per-item transaction, partial-success model, or compensating operation. Preserve the provider result before deciding how to recover a partial import.

Team and membership operations

The three membership mutations share one collection route. Their provider methods distinguish add, replace, and remove behavior. Review the exact member set in the approved body, especially before team.member.update.

Agent-bot operations

Agent-bot records can influence automated handling in Chatwoot, but the generic contract declares only write and external_network side effects. Apply provider-aware policy without treating the generic markers as an exhaustive impact model.

Account and path inputs

The host inserts its configured account_id into every provider path. Do not put account_id in Action input; it is not present in the published input schema.

The remaining placeholders become required top-level strings:

Each path value must be non-blank, contain no control character, and fit within 512 bytes. The URL builder inserts it as one encoded path segment. A caller cannot use a slash inside the value to select another route.

Generic catalogue input

Every operation accepts the same source-generated envelope around its path inputs:

A null query value is omitted. String, number, integer, and Boolean values are encoded as query values. Nested query objects are rejected.

The connector does not freeze operation-specific body fields for this family. It validates only that body is an object within the generic bounds, then passes it to the pinned provider route. Use the provider schema admitted for the pinned Chatwoot revision. Do not infer that a schema-valid empty object is a valid provider mutation.

The same generic input technically permits multipart data. Use it only when the pinned provider operation explicitly accepts multipart content. These 22 catalogue entries publish no operation-specific multipart requirement.

Read an assignable-agent list

Select the capability from tenant discovery, then send only the provider query that the admitted route needs:

aipctl action call \
  "$AIP_URL" \
  cap:chatwoot:agent.assignable.list \
  --action-id act_chatwoot_assignable_agents_001 \
  --input '{"query":{"page":1}}'

The connector inserts the account and calls:

GET /api/v1/accounts/{configured_account_id}/assignable_agents?page=1

The read is safe to retry at the capability-contract level. A retry still requires the same tenant route, deadline, and policy context. It can return a different list if Chatwoot state changed between calls.

Update an agent

The pinned connector fixture demonstrates this exact generic input:

{
  "agent_id": "42",
  "body": {
    "name": "Operations"
  }
}

Submit it as one governed Action:

aipctl action call \
  "$AIP_URL" \
  cap:chatwoot:agent.update \
  --action-id act_chatwoot_agent_update_001 \
  --idempotency-key agent-update-42-v1 \
  --input '{"agent_id":"42","body":{"name":"Operations"}}'

Expected first outcome: the policy path may hold the Action for approval. The approval must bind this capability, agent ID, body, Action identity, actor, tenant, and policy hash.

After authorization, the connector sends PATCH to the configured account, adds X-AIP-Action-ID and Idempotency-Key, and uses the configured api_access_token. Do not place the token in Action input or evidence.

Mutation safety

All 14 mutations share this AIP contract:

An idempotency key binds one intent inside the external-account scope. The connector forwards that key to Chatwoot, but the contract does not prove that every pinned provider route deduplicates requests.

If dispatch may have occurred, retain the original Action and key. Inspect authoritative Chatwoot state before any corrective mutation. Do not create a new Action merely because the original response was lost.

Result contract

A successful catalogue call returns:

{
  "http_status": 200,
  "body": {},
  "provider_request_id": null
}

http_status contains the successful provider status. body contains parsed JSON, null for an empty response, or {"text":"..."} for a non-JSON body. provider_request_id uses x-request-id when present and falls back to x-runtime.

The default response bound is 16 MiB and configuration can raise it only to the connector’s hard 128 MiB ceiling. A successful HTTP response that exceeds the active bound fails before an Action result is returned.

Provider response fields remain provider-owned. Preserve unknown fields and validate the specific object shape required by the application.

Failures and recovery

The failure mapping sets retryable to false for every connector failure. That prevents an error from instructing a blind retry. The capability contract separately permits bounded retries for the eight reads.

Transport, temporary provider, and oversized-response failures mark an invocation outcome uncertain. For a mutation, uncertainty means the provider may already contain the change. Read authoritative state before deciding on a separately approved correction.

Verify an integration

Require all of the following:

• tenant discovery returns only the admitted family operations;
• the Action contains no caller-selected account ID;
• each non-account path placeholder is present and bound to the intended provider object;
• every mutation has exact approval evidence and one retained idempotency key;
• the completed result belongs to the submitted Action and preserves provider status and request identity;
• a read-back confirms consequential writes when the provider offers one;
• restricted account, agent, team, and bot data follows tenant redaction and retention policy;
• uncertain mutations are reconciled instead of repeated.

These checks validate application handling. They do not establish live qualification of a Chatwoot version or permission to administer every object in the configured account.

Related documentation

• Chatwoot capability index
• Authentication and account isolation
• Chatwoot connector configuration
• Approvals and policy
• Error reference