Chatwoot automation, macros, and canned responses

Use these 16 capabilities to manage reusable text and behavior in the configured Chatwoot account. Review both the immediate provider request and the later effects of the object being created, changed, cloned, or executed.

The generic catalogue marks mutations as write plus external_network. Those markers do not describe every future message, assignment, label, or workflow effect that provider configuration may cause.

Family at a glance

The method split is five GET, five POST, three PATCH, and three DELETE operations. Five reads are low risk, seven mutations are medium risk, and four mutations are high risk.

Fourteen capabilities are Tools. automation_rule.clone and macro.execute are Workflows. Both still use synchronous execution without AIP async, streaming, or cancellation support.

Canned-response operations

The reviewed catalogue has no canned_response.get capability. Use the list result only when its provider shape contains enough information for the task. Do not synthesize a get ID or call an unadmitted provider path.

Canned text can later be sent to customers. Review restricted data, placeholders, links, and tenant policy before creating or updating it.

Automation-rule operations

The source classifies clone as a Workflow but does not publish a transaction, background-run handle, or rollback operation. Treat the returned provider body as the only immediate result, then inspect the cloned rule.

The generic body schema does not validate conditions, actions, ordering, activation, or other provider rule fields. Approval must cover the complete provider body and the behavior it can trigger.

Macro operations

macro.execute is the only non-delete high-risk operation in this family. It is a synchronous Workflow and has no AIP rollback. The body that identifies the target and execution context remains provider-owned.

Do not infer safe repetition from the verb execute or from the idempotency key. A lost response can hide provider-side effects on the declared target.

Account and path inputs

The connector injects its configured account_id. Callers cannot select another account through Action input.

Each path value is a non-blank string of at most 512 bytes without control characters. The URL builder encodes it as one path segment.

Create and list operations use account-level collection routes. Their provider identifiers or fields belong in query or body, not in a guessed path.

Generic provider input

Every operation accepts the common catalogue envelope:

The connector rejects body and multipart together. It does not validate a canned-response payload, rule definition, macro definition, clone option, or execution target.

Use the exact pinned provider schema. Retain the canonical body with the approval evidence and idempotency record.

Read one macro

Use a macro ID returned by the same configured account:

aipctl action call \
  "$AIP_URL" \
  cap:chatwoot:macro.get \
  --action-id act_chatwoot_macro_get_001 \
  --input '{"macro_id":"41"}'

The connector sends:

GET /api/v1/accounts/{configured_account_id}/macros/41

The read needs no capability-level approval and advertises safe retry. Treat the provider body as restricted data because it can describe customer-visible or operational behavior.

Review a mutation by intent

The source does not prove that list results expose every field required for review. Use automation_rule.get or macro.get when exact reads exist. For a canned response, retain authoritative provider evidence available through the admitted list surface.

Shared mutation contract

All 11 mutations declare:

The idempotency key identifies one governed intent. The connector forwards it to Chatwoot but does not establish provider deduplication.

Result contract

Every successful catalogue call returns:

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

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

The result does not include an AIP Workflow run ID. A Workflow kind here describes capability semantics, not asynchronous execution.

Failures and recovery

All connector failures set retryable: false. Only the five read contracts advertise safe retry.

For an uncertain create, update, clone, or delete, inspect the provider object before another Action. For uncertain macro.execute, inspect the exact target and resulting conversation state before risking repeated effects.

No mutation has an AIP compensating capability. A corrective change requires new approval against current provider state.

Verify an integration

Require all of the following:

• discovery admits the exact reusable-behavior capability;
• every path ID belongs to the configured account;
• provider body fields match the pinned route;
• approval covers both immediate changes and expected future behavior;
• each mutation retains one Action ID, one canonical input, and one idempotency key;
• clone and execute are treated as synchronous, unsafe-to-retry Workflows;
• the completed result belongs to the submitted Action;
• reads confirm the created, changed, cloned, or deleted object when possible;
• restricted reusable content and rule detail follows redaction and retention policy;
• uncertain mutations are reconciled instead of repeated.

These checks validate application behavior. They do not qualify a provider rule engine, macro effect, or customer-visible result.

Related documentation

• Chatwoot capability index
• Conversations and messages
• Chatwoot connector configuration
• Approvals and policy
• Error reference