Chatwoot conversations and messages

Use these 28 provider-catalogue capabilities to find conversations, change their state, manage routing metadata, and work with messages. Start by choosing the exact capability ID; three similar connector composites use different punctuation and different contracts.

The connector inserts its configured Chatwoot account. Applications supply only conversation, message, query, and provider-body values allowed by the selected operation.

Family at a glance

The method split is nine GET, 15 POST, two PATCH, and two DELETE operations. The nine reads are low risk, 17 mutations are medium risk, and the two deletes are high risk.

Twenty-seven capabilities are Tools. conversation.transcript is a Workflow, but its execution contract is still synchronous and has no async, streaming, or cancellation support.

Distinguish catalogue operations from composites

Do not normalize dots and colons. They are distinct capability IDs, and an approval or idempotency record for one does not authorize another.

Core conversation operations

conversation.filter has a read-like purpose but uses POST. The frozen catalogue classifies every non-GET operation as a mutation. It therefore requires approval and an idempotency key and does not advertise retry support.

State, routing, and metadata operations

The word list in conversation.reporting_event.list matches its GET contract. The word transcript does not imply a background AIP run; this Workflow completes through the same synchronous catalogue path.

Typing state, labels, priority, assignment, and custom attributes can affect customer-service workflows. The generic contract marks only write and external_network, so policy must also inspect the exact capability and body.

Message operations

message.retry is a provider operation, not permission for AIP to repeat the Action. Its own capability contract declares retry unsafe. Repeating it after an uncertain result can ask Chatwoot to process the failed message again.

Account and path inputs

The host inserts account_id. It is not a caller input.

conversation_id is required by 22 operations. It is omitted only for:

• conversation.list;
• conversation.create;
• conversation.meta;
• conversation.search;
• conversation.unread_counts;
• conversation.filter.

message_id is additionally required by message.update, message.delete, message.translate, and message.retry.

Every path input is a non-blank string of at most 512 bytes without control characters. Each value becomes one encoded URL segment.

Generic input envelope

The catalogue adds optional query, body, and multipart properties around the required path IDs:

body and multipart are mutually exclusive. Provider-specific message, conversation, filter, assignment, label, status, and translation fields are not frozen by this generic schema.

An input can satisfy the AIP schema and still be rejected by Chatwoot. Use the payload contract for the exact pinned provider route, then retain its canonical form with approval evidence.

Read one conversation

Use a conversation ID obtained from the same account route:

aipctl action call \
  "$AIP_URL" \
  cap:chatwoot:conversation.get \
  --action-id act_chatwoot_conversation_get_001 \
  --input '{"conversation_id":"314"}'

The connector sends:

GET /api/v1/accounts/{configured_account_id}/conversations/314

This read needs no capability-level approval and advertises safe retry. Its result can contain customer and message metadata, so the restricted-data and redaction contract still applies.

Create a message with an attachment

The pinned connector fixture exercises cap:chatwoot:message.create with this exact input shape:

{
  "conversation_id": "conversation-1",
  "multipart": {
    "fields": {
      "content": "Evidence attached",
      "private": false
    },
    "files": [
      {
        "field_name": "attachments[]",
        "filename": "evidence.txt",
        "content_type": "text/plain",
        "content_base64": "aGVsbG8="
      }
    ]
  }
}

The fixture proves connector-side multipart encoding and allowlist enforcement. It does not prove that an unidentified Chatwoot version accepts the same payload.

Multipart bounds

Each file object must contain exactly field_name, filename, content_type, and standard-base64 content_base64. An empty multipart object is rejected.

Submit the message mutation with a unique Action ID, exact approval, and one external-account-scoped idempotency key. The connector forwards X-AIP-Action-ID and Idempotency-Key to the provider.

Shared mutation contract

All 19 non-GET operations declare:

The connector forwards an idempotency key but does not prove provider deduplication. Preserve one key only for the same capability, account, Action, path IDs, and canonical input.

Result contract

A successful catalogue operation returns:

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

body contains parsed JSON, null for an empty provider body, or a text wrapper for non-JSON bytes. provider_request_id reads x-request-id first and x-runtime second.

This generic result differs from the strict outputs of the three colon-named composites. Do not deserialize one as the other.

Failures and recovery

Connector failures set retryable: false. Only the nine read contracts advertise retry support.

For an uncertain create or update, search or read the target before submitting a correction. For an uncertain delete, compare authoritative state and audit evidence. For an uncertain message.retry or message.create, inspect the conversation before risking duplicate customer-visible delivery.

Approval and idempotency do not provide rollback. Corrective writes require a new decision based on current Chatwoot state.

Verify an integration

Require all of the following:

• discovery returns the exact dot-named catalogue capability;
• the Action does not contain a caller-selected account ID;
• conversation and message IDs belong to the configured account;
• provider body fields match the pinned route;
• every non-GET operation has exact approval and one retained key;
• multipart content stays within every decoded and aggregate bound;
• the completed result belongs to the original Action and preserves provider status and request identity;
• consequential mutations are confirmed through authoritative conversation state;
• restricted conversation, message, transcript, and attachment data is redacted and retained under tenant policy;
• uncertain mutations are reconciled instead of repeated.

These checks validate application behavior. They do not establish live Chatwoot qualification or customer-delivery correctness.

Related documentation

• Chatwoot capability index
• Accounts, agents, teams, and bots
• Run the Chatwoot connector quickstart
• Approvals and policy
• Error reference