{
  "schemaVersion": "1.0",
  "title": "Chatwoot automation, macros, and canned responses",
  "description": "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.",
  "canonical": "https://getaip.org/docs/connectors/chatwoot/capabilities/automation-macros-and-canned-responses",
  "route": "/docs/connectors/chatwoot/capabilities/automation-macros-and-canned-responses",
  "source": "docs/connectors/chatwoot/capabilities/automation-macros-and-canned-responses.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/chatwoot/capabilities/automation-macros-and-canned-responses.md",
    "txt": "/docs/download/connectors/chatwoot/capabilities/automation-macros-and-canned-responses.txt",
    "json": "/docs/download/connectors/chatwoot/capabilities/automation-macros-and-canned-responses.json",
    "pdf": "/docs/download/connectors/chatwoot/capabilities/automation-macros-and-canned-responses.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Chatwoot automation, macros, and canned responses\ndescription: >-\n  Use 16 exact reusable-behavior capabilities with governed creation, cloning,\n  execution, update, and deletion\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: chatwoot\ncapabilityIds:\n  - cap:chatwoot:canned_response.list\n  - cap:chatwoot:canned_response.create\n  - cap:chatwoot:canned_response.update\n  - cap:chatwoot:canned_response.delete\n  - cap:chatwoot:automation_rule.list\n  - cap:chatwoot:automation_rule.get\n  - cap:chatwoot:automation_rule.create\n  - cap:chatwoot:automation_rule.update\n  - cap:chatwoot:automation_rule.delete\n  - cap:chatwoot:automation_rule.clone\n  - cap:chatwoot:macro.list\n  - cap:chatwoot:macro.get\n  - cap:chatwoot:macro.create\n  - cap:chatwoot:macro.update\n  - cap:chatwoot:macro.delete\n  - cap:chatwoot:macro.execute\naliases:\n  - Chatwoot reusable behavior\n  - Chatwoot automation capabilities\n---\n\n# Chatwoot automation, macros, and canned responses\n\nUse these 16 capabilities to manage reusable text and behavior in the\nconfigured Chatwoot account. Review both the immediate provider request and\nthe later effects of the object being created, changed, cloned, or executed.\n\nThe generic catalogue marks mutations as `write` plus `external_network`. Those\nmarkers do not describe every future message, assignment, label, or workflow\neffect that provider configuration may cause.\n\n## Family at a glance\n\n| Group | Operations | Reads | Mutations | High risk |\n|---|---:|---:|---:|---:|\n| Canned responses | 4 | 1 | 3 | 1 |\n| Automation rules | 6 | 2 | 4 | 1 |\n| Macros | 6 | 2 | 4 | 2 |\n| **Total** | **16** | **5** | **11** | **4** |\n\nThe method split is five `GET`, five `POST`, three `PATCH`, and three `DELETE`\noperations. Five reads are low risk, seven mutations are medium risk, and four\nmutations are high risk.\n\nFourteen capabilities are Tools. `automation_rule.clone` and `macro.execute`\nare Workflows. Both still use synchronous execution without AIP async,\nstreaming, or cancellation support.\n\n## Canned-response operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:canned_response.list` | `GET /api/v1/accounts/{account_id}/canned_responses` | List canned responses | Low | No |\n| `cap:chatwoot:canned_response.create` | `POST /api/v1/accounts/{account_id}/canned_responses` | Create a canned response | Medium | Required |\n| `cap:chatwoot:canned_response.update` | `PATCH /api/v1/accounts/{account_id}/canned_responses/{canned_response_id}` | Update one canned response | Medium | Required |\n| `cap:chatwoot:canned_response.delete` | `DELETE /api/v1/accounts/{account_id}/canned_responses/{canned_response_id}` | Delete one canned response | High | Required |\n\nThe reviewed catalogue has no `canned_response.get` capability. Use the list\nresult only when its provider shape contains enough information for the task.\nDo not synthesize a get ID or call an unadmitted provider path.\n\nCanned text can later be sent to customers. Review restricted data,\nplaceholders, links, and tenant policy before creating or updating it.\n\n## Automation-rule operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:automation_rule.list` | `GET /api/v1/accounts/{account_id}/automation_rules` | List automation rules | Low | No |\n| `cap:chatwoot:automation_rule.get` | `GET /api/v1/accounts/{account_id}/automation_rules/{automation_rule_id}` | Read one rule | Low | No |\n| `cap:chatwoot:automation_rule.create` | `POST /api/v1/accounts/{account_id}/automation_rules` | Create a rule | Medium | Required |\n| `cap:chatwoot:automation_rule.update` | `PATCH /api/v1/accounts/{account_id}/automation_rules/{automation_rule_id}` | Update one rule | Medium | Required |\n| `cap:chatwoot:automation_rule.delete` | `DELETE /api/v1/accounts/{account_id}/automation_rules/{automation_rule_id}` | Delete one rule | High | Required |\n| `cap:chatwoot:automation_rule.clone` | `POST /api/v1/accounts/{account_id}/automation_rules/{automation_rule_id}/clone` | Clone one rule | Medium | Required |\n\nThe source classifies clone as a Workflow but does not publish a transaction,\nbackground-run handle, or rollback operation. Treat the returned provider body\nas the only immediate result, then inspect the cloned rule.\n\nThe generic body schema does not validate conditions, actions, ordering,\nactivation, or other provider rule fields. Approval must cover the complete\nprovider body and the behavior it can trigger.\n\n## Macro operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:macro.list` | `GET /api/v1/accounts/{account_id}/macros` | List macros | Low | No |\n| `cap:chatwoot:macro.get` | `GET /api/v1/accounts/{account_id}/macros/{macro_id}` | Read one macro | Low | No |\n| `cap:chatwoot:macro.create` | `POST /api/v1/accounts/{account_id}/macros` | Create a macro | Medium | Required |\n| `cap:chatwoot:macro.update` | `PATCH /api/v1/accounts/{account_id}/macros/{macro_id}` | Update one macro | Medium | Required |\n| `cap:chatwoot:macro.delete` | `DELETE /api/v1/accounts/{account_id}/macros/{macro_id}` | Delete one macro | High | Required |\n| `cap:chatwoot:macro.execute` | `POST /api/v1/accounts/{account_id}/macros/{macro_id}/execute` | Execute a macro against its declared target | High | Required |\n\n`macro.execute` is the only non-delete high-risk operation in this family. It\nis a synchronous Workflow and has no AIP rollback. The body that identifies\nthe target and execution context remains provider-owned.\n\nDo not infer safe repetition from the verb `execute` or from the idempotency\nkey. A lost response can hide provider-side effects on the declared target.\n\n## Account and path inputs\n\nThe connector injects its configured `account_id`. Callers cannot select\nanother account through Action input.\n\n| Input | Required by |\n|---|---|\n| `canned_response_id` | Canned-response update and delete |\n| `automation_rule_id` | Rule get, update, delete, and clone |\n| `macro_id` | Macro get, update, delete, and execute |\n\nEach path value is a non-blank string of at most 512 bytes without control\ncharacters. The URL builder encodes it as one path segment.\n\nCreate and list operations use account-level collection routes. Their provider\nidentifiers or fields belong in `query` or `body`, not in a guessed path.\n\n## Generic provider input\n\nEvery operation accepts the common catalogue envelope:\n\n| Property | Connector boundary |\n|---|---|\n| `query` | Optional object; at most 128 keys; scalar values or bounded scalar arrays |\n| `body` | Optional object; at most 512 properties and 16 MiB encoded |\n| `multipart` | Optional bounded fields-and-files object instead of `body` |\n\nThe connector rejects `body` and `multipart` together. It does not validate a\ncanned-response payload, rule definition, macro definition, clone option, or\nexecution target.\n\nUse the exact pinned provider schema. Retain the canonical body with the\napproval evidence and idempotency record.\n\n## Read one macro\n\nUse a macro ID returned by the same configured account:\n\n```sh\naipctl action call \\\n  \"$AIP_URL\" \\\n  cap:chatwoot:macro.get \\\n  --action-id act_chatwoot_macro_get_001 \\\n  --input '{\"macro_id\":\"41\"}'\n```\n\nThe connector sends:\n\n```text\nGET /api/v1/accounts/{configured_account_id}/macros/41\n```\n\nThe read needs no capability-level approval and advertises safe retry. Treat\nthe provider body as restricted data because it can describe customer-visible\nor operational behavior.\n\n## Review a mutation by intent\n\n| Intent | Review before approval | Verify after completion |\n|---|---|---|\n| Create reusable text | Content, placeholders, links, audience, and owner | List canned responses |\n| Update reusable text | Current object, exact changed fields, and downstream use | List canned responses and compare |\n| Create or update a rule | Complete rule definition from the pinned provider schema | Read the rule |\n| Clone a rule | Source identity and provider-owned clone options | Read the returned or discovered clone |\n| Create or update a macro | Complete provider definition and intended use | Read the macro |\n| Execute a macro | Macro revision, exact target, execution body, and expected effects | Read the target and related conversation state |\n| Delete any reusable object | Current object, references, owner, and removal intent | Confirm provider state and audit evidence |\n\nThe source does not prove that list results expose every field required for\nreview. Use `automation_rule.get` or `macro.get` when exact reads exist. For a\ncanned response, retain authoritative provider evidence available through the\nadmitted list surface.\n\n## Shared mutation contract\n\nAll 11 mutations declare:\n\n| Contract field | Value |\n|---|---|\n| Approval | Required; tenant-policy selector |\n| Approval validity | 900,000 ms |\n| Approval evidence | Reason, input snapshot, policy decision |\n| Idempotency | Required; external-account scope; 86,400,000 ms published TTL |\n| Connector retry | Not supported; unsafe |\n| Side effects | `write`, `external_network` |\n| Data | Restricted; contains PII; redaction required |\n| Execution | Synchronous; no async, streaming, or cancellation support |\n| Compensation | Rollback not supported |\n\nThe idempotency key identifies one governed intent. The connector forwards it\nto Chatwoot but does not establish provider deduplication.\n\n## Result contract\n\nEvery successful catalogue call returns:\n\n```json\n{\n  \"http_status\": 200,\n  \"body\": {},\n  \"provider_request_id\": null\n}\n```\n\n`body` is parsed JSON, `null` for an empty provider response, or a `text`\nwrapper for non-JSON bytes. `provider_request_id` takes `x-request-id` first\nand `x-runtime` second.\n\nThe result does not include an AIP Workflow run ID. A Workflow kind here\ndescribes capability semantics, not asynchronous execution.\n\n## Failures and recovery\n\n| Failure code | Typical cause | Safe response |\n|---|---|---|\n| `connector.chatwoot.invalid_action` | Unknown or unadmitted ID, missing path input, or malformed generic envelope | Refresh discovery or correct input before dispatch |\n| `connector.chatwoot.missing_idempotency_key` | Mutation lacks a valid key | Restore the key for the original governed input |\n| `connector.chatwoot.authentication` | Provider returned `401` or `403` | Verify account route and credential revision |\n| `connector.chatwoot.remote_rejected` | Provider rejected fields or current state | Correct authoritative input before a new Action |\n| `connector.chatwoot.remote_temporary` | Provider returned `429` or a server error | Retry a read within policy; reconcile a mutation |\n| `connector.chatwoot.transport` | Provider exchange failed | Retry a read within policy; treat mutation outcome as uncertain |\n| `connector.chatwoot.response_too_large` | Response crossed the active bound | Preserve evidence and reconcile a mutation |\n\nAll connector failures set `retryable: false`. Only the five read contracts\nadvertise safe retry.\n\nFor an uncertain create, update, clone, or delete, inspect the provider object\nbefore another Action. For uncertain `macro.execute`, inspect the exact target\nand resulting conversation state before risking repeated effects.\n\nNo mutation has an AIP compensating capability. A corrective change requires\nnew approval against current provider state.\n\n## Verify an integration\n\nRequire all of the following:\n\n- discovery admits the exact reusable-behavior capability;\n- every path ID belongs to the configured account;\n- provider body fields match the pinned route;\n- approval covers both immediate changes and expected future behavior;\n- each mutation retains one Action ID, one canonical input, and one\n  idempotency key;\n- clone and execute are treated as synchronous, unsafe-to-retry Workflows;\n- the completed result belongs to the submitted Action;\n- reads confirm the created, changed, cloned, or deleted object when possible;\n- restricted reusable content and rule detail follows redaction and retention\n  policy;\n- uncertain mutations are reconciled instead of repeated.\n\nThese checks validate application behavior. They do not qualify a provider\nrule engine, macro effect, or customer-visible result.\n\n## Related documentation\n\n- [Chatwoot capability index](README.md)\n- [Conversations and messages](conversations-and-messages.md)\n- [Chatwoot connector configuration](../reference/configuration.md)\n- [Approvals and policy](../../../concepts/approvals-and-policy.md)\n- [Error reference](../../../reference/errors.md)\n",
    "text": "Chatwoot automation, macros, and canned responses\n\nUse these 16 capabilities to manage reusable text and behavior in the\nconfigured Chatwoot account. Review both the immediate provider request and\nthe later effects of the object being created, changed, cloned, or executed.\n\nThe generic catalogue marks mutations as write plus externalnetwork. Those\nmarkers do not describe every future message, assignment, label, or workflow\neffect that provider configuration may cause.\n\nFamily at a glance\n\n| Group | Operations | Reads | Mutations | High risk |\n\n| Canned responses | 4 | 1 | 3 | 1 |\n| Automation rules | 6 | 2 | 4 | 1 |\n| Macros | 6 | 2 | 4 | 2 |\n| Total | 16 | 5 | 11 | 4 |\n\nThe method split is five GET, five POST, three PATCH, and three DELETE\noperations. Five reads are low risk, seven mutations are medium risk, and four\nmutations are high risk.\n\nFourteen capabilities are Tools. automationrule.clone and macro.execute\nare Workflows. Both still use synchronous execution without AIP async,\nstreaming, or cancellation support.\n\nCanned-response operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:cannedresponse.list | GET /api/v1/accounts/{accountid}/cannedresponses | List canned responses | Low | No |\n| cap:chatwoot:cannedresponse.create | POST /api/v1/accounts/{accountid}/cannedresponses | Create a canned response | Medium | Required |\n| cap:chatwoot:cannedresponse.update | PATCH /api/v1/accounts/{accountid}/cannedresponses/{cannedresponseid} | Update one canned response | Medium | Required |\n| cap:chatwoot:cannedresponse.delete | DELETE /api/v1/accounts/{accountid}/cannedresponses/{cannedresponseid} | Delete one canned response | High | Required |\n\nThe reviewed catalogue has no cannedresponse.get capability. Use the list\nresult only when its provider shape contains enough information for the task.\nDo not synthesize a get ID or call an unadmitted provider path.\n\nCanned text can later be sent to customers. Review restricted data,\nplaceholders, links, and tenant policy before creating or updating it.\n\nAutomation-rule operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:automationrule.list | GET /api/v1/accounts/{accountid}/automationrules | List automation rules | Low | No |\n| cap:chatwoot:automationrule.get | GET /api/v1/accounts/{accountid}/automationrules/{automationruleid} | Read one rule | Low | No |\n| cap:chatwoot:automationrule.create | POST /api/v1/accounts/{accountid}/automationrules | Create a rule | Medium | Required |\n| cap:chatwoot:automationrule.update | PATCH /api/v1/accounts/{accountid}/automationrules/{automationruleid} | Update one rule | Medium | Required |\n| cap:chatwoot:automationrule.delete | DELETE /api/v1/accounts/{accountid}/automationrules/{automationruleid} | Delete one rule | High | Required |\n| cap:chatwoot:automationrule.clone | POST /api/v1/accounts/{accountid}/automationrules/{automationruleid}/clone | Clone one rule | Medium | Required |\n\nThe source classifies clone as a Workflow but does not publish a transaction,\nbackground-run handle, or rollback operation. Treat the returned provider body\nas the only immediate result, then inspect the cloned rule.\n\nThe generic body schema does not validate conditions, actions, ordering,\nactivation, or other provider rule fields. Approval must cover the complete\nprovider body and the behavior it can trigger.\n\nMacro operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:macro.list | GET /api/v1/accounts/{accountid}/macros | List macros | Low | No |\n| cap:chatwoot:macro.get | GET /api/v1/accounts/{accountid}/macros/{macroid} | Read one macro | Low | No |\n| cap:chatwoot:macro.create | POST /api/v1/accounts/{accountid}/macros | Create a macro | Medium | Required |\n| cap:chatwoot:macro.update | PATCH /api/v1/accounts/{accountid}/macros/{macroid} | Update one macro | Medium | Required |\n| cap:chatwoot:macro.delete | DELETE /api/v1/accounts/{accountid}/macros/{macroid} | Delete one macro | High | Required |\n| cap:chatwoot:macro.execute | POST /api/v1/accounts/{accountid}/macros/{macroid}/execute | Execute a macro against its declared target | High | Required |\n\nmacro.execute is the only non-delete high-risk operation in this family. It\nis a synchronous Workflow and has no AIP rollback. The body that identifies\nthe target and execution context remains provider-owned.\n\nDo not infer safe repetition from the verb execute or from the idempotency\nkey. A lost response can hide provider-side effects on the declared target.\n\nAccount and path inputs\n\nThe connector injects its configured accountid. Callers cannot select\nanother account through Action input.\n\n| Input | Required by |\n\n| cannedresponseid | Canned-response update and delete |\n| automationruleid | Rule get, update, delete, and clone |\n| macroid | Macro get, update, delete, and execute |\n\nEach path value is a non-blank string of at most 512 bytes without control\ncharacters. The URL builder encodes it as one path segment.\n\nCreate and list operations use account-level collection routes. Their provider\nidentifiers or fields belong in query or body, not in a guessed path.\n\nGeneric provider input\n\nEvery operation accepts the common catalogue envelope:\n\n| Property | Connector boundary |\n\n| query | Optional object; at most 128 keys; scalar values or bounded scalar arrays |\n| body | Optional object; at most 512 properties and 16 MiB encoded |\n| multipart | Optional bounded fields-and-files object instead of body |\n\nThe connector rejects body and multipart together. It does not validate a\ncanned-response payload, rule definition, macro definition, clone option, or\nexecution target.\n\nUse the exact pinned provider schema. Retain the canonical body with the\napproval evidence and idempotency record.\n\nRead one macro\n\nUse a macro ID returned by the same configured account:\n\naipctl action call \\\n  \"$AIPURL\" \\\n  cap:chatwoot:macro.get \\\n  --action-id actchatwootmacroget001 \\\n  --input '{\"macroid\":\"41\"}'\n\nThe connector sends:\n\nGET /api/v1/accounts/{configuredaccountid}/macros/41\n\nThe read needs no capability-level approval and advertises safe retry. Treat\nthe provider body as restricted data because it can describe customer-visible\nor operational behavior.\n\nReview a mutation by intent\n\n| Intent | Review before approval | Verify after completion |\n\n| Create reusable text | Content, placeholders, links, audience, and owner | List canned responses |\n| Update reusable text | Current object, exact changed fields, and downstream use | List canned responses and compare |\n| Create or update a rule | Complete rule definition from the pinned provider schema | Read the rule |\n| Clone a rule | Source identity and provider-owned clone options | Read the returned or discovered clone |\n| Create or update a macro | Complete provider definition and intended use | Read the macro |\n| Execute a macro | Macro revision, exact target, execution body, and expected effects | Read the target and related conversation state |\n| Delete any reusable object | Current object, references, owner, and removal intent | Confirm provider state and audit evidence |\n\nThe source does not prove that list results expose every field required for\nreview. Use automationrule.get or macro.get when exact reads exist. For a\ncanned response, retain authoritative provider evidence available through the\nadmitted list surface.\n\nShared mutation contract\n\nAll 11 mutations declare:\n\n| Contract field | Value |\n\n| Approval | Required; tenant-policy selector |\n| Approval validity | 900,000 ms |\n| Approval evidence | Reason, input snapshot, policy decision |\n| Idempotency | Required; external-account scope; 86,400,000 ms published TTL |\n| Connector retry | Not supported; unsafe |\n| Side effects | write, externalnetwork |\n| Data | Restricted; contains PII; redaction required |\n| Execution | Synchronous; no async, streaming, or cancellation support |\n| Compensation | Rollback not supported |\n\nThe idempotency key identifies one governed intent. The connector forwards it\nto Chatwoot but does not establish provider deduplication.\n\nResult contract\n\nEvery successful catalogue call returns:\n\n{\n  \"httpstatus\": 200,\n  \"body\": {},\n  \"providerrequestid\": null\n}\n\nbody is parsed JSON, null for an empty provider response, or a text\nwrapper for non-JSON bytes. providerrequestid takes x-request-id first\nand x-runtime second.\n\nThe result does not include an AIP Workflow run ID. A Workflow kind here\ndescribes capability semantics, not asynchronous execution.\n\nFailures and recovery\n\n| Failure code | Typical cause | Safe response |\n\n| connector.chatwoot.invalidaction | Unknown or unadmitted ID, missing path input, or malformed generic envelope | Refresh discovery or correct input before dispatch |\n| connector.chatwoot.missingidempotencykey | Mutation lacks a valid key | Restore the key for the original governed input |\n| connector.chatwoot.authentication | Provider returned 401 or 403 | Verify account route and credential revision |\n| connector.chatwoot.remoterejected | Provider rejected fields or current state | Correct authoritative input before a new Action |\n| connector.chatwoot.remotetemporary | Provider returned 429 or a server error | Retry a read within policy; reconcile a mutation |\n| connector.chatwoot.transport | Provider exchange failed | Retry a read within policy; treat mutation outcome as uncertain |\n| connector.chatwoot.responsetoolarge | Response crossed the active bound | Preserve evidence and reconcile a mutation |\n\nAll connector failures set retryable: false. Only the five read contracts\nadvertise safe retry.\n\nFor an uncertain create, update, clone, or delete, inspect the provider object\nbefore another Action. For uncertain macro.execute, inspect the exact target\nand resulting conversation state before risking repeated effects.\n\nNo mutation has an AIP compensating capability. A corrective change requires\nnew approval against current provider state.\n\nVerify an integration\n\nRequire all of the following:\n• discovery admits the exact reusable-behavior capability;\n• every path ID belongs to the configured account;\n• provider body fields match the pinned route;\n• approval covers both immediate changes and expected future behavior;\n• each mutation retains one Action ID, one canonical input, and one\n  idempotency key;\n• clone and execute are treated as synchronous, unsafe-to-retry Workflows;\n• the completed result belongs to the submitted Action;\n• reads confirm the created, changed, cloned, or deleted object when possible;\n• restricted reusable content and rule detail follows redaction and retention\n  policy;\n• uncertain mutations are reconciled instead of repeated.\n\nThese checks validate application behavior. They do not qualify a provider\nrule engine, macro effect, or customer-visible result.\n\nRelated documentation\n• Chatwoot capability index (README.md)\n• Conversations and messages (conversations-and-messages.md)\n• Chatwoot connector configuration (../reference/configuration.md)\n• Approvals and policy (../../../concepts/approvals-and-policy.md)\n• Error reference (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "d09126881c91df66eff79952c1b51bf846918ddb052ab30c81db8f4dca1ef943"
  }
}