{
  "schemaVersion": "1.0",
  "title": "Chatwoot connector",
  "description": "Use the Chatwoot connector when an AIP application needs governed access to one Chatwoot account. The connector exposes 150 fixed account API operations, three conversation-oriented AIP composites, and optional authenticated webhook ingress",
  "canonical": "https://getaip.org/docs/connectors/chatwoot",
  "route": "/docs/connectors/chatwoot",
  "source": "docs/connectors/chatwoot/README.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/connectors/chatwoot.md",
    "txt": "/docs/download/connectors/chatwoot.txt",
    "json": "/docs/download/connectors/chatwoot.json",
    "pdf": "/docs/download/connectors/chatwoot.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Chatwoot connector\ndescription: >-\n  Adopt one tenant-bound Chatwoot account through 150 frozen provider\n  operations, three AIP composites, and verified webhook ingress\nkind: connector-overview\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\nconnector: chatwoot\n---\n\n# Chatwoot connector\n\nUse the Chatwoot connector when an AIP application needs governed access to\none Chatwoot account. The connector exposes 150 fixed account API operations,\nthree conversation-oriented AIP composites, and optional authenticated webhook\ningress through a standalone host.\n\nThe connector inserts its configured account ID, base URL, and API token\ninside the host. An Action can choose an admitted capability and provide its\nremaining path, query, or body values, but it cannot select another Chatwoot\naccount or origin.\n\n## At a glance\n\n| Property | Reviewed value |\n|---|---|\n| Connector ID | `chatwoot` |\n| Standalone process | `aip-host-chatwoot` |\n| AIP workspace version | `2.0.0` |\n| Reviewed AIP source | `d7cce13d1d555644d04a4d73c66c95b113737635` |\n| Pinned Chatwoot source | `8818d276b954ac4f84cffd8915c99f40e43804ed` |\n| Connector profile | `aip.connector.chatwoot.v1` |\n| Provider capability shape | `cap:chatwoot:<operation.suffix>` |\n| Full capability count | 150 provider operations plus three AIP composites |\n| Provider authentication | Deployment-owned `api_access_token` header |\n| Inbound path | Optional `POST /webhooks/chatwoot` |\n| Streaming and provider cancellation | Not implemented |\n\nThe full 153-capability count applies only when the operation allowlist is\nomitted or contains all 150 provider operations. A deployment may publish an\nexact non-empty subset of the provider catalogue; the three composites remain\npresent.\n\nThese numbers describe the source contract. They do not prove compatibility\nwith an unidentified Chatwoot image, edition, configuration, or extension.\n\n## Choose this connector when\n\nThe connector fits an integration that needs to:\n\n- manage account agents, teams, bots, inboxes, integrations, and webhooks;\n- create, assign, update, search, and report on customer conversations;\n- send messages and manage contacts, companies, labels, and related records;\n- administer automation rules, macros, canned responses, and portal content;\n- consume verified Chatwoot webhook deliveries as durable AIP events;\n- restrict one deployment to an edition-specific or policy-specific operation\n  allowlist.\n\nUse another integration boundary when the task needs an arbitrary Chatwoot\nURL or method, multiple Chatwoot accounts in one connector instance, a\nprovider-native streaming result, or a route absent from the pinned catalogue.\n\nRe-audit and requalify the exact provider and connector artifacts before\nadvancing the Chatwoot source pin.\n\n## Understand the standalone account boundary\n\nOne connector instance owns one Chatwoot origin and account:\n\n1. An operator configures the base URL, account ID, and owner-only API token\n   file.\n2. The host optionally applies an exact operation-suffix allowlist.\n3. Registry admission binds the resulting manifest, artifact, tenant, external\n   account, credential revision, instance, and replicas.\n4. An authenticated caller submits an Action to product-neutral `getaip-server`.\n5. The registry selects the tenant-owned Chatwoot instance and a ready replica.\n6. The host replaces `{account_id}` with its configured value and encodes the\n   remaining path segments from validated input.\n7. The connector adds the API token and sends one fixed method and route.\n8. The result returns through the durable AIP lifecycle.\n\nThe base URL must be an HTTPS origin without credentials, path, query, or\nfragment. Explicit loopback HTTP is accepted for controlled local use.\nAuthenticated provider requests do not follow redirects.\n\nChanging the account, origin, allowlist, upstream pin, or manifest is a\ndeployment and admission change. Do not treat it as request-level recovery.\n\n## Choose a capability family\n\nThe 150 provider operations are organized into eight reader-facing families.\n\n| Family | Operations | Included domains |\n|---|---:|---|\n| Accounts, agents, teams, and bots | 22 | Account, agents, assignable agents, teams, members, and agent bots |\n| Inboxes, integrations, and webhooks | 21 | Inboxes, members, health, templates, integration hooks, and webhooks |\n| Conversations and messages | 28 | Conversation and message lifecycle, assignment, labels, typing, and attachments |\n| Contacts and companies | 31 | Contact and company lifecycle, notes, merge, import, export, and relations |\n| Automation, macros, and canned responses | 16 | Rules, cloning, macro execution, and canned content |\n| Labels, attributes, and filters | 15 | Labels, custom attribute definitions, and custom filters |\n| Reports, audit, and events | 12 | Reports, summary reports, reporting events, and audit log |\n| Customer portals | 5 | Portals, categories, and articles |\n| **Provider catalogue** | **150** | Complete frozen operation set |\n\nThe catalogue contains 62 `GET`, 47 `POST`, 21 `PATCH`, and 20 `DELETE`\noperations. Automation-rule clone, macro execute, and conversation transcript\nare workflows. The other 147 catalogue entries are tools.\n\nThe three AIP composites are separate capabilities:\n\n| Capability | Outcome |\n|---|---|\n| `cap:chatwoot:message:create` | Send one public reply or private note and mark it with the AIP Action identity |\n| `cap:chatwoot:conversation:status` | Set a conversation to `open`, `resolved`, or `pending` |\n| `cap:chatwoot:conversation:handoff` | Assign a conversation, add a private note, or perform both in sequence |\n\nThe composite handoff is not one atomic Chatwoot transaction. Its focused\nreference page defines partial-effect and recovery decisions.\n\n## Keep credentials and account identity outside Actions\n\nEvery provider operation uses the configured account ID. Input schemas omit\n`account_id` even though the fixed provider templates contain that segment.\nOther path parameters are bounded and encoded as path segments.\n\nThe host reads the API token from an owner-only file and adds it as\n`api_access_token`. It does not accept a token or base URL in Action input.\nThe HTTP client refuses cross-origin redirects, which prevents automatic token\nforwarding to another origin.\n\nUse one connector instance per Chatwoot account and AIP tenant boundary. Give\neach instance its own API token, runtime database role, admission package,\nexternal-account identity, and webhook secret. An upstream token still needs\nthe least Chatwoot privileges required by the admitted suffix set.\n\n## Apply mutation and retry rules\n\nAll 88 non-`GET` provider operations require human approval and an AIP\nidempotency key scoped to the external account. The connector forwards the\nAction ID and idempotency key as provider headers for catalogue operations.\nThat header does not prove the selected Chatwoot deployment deduplicates a\nmutation.\n\nProvider catalogue reads declare safe retry support. Mutations declare unsafe\nretry behavior and rollback is not implemented. All three composites require\napproval and idempotency; only the conversation-status composite declares\nretry support.\n\nThe connector has no provider cancellation implementation. If local\ncancellation wins before a provider response, the result is uncertain. Read\nthe original Action and Chatwoot state before deciding whether any mutation can\nbe replaced or reconciled.\n\nCustomer, contact, conversation, and message data is marked restricted,\nPII-bearing, and subject to redaction. Keep raw bodies, attachments, tokens,\nand personal data out of logs and evidence summaries.\n\n## Treat webhook ingress as a separate trust path\n\nWebhook ingress is absent when no webhook-secret file is configured. When\nenabled, the standalone host:\n\n1. limits the exact request body to 1 MiB;\n2. requires delivery, timestamp, and `sha256` signature headers;\n3. verifies HMAC over the timestamp, a dot, and the original UTF-8 body;\n4. rejects timestamps outside a five-minute window;\n5. records delivery identity in instance-scoped durable profile state;\n6. ignores messages marked as produced by the Chatwoot connector;\n7. derives a deterministic AIP event ID from the authenticated delivery ID;\n8. appends that event durably before enqueueing central publication.\n\nA provider retry of the same accepted delivery is projected to the same event\nidentity. This supports recovery when a process fails after replay admission\nor event persistence. It does not authorize another outbound response.\n\nAn accepted HTTP response can include a queued central-delivery state. It does\nnot prove every downstream consumer has processed the event.\n\n## Deliberate exclusions\n\nThe reviewed connector does not provide:\n\n- arbitrary provider path, method, origin, or account selection;\n- multiple Chatwoot accounts in one standalone instance;\n- provider credentials from protocol messages or generic credential handles;\n- operation-specific schemas for every upstream request body;\n- native streaming, asynchronous completion, provider cancellation, AIP\n  transactions, reconciliation, or rollback;\n- safe automatic replay of a Chatwoot mutation;\n- a webhook route when verification or central event publication is not\n  configured;\n- compatibility with a Chatwoot revision other than the pinned source;\n- production readiness for an unqualified artifact and deployment.\n\nThe generic catalogue schema bounds paths, query values, JSON bodies, and\nmultipart data. Chatwoot remains responsible for operation-specific semantic\nvalidation.\n\n## Evidence status\n\n| Evidence | What it supports | What it does not support |\n|---|---|---|\n| Source and 150-route matrix | Implemented account-scoped contract at the reviewed AIP commit | Execution of an unbuilt artifact |\n| Connector unit tests | Deterministic catalogue, request, webhook, replay, and redaction checks exist | A retained pass for a promoted image |\n| Controlled product fleet | Admission of 153 capabilities and selected fixture-backed reads and mutation | Real Chatwoot compatibility |\n| Live-product inventory | No dedicated external Chatwoot harness exists at the pinned revision | Any current isolated-live or production pass |\n\nQualify the exact connector image, Chatwoot artifact, account configuration,\nwebhook path, and failure cases before publishing a readiness claim.\n\n## Plan the next task\n\nContinue according to the task you need to complete:\n\n- use `getting-started/quickstart.md` for one admitted host and first\n  conversation flow;\n- use the authentication page to bind the tenant, account, and least-privilege\n  token;\n- use the configuration reference for host, ingress, limit, and allowlist\n  settings;\n- open `capabilities/README.md` to choose one of the eight provider families\n  or three composites;\n- use the webhook and mutation references before enabling inbound events or\n  state changes;\n- use operations and qualification pages before promoting an artifact.\n\nThe global pages below own shared fleet, source-identity, and evidence rules.\n\n## Related documentation\n\n- [Connector documentation](../README.md)\n- [Pinned upstream baselines](../upstream-baselines.md)\n- [Connector fleet quickstart](../../getting-started/connector-fleet-quickstart.md)\n- [Conformance and qualification](../../reference/conformance.md)\n- [Live-product qualification](../../testing/live-product-e2e.md)\n",
    "text": "Chatwoot connector\n\nUse the Chatwoot connector when an AIP application needs governed access to\none Chatwoot account. The connector exposes 150 fixed account API operations,\nthree conversation-oriented AIP composites, and optional authenticated webhook\ningress through a standalone host.\n\nThe connector inserts its configured account ID, base URL, and API token\ninside the host. An Action can choose an admitted capability and provide its\nremaining path, query, or body values, but it cannot select another Chatwoot\naccount or origin.\n\nAt a glance\n\n| Property | Reviewed value |\n\n| Connector ID | chatwoot |\n| Standalone process | aip-host-chatwoot |\n| AIP workspace version | 2.0.0 |\n| Reviewed AIP source | d7cce13d1d555644d04a4d73c66c95b113737635 |\n| Pinned Chatwoot source | 8818d276b954ac4f84cffd8915c99f40e43804ed |\n| Connector profile | aip.connector.chatwoot.v1 |\n| Provider capability shape | cap:chatwoot: |\n| Full capability count | 150 provider operations plus three AIP composites |\n| Provider authentication | Deployment-owned apiaccesstoken header |\n| Inbound path | Optional POST /webhooks/chatwoot |\n| Streaming and provider cancellation | Not implemented |\n\nThe full 153-capability count applies only when the operation allowlist is\nomitted or contains all 150 provider operations. A deployment may publish an\nexact non-empty subset of the provider catalogue; the three composites remain\npresent.\n\nThese numbers describe the source contract. They do not prove compatibility\nwith an unidentified Chatwoot image, edition, configuration, or extension.\n\nChoose this connector when\n\nThe connector fits an integration that needs to:\n• manage account agents, teams, bots, inboxes, integrations, and webhooks;\n• create, assign, update, search, and report on customer conversations;\n• send messages and manage contacts, companies, labels, and related records;\n• administer automation rules, macros, canned responses, and portal content;\n• consume verified Chatwoot webhook deliveries as durable AIP events;\n• restrict one deployment to an edition-specific or policy-specific operation\n  allowlist.\n\nUse another integration boundary when the task needs an arbitrary Chatwoot\nURL or method, multiple Chatwoot accounts in one connector instance, a\nprovider-native streaming result, or a route absent from the pinned catalogue.\n\nRe-audit and requalify the exact provider and connector artifacts before\nadvancing the Chatwoot source pin.\n\nUnderstand the standalone account boundary\n\nOne connector instance owns one Chatwoot origin and account:\n1. An operator configures the base URL, account ID, and owner-only API token\n   file.\n2. The host optionally applies an exact operation-suffix allowlist.\n3. Registry admission binds the resulting manifest, artifact, tenant, external\n   account, credential revision, instance, and replicas.\n4. An authenticated caller submits an Action to product-neutral getaip-server.\n5. The registry selects the tenant-owned Chatwoot instance and a ready replica.\n6. The host replaces {accountid} with its configured value and encodes the\n   remaining path segments from validated input.\n7. The connector adds the API token and sends one fixed method and route.\n8. The result returns through the durable AIP lifecycle.\n\nThe base URL must be an HTTPS origin without credentials, path, query, or\nfragment. Explicit loopback HTTP is accepted for controlled local use.\nAuthenticated provider requests do not follow redirects.\n\nChanging the account, origin, allowlist, upstream pin, or manifest is a\ndeployment and admission change. Do not treat it as request-level recovery.\n\nChoose a capability family\n\nThe 150 provider operations are organized into eight reader-facing families.\n\n| Family | Operations | Included domains |\n\n| Accounts, agents, teams, and bots | 22 | Account, agents, assignable agents, teams, members, and agent bots |\n| Inboxes, integrations, and webhooks | 21 | Inboxes, members, health, templates, integration hooks, and webhooks |\n| Conversations and messages | 28 | Conversation and message lifecycle, assignment, labels, typing, and attachments |\n| Contacts and companies | 31 | Contact and company lifecycle, notes, merge, import, export, and relations |\n| Automation, macros, and canned responses | 16 | Rules, cloning, macro execution, and canned content |\n| Labels, attributes, and filters | 15 | Labels, custom attribute definitions, and custom filters |\n| Reports, audit, and events | 12 | Reports, summary reports, reporting events, and audit log |\n| Customer portals | 5 | Portals, categories, and articles |\n| Provider catalogue | 150 | Complete frozen operation set |\n\nThe catalogue contains 62 GET, 47 POST, 21 PATCH, and 20 DELETE\noperations. Automation-rule clone, macro execute, and conversation transcript\nare workflows. The other 147 catalogue entries are tools.\n\nThe three AIP composites are separate capabilities:\n\n| Capability | Outcome |\n\n| cap:chatwoot:message:create | Send one public reply or private note and mark it with the AIP Action identity |\n| cap:chatwoot:conversation:status | Set a conversation to open, resolved, or pending |\n| cap:chatwoot:conversation:handoff | Assign a conversation, add a private note, or perform both in sequence |\n\nThe composite handoff is not one atomic Chatwoot transaction. Its focused\nreference page defines partial-effect and recovery decisions.\n\nKeep credentials and account identity outside Actions\n\nEvery provider operation uses the configured account ID. Input schemas omit\naccountid even though the fixed provider templates contain that segment.\nOther path parameters are bounded and encoded as path segments.\n\nThe host reads the API token from an owner-only file and adds it as\napiaccesstoken. It does not accept a token or base URL in Action input.\nThe HTTP client refuses cross-origin redirects, which prevents automatic token\nforwarding to another origin.\n\nUse one connector instance per Chatwoot account and AIP tenant boundary. Give\neach instance its own API token, runtime database role, admission package,\nexternal-account identity, and webhook secret. An upstream token still needs\nthe least Chatwoot privileges required by the admitted suffix set.\n\nApply mutation and retry rules\n\nAll 88 non-GET provider operations require human approval and an AIP\nidempotency key scoped to the external account. The connector forwards the\nAction ID and idempotency key as provider headers for catalogue operations.\nThat header does not prove the selected Chatwoot deployment deduplicates a\nmutation.\n\nProvider catalogue reads declare safe retry support. Mutations declare unsafe\nretry behavior and rollback is not implemented. All three composites require\napproval and idempotency; only the conversation-status composite declares\nretry support.\n\nThe connector has no provider cancellation implementation. If local\ncancellation wins before a provider response, the result is uncertain. Read\nthe original Action and Chatwoot state before deciding whether any mutation can\nbe replaced or reconciled.\n\nCustomer, contact, conversation, and message data is marked restricted,\nPII-bearing, and subject to redaction. Keep raw bodies, attachments, tokens,\nand personal data out of logs and evidence summaries.\n\nTreat webhook ingress as a separate trust path\n\nWebhook ingress is absent when no webhook-secret file is configured. When\nenabled, the standalone host:\n1. limits the exact request body to 1 MiB;\n2. requires delivery, timestamp, and sha256 signature headers;\n3. verifies HMAC over the timestamp, a dot, and the original UTF-8 body;\n4. rejects timestamps outside a five-minute window;\n5. records delivery identity in instance-scoped durable profile state;\n6. ignores messages marked as produced by the Chatwoot connector;\n7. derives a deterministic AIP event ID from the authenticated delivery ID;\n8. appends that event durably before enqueueing central publication.\n\nA provider retry of the same accepted delivery is projected to the same event\nidentity. This supports recovery when a process fails after replay admission\nor event persistence. It does not authorize another outbound response.\n\nAn accepted HTTP response can include a queued central-delivery state. It does\nnot prove every downstream consumer has processed the event.\n\nDeliberate exclusions\n\nThe reviewed connector does not provide:\n• arbitrary provider path, method, origin, or account selection;\n• multiple Chatwoot accounts in one standalone instance;\n• provider credentials from protocol messages or generic credential handles;\n• operation-specific schemas for every upstream request body;\n• native streaming, asynchronous completion, provider cancellation, AIP\n  transactions, reconciliation, or rollback;\n• safe automatic replay of a Chatwoot mutation;\n• a webhook route when verification or central event publication is not\n  configured;\n• compatibility with a Chatwoot revision other than the pinned source;\n• production readiness for an unqualified artifact and deployment.\n\nThe generic catalogue schema bounds paths, query values, JSON bodies, and\nmultipart data. Chatwoot remains responsible for operation-specific semantic\nvalidation.\n\nEvidence status\n\n| Evidence | What it supports | What it does not support |\n\n| Source and 150-route matrix | Implemented account-scoped contract at the reviewed AIP commit | Execution of an unbuilt artifact |\n| Connector unit tests | Deterministic catalogue, request, webhook, replay, and redaction checks exist | A retained pass for a promoted image |\n| Controlled product fleet | Admission of 153 capabilities and selected fixture-backed reads and mutation | Real Chatwoot compatibility |\n| Live-product inventory | No dedicated external Chatwoot harness exists at the pinned revision | Any current isolated-live or production pass |\n\nQualify the exact connector image, Chatwoot artifact, account configuration,\nwebhook path, and failure cases before publishing a readiness claim.\n\nPlan the next task\n\nContinue according to the task you need to complete:\n• use getting-started/quickstart.md for one admitted host and first\n  conversation flow;\n• use the authentication page to bind the tenant, account, and least-privilege\n  token;\n• use the configuration reference for host, ingress, limit, and allowlist\n  settings;\n• open capabilities/README.md to choose one of the eight provider families\n  or three composites;\n• use the webhook and mutation references before enabling inbound events or\n  state changes;\n• use operations and qualification pages before promoting an artifact.\n\nThe global pages below own shared fleet, source-identity, and evidence rules.\n\nRelated documentation\n• Connector documentation (../README.md)\n• Pinned upstream baselines (../upstream-baselines.md)\n• Connector fleet quickstart (../../getting-started/connector-fleet-quickstart.md)\n• Conformance and qualification (../../reference/conformance.md)\n• Live-product qualification (../../testing/live-product-e2e.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "74ed12f4a2e319d9fb1a8c4df2cc9606deca9167a1252471de03c024dd62110b"
  }
}