{
  "schemaVersion": "1.0",
  "title": "Chatwoot accounts, agents, teams, and bots",
  "description": "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.",
  "canonical": "https://getaip.org/docs/connectors/chatwoot/capabilities/accounts-agents-teams-and-bots",
  "route": "/docs/connectors/chatwoot/capabilities/accounts-agents-teams-and-bots",
  "source": "docs/connectors/chatwoot/capabilities/accounts-agents-teams-and-bots.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/chatwoot/capabilities/accounts-agents-teams-and-bots.md",
    "txt": "/docs/download/connectors/chatwoot/capabilities/accounts-agents-teams-and-bots.txt",
    "json": "/docs/download/connectors/chatwoot/capabilities/accounts-agents-teams-and-bots.json",
    "pdf": "/docs/download/connectors/chatwoot/capabilities/accounts-agents-teams-and-bots.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Chatwoot accounts, agents, teams, and bots\ndescription: >-\n  Choose and invoke the 22 workforce and account capabilities without crossing\n  the configured Chatwoot account boundary\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: chatwoot\ncapabilityIds:\n  - cap:chatwoot:account.get\n  - cap:chatwoot:account.update\n  - cap:chatwoot:agent.list\n  - cap:chatwoot:agent.create\n  - cap:chatwoot:agent.update\n  - cap:chatwoot:agent.delete\n  - cap:chatwoot:agent.bulk_create\n  - cap:chatwoot:agent.assignable.list\n  - cap:chatwoot:team.list\n  - cap:chatwoot:team.create\n  - cap:chatwoot:team.get\n  - cap:chatwoot:team.update\n  - cap:chatwoot:team.delete\n  - cap:chatwoot:team.member.list\n  - cap:chatwoot:team.member.create\n  - cap:chatwoot:team.member.update\n  - cap:chatwoot:team.member.delete\n  - cap:chatwoot:agent_bot.list\n  - cap:chatwoot:agent_bot.create\n  - cap:chatwoot:agent_bot.get\n  - cap:chatwoot:agent_bot.update\n  - cap:chatwoot:agent_bot.delete\naliases:\n  - Chatwoot workforce capabilities\n  - Chatwoot account administration\n---\n\n# Chatwoot accounts, agents, teams, and bots\n\nUse these 22 capabilities to read the configured account and manage its human\nagents, teams, team membership, and agent bots. The connector owns the account\nboundary; an Action cannot select another Chatwoot account through its input.\n\nThis page documents the exact routes and the generic AIP request envelope\nfrozen in the reviewed source. It does not invent provider payload fields that\nthe Rust catalogue does not validate.\n\n## Family at a glance\n\n| Group | Operations | Reads | Mutations | High-risk deletes |\n|---|---:|---:|---:|---:|\n| Account | 2 | 1 | 1 | 0 |\n| Agents | 6 | 2 | 4 | 1 |\n| Teams and members | 9 | 3 | 6 | 2 |\n| Agent bots | 5 | 2 | 3 | 1 |\n| **Total** | **22** | **8** | **14** | **4** |\n\nAll 22 capabilities are Tools. The eight `GET` operations are low-risk reads.\nThe five `POST` and five `PATCH` operations are medium-risk mutations. The four\n`DELETE` operations are high-risk mutations.\n\nEvery mutation requires approval and an idempotency key. Reads do not require\ncapability-level approval and advertise safe retry support.\n\n## Account and agent operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:account.get` | `GET /api/v1/accounts/{account_id}` | Read the configured account | Low | No |\n| `cap:chatwoot:account.update` | `PATCH /api/v1/accounts/{account_id}` | Update the configured account | Medium | Required |\n| `cap:chatwoot:agent.list` | `GET /api/v1/accounts/{account_id}/agents` | List account agents | Low | No |\n| `cap:chatwoot:agent.create` | `POST /api/v1/accounts/{account_id}/agents` | Create an agent | Medium | Required |\n| `cap:chatwoot:agent.update` | `PATCH /api/v1/accounts/{account_id}/agents/{agent_id}` | Update one agent | Medium | Required |\n| `cap:chatwoot:agent.delete` | `DELETE /api/v1/accounts/{account_id}/agents/{agent_id}` | Delete one agent | High | Required |\n| `cap:chatwoot:agent.bulk_create` | `POST /api/v1/accounts/{account_id}/agents/bulk_create` | Create agents in one bounded provider request | Medium | Required |\n| `cap:chatwoot:agent.assignable.list` | `GET /api/v1/accounts/{account_id}/assignable_agents` | List agents available for assignment | Low | No |\n\n`agent.bulk_create` is one provider mutation. The catalogue does not define a\nper-item transaction, partial-success model, or compensating operation.\nPreserve the provider result before deciding how to recover a partial import.\n\n## Team and membership operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:team.list` | `GET /api/v1/accounts/{account_id}/teams` | List teams | Low | No |\n| `cap:chatwoot:team.create` | `POST /api/v1/accounts/{account_id}/teams` | Create a team | Medium | Required |\n| `cap:chatwoot:team.get` | `GET /api/v1/accounts/{account_id}/teams/{team_id}` | Read one team | Low | No |\n| `cap:chatwoot:team.update` | `PATCH /api/v1/accounts/{account_id}/teams/{team_id}` | Update one team | Medium | Required |\n| `cap:chatwoot:team.delete` | `DELETE /api/v1/accounts/{account_id}/teams/{team_id}` | Delete one team | High | Required |\n| `cap:chatwoot:team.member.list` | `GET /api/v1/accounts/{account_id}/teams/{team_id}/team_members` | List team members | Low | No |\n| `cap:chatwoot:team.member.create` | `POST /api/v1/accounts/{account_id}/teams/{team_id}/team_members` | Add team members | Medium | Required |\n| `cap:chatwoot:team.member.update` | `PATCH /api/v1/accounts/{account_id}/teams/{team_id}/team_members` | Replace team members | Medium | Required |\n| `cap:chatwoot:team.member.delete` | `DELETE /api/v1/accounts/{account_id}/teams/{team_id}/team_members` | Remove team members | High | Required |\n\nThe three membership mutations share one collection route. Their provider\nmethods distinguish add, replace, and remove behavior. Review the exact member\nset in the approved body, especially before `team.member.update`.\n\n## Agent-bot operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:agent_bot.list` | `GET /api/v1/accounts/{account_id}/agent_bots` | List agent bots | Low | No |\n| `cap:chatwoot:agent_bot.create` | `POST /api/v1/accounts/{account_id}/agent_bots` | Create an agent bot | Medium | Required |\n| `cap:chatwoot:agent_bot.get` | `GET /api/v1/accounts/{account_id}/agent_bots/{agent_bot_id}` | Read one agent bot | Low | No |\n| `cap:chatwoot:agent_bot.update` | `PATCH /api/v1/accounts/{account_id}/agent_bots/{agent_bot_id}` | Update one agent bot | Medium | Required |\n| `cap:chatwoot:agent_bot.delete` | `DELETE /api/v1/accounts/{account_id}/agent_bots/{agent_bot_id}` | Delete one agent bot | High | Required |\n\nAgent-bot records can influence automated handling in Chatwoot, but the generic\ncontract declares only `write` and `external_network` side effects. Apply\nprovider-aware policy without treating the generic markers as an exhaustive\nimpact model.\n\n## Account and path inputs\n\nThe host inserts its configured `account_id` into every provider path. Do not\nput `account_id` in Action input; it is not present in the published input\nschema.\n\nThe remaining placeholders become required top-level strings:\n\n| Input | Required by |\n|---|---|\n| `agent_id` | `agent.update` and `agent.delete` |\n| `team_id` | `team.get`, `team.update`, `team.delete`, and all four `team.member.*` operations |\n| `agent_bot_id` | `agent_bot.get`, `agent_bot.update`, and `agent_bot.delete` |\n\nEach path value must be non-blank, contain no control character, and fit within\n512 bytes. The URL builder inserts it as one encoded path segment. A caller\ncannot use a slash inside the value to select another route.\n\n## Generic catalogue input\n\nEvery operation accepts the same source-generated envelope around its path\ninputs:\n\n| Property | Shape | Connector boundary |\n|---|---|---|\n| Path inputs | Required strings for placeholders other than `account_id` | Non-blank; at most 512 bytes |\n| `query` | Optional object of scalar values or scalar arrays | At most 128 keys and 256 values per array |\n| `body` | Optional JSON object | At most 512 properties and 16 MiB when encoded |\n| `multipart` | Optional fields-and-files object | Mutually exclusive with `body` |\n\nA null query value is omitted. String, number, integer, and Boolean values are\nencoded as query values. Nested query objects are rejected.\n\nThe connector does not freeze operation-specific body fields for this family.\nIt validates only that `body` is an object within the generic bounds, then\npasses it to the pinned provider route. Use the provider schema admitted for\nthe pinned Chatwoot revision. Do not infer that a schema-valid empty object is\na valid provider mutation.\n\nThe same generic input technically permits multipart data. Use it only when\nthe pinned provider operation explicitly accepts multipart content. These 22\ncatalogue entries publish no operation-specific multipart requirement.\n\n## Read an assignable-agent list\n\nSelect the capability from tenant discovery, then send only the provider query\nthat the admitted route needs:\n\n```sh\naipctl action call \\\n  \"$AIP_URL\" \\\n  cap:chatwoot:agent.assignable.list \\\n  --action-id act_chatwoot_assignable_agents_001 \\\n  --input '{\"query\":{\"page\":1}}'\n```\n\nThe connector inserts the account and calls:\n\n```text\nGET /api/v1/accounts/{configured_account_id}/assignable_agents?page=1\n```\n\nThe read is safe to retry at the capability-contract level. A retry still\nrequires the same tenant route, deadline, and policy context. It can return a\ndifferent list if Chatwoot state changed between calls.\n\n## Update an agent\n\nThe pinned connector fixture demonstrates this exact generic input:\n\n```json\n{\n  \"agent_id\": \"42\",\n  \"body\": {\n    \"name\": \"Operations\"\n  }\n}\n```\n\nSubmit it as one governed Action:\n\n```sh\naipctl action call \\\n  \"$AIP_URL\" \\\n  cap:chatwoot:agent.update \\\n  --action-id act_chatwoot_agent_update_001 \\\n  --idempotency-key agent-update-42-v1 \\\n  --input '{\"agent_id\":\"42\",\"body\":{\"name\":\"Operations\"}}'\n```\n\nExpected first outcome: the policy path may hold the Action for approval. The\napproval must bind this capability, agent ID, body, Action identity, actor,\ntenant, and policy hash.\n\nAfter authorization, the connector sends `PATCH` to the configured account,\nadds `X-AIP-Action-ID` and `Idempotency-Key`, and uses the configured\n`api_access_token`. Do not place the token in Action input or evidence.\n\n## Mutation safety\n\nAll 14 mutations share this AIP contract:\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| Collision behavior | Revalidate input hash |\n| Connector retry support | No |\n| Retry safety | 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\nAn idempotency key binds one intent inside the external-account scope. The\nconnector forwards that key to Chatwoot, but the contract does not prove that\nevery pinned provider route deduplicates requests.\n\nIf dispatch may have occurred, retain the original Action and key. Inspect\nauthoritative Chatwoot state before any corrective mutation. Do not create a\nnew Action merely because the original response was lost.\n\n## Result contract\n\nA successful catalogue call returns:\n\n```json\n{\n  \"http_status\": 200,\n  \"body\": {},\n  \"provider_request_id\": null\n}\n```\n\n`http_status` contains the successful provider status. `body` contains parsed\nJSON, `null` for an empty response, or `{\"text\":\"...\"}` for a non-JSON body.\n`provider_request_id` uses `x-request-id` when present and falls back to\n`x-runtime`.\n\nThe default response bound is 16 MiB and configuration can raise it only to\nthe connector's hard 128 MiB ceiling. A successful HTTP response that exceeds\nthe active bound fails before an Action result is returned.\n\nProvider response fields remain provider-owned. Preserve unknown fields and\nvalidate the specific object shape required by the application.\n\n## Failures and recovery\n\n| Failure code | Typical cause | Safe response |\n|---|---|---|\n| `connector.chatwoot.invalid_action` | Unknown, unadmitted, or malformed capability input | Refresh discovery or correct the path/query/body input |\n| `connector.chatwoot.missing_idempotency_key` | Mutation has no valid key | Restore the key bound to the original intent before dispatch |\n| `connector.chatwoot.authentication` | Provider returned `401` or `403` | Verify account binding and credential revision |\n| `connector.chatwoot.remote_rejected` | Provider rejected another client request | Correct provider state or payload 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 a mutation outcome as uncertain |\n| `connector.chatwoot.response_too_large` | Response crossed the configured bound | Inspect provider output and the reviewed bound; reconcile a mutation |\n| `connector.chatwoot.invalid_credential` | Configured token is not usable UTF-8 | Rotate or replace the owner-only credential |\n\nThe failure mapping sets `retryable` to false for every connector failure.\nThat prevents an error from instructing a blind retry. The capability contract\nseparately permits bounded retries for the eight reads.\n\nTransport, temporary provider, and oversized-response failures mark an\ninvocation outcome uncertain. For a mutation, uncertainty means the provider\nmay already contain the change. Read authoritative state before deciding on a\nseparately approved correction.\n\n## Verify an integration\n\nRequire all of the following:\n\n- tenant discovery returns only the admitted family operations;\n- the Action contains no caller-selected account ID;\n- each non-account path placeholder is present and bound to the intended\n  provider object;\n- every mutation has exact approval evidence and one retained idempotency key;\n- the completed result belongs to the submitted Action and preserves provider\n  status and request identity;\n- a read-back confirms consequential writes when the provider offers one;\n- restricted account, agent, team, and bot data follows tenant redaction and\n  retention policy;\n- uncertain mutations are reconciled instead of repeated.\n\nThese checks validate application handling. They do not establish live\nqualification of a Chatwoot version or permission to administer every object\nin the configured account.\n\n## Related documentation\n\n- [Chatwoot capability index](README.md)\n- [Authentication and account isolation](../getting-started/authentication-and-account-isolation.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 accounts, agents, teams, and bots\n\nUse these 22 capabilities to read the configured account and manage its human\nagents, teams, team membership, and agent bots. The connector owns the account\nboundary; an Action cannot select another Chatwoot account through its input.\n\nThis page documents the exact routes and the generic AIP request envelope\nfrozen in the reviewed source. It does not invent provider payload fields that\nthe Rust catalogue does not validate.\n\nFamily at a glance\n\n| Group | Operations | Reads | Mutations | High-risk deletes |\n\n| Account | 2 | 1 | 1 | 0 |\n| Agents | 6 | 2 | 4 | 1 |\n| Teams and members | 9 | 3 | 6 | 2 |\n| Agent bots | 5 | 2 | 3 | 1 |\n| Total | 22 | 8 | 14 | 4 |\n\nAll 22 capabilities are Tools. The eight GET operations are low-risk reads.\nThe five POST and five PATCH operations are medium-risk mutations. The four\nDELETE operations are high-risk mutations.\n\nEvery mutation requires approval and an idempotency key. Reads do not require\ncapability-level approval and advertise safe retry support.\n\nAccount and agent operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:account.get | GET /api/v1/accounts/{accountid} | Read the configured account | Low | No |\n| cap:chatwoot:account.update | PATCH /api/v1/accounts/{accountid} | Update the configured account | Medium | Required |\n| cap:chatwoot:agent.list | GET /api/v1/accounts/{accountid}/agents | List account agents | Low | No |\n| cap:chatwoot:agent.create | POST /api/v1/accounts/{accountid}/agents | Create an agent | Medium | Required |\n| cap:chatwoot:agent.update | PATCH /api/v1/accounts/{accountid}/agents/{agentid} | Update one agent | Medium | Required |\n| cap:chatwoot:agent.delete | DELETE /api/v1/accounts/{accountid}/agents/{agentid} | Delete one agent | High | Required |\n| cap:chatwoot:agent.bulkcreate | POST /api/v1/accounts/{accountid}/agents/bulkcreate | Create agents in one bounded provider request | Medium | Required |\n| cap:chatwoot:agent.assignable.list | GET /api/v1/accounts/{accountid}/assignableagents | List agents available for assignment | Low | No |\n\nagent.bulkcreate is one provider mutation. The catalogue does not define a\nper-item transaction, partial-success model, or compensating operation.\nPreserve the provider result before deciding how to recover a partial import.\n\nTeam and membership operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:team.list | GET /api/v1/accounts/{accountid}/teams | List teams | Low | No |\n| cap:chatwoot:team.create | POST /api/v1/accounts/{accountid}/teams | Create a team | Medium | Required |\n| cap:chatwoot:team.get | GET /api/v1/accounts/{accountid}/teams/{teamid} | Read one team | Low | No |\n| cap:chatwoot:team.update | PATCH /api/v1/accounts/{accountid}/teams/{teamid} | Update one team | Medium | Required |\n| cap:chatwoot:team.delete | DELETE /api/v1/accounts/{accountid}/teams/{teamid} | Delete one team | High | Required |\n| cap:chatwoot:team.member.list | GET /api/v1/accounts/{accountid}/teams/{teamid}/teammembers | List team members | Low | No |\n| cap:chatwoot:team.member.create | POST /api/v1/accounts/{accountid}/teams/{teamid}/teammembers | Add team members | Medium | Required |\n| cap:chatwoot:team.member.update | PATCH /api/v1/accounts/{accountid}/teams/{teamid}/teammembers | Replace team members | Medium | Required |\n| cap:chatwoot:team.member.delete | DELETE /api/v1/accounts/{accountid}/teams/{teamid}/teammembers | Remove team members | High | Required |\n\nThe three membership mutations share one collection route. Their provider\nmethods distinguish add, replace, and remove behavior. Review the exact member\nset in the approved body, especially before team.member.update.\n\nAgent-bot operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:agentbot.list | GET /api/v1/accounts/{accountid}/agentbots | List agent bots | Low | No |\n| cap:chatwoot:agentbot.create | POST /api/v1/accounts/{accountid}/agentbots | Create an agent bot | Medium | Required |\n| cap:chatwoot:agentbot.get | GET /api/v1/accounts/{accountid}/agentbots/{agentbotid} | Read one agent bot | Low | No |\n| cap:chatwoot:agentbot.update | PATCH /api/v1/accounts/{accountid}/agentbots/{agentbotid} | Update one agent bot | Medium | Required |\n| cap:chatwoot:agentbot.delete | DELETE /api/v1/accounts/{accountid}/agentbots/{agentbotid} | Delete one agent bot | High | Required |\n\nAgent-bot records can influence automated handling in Chatwoot, but the generic\ncontract declares only write and externalnetwork side effects. Apply\nprovider-aware policy without treating the generic markers as an exhaustive\nimpact model.\n\nAccount and path inputs\n\nThe host inserts its configured accountid into every provider path. Do not\nput accountid in Action input; it is not present in the published input\nschema.\n\nThe remaining placeholders become required top-level strings:\n\n| Input | Required by |\n\n| agentid | agent.update and agent.delete |\n| teamid | team.get, team.update, team.delete, and all four team.member. operations |\n| agentbotid | agentbot.get, agentbot.update, and agentbot.delete |\n\nEach path value must be non-blank, contain no control character, and fit within\n512 bytes. The URL builder inserts it as one encoded path segment. A caller\ncannot use a slash inside the value to select another route.\n\nGeneric catalogue input\n\nEvery operation accepts the same source-generated envelope around its path\ninputs:\n\n| Property | Shape | Connector boundary |\n\n| Path inputs | Required strings for placeholders other than accountid | Non-blank; at most 512 bytes |\n| query | Optional object of scalar values or scalar arrays | At most 128 keys and 256 values per array |\n| body | Optional JSON object | At most 512 properties and 16 MiB when encoded |\n| multipart | Optional fields-and-files object | Mutually exclusive with body |\n\nA null query value is omitted. String, number, integer, and Boolean values are\nencoded as query values. Nested query objects are rejected.\n\nThe connector does not freeze operation-specific body fields for this family.\nIt validates only that body is an object within the generic bounds, then\npasses it to the pinned provider route. Use the provider schema admitted for\nthe pinned Chatwoot revision. Do not infer that a schema-valid empty object is\na valid provider mutation.\n\nThe same generic input technically permits multipart data. Use it only when\nthe pinned provider operation explicitly accepts multipart content. These 22\ncatalogue entries publish no operation-specific multipart requirement.\n\nRead an assignable-agent list\n\nSelect the capability from tenant discovery, then send only the provider query\nthat the admitted route needs:\n\naipctl action call \\\n  \"$AIPURL\" \\\n  cap:chatwoot:agent.assignable.list \\\n  --action-id actchatwootassignableagents001 \\\n  --input '{\"query\":{\"page\":1}}'\n\nThe connector inserts the account and calls:\n\nGET /api/v1/accounts/{configuredaccountid}/assignableagents?page=1\n\nThe read is safe to retry at the capability-contract level. A retry still\nrequires the same tenant route, deadline, and policy context. It can return a\ndifferent list if Chatwoot state changed between calls.\n\nUpdate an agent\n\nThe pinned connector fixture demonstrates this exact generic input:\n\n{\n  \"agentid\": \"42\",\n  \"body\": {\n    \"name\": \"Operations\"\n  }\n}\n\nSubmit it as one governed Action:\n\naipctl action call \\\n  \"$AIPURL\" \\\n  cap:chatwoot:agent.update \\\n  --action-id actchatwootagentupdate001 \\\n  --idempotency-key agent-update-42-v1 \\\n  --input '{\"agentid\":\"42\",\"body\":{\"name\":\"Operations\"}}'\n\nExpected first outcome: the policy path may hold the Action for approval. The\napproval must bind this capability, agent ID, body, Action identity, actor,\ntenant, and policy hash.\n\nAfter authorization, the connector sends PATCH to the configured account,\nadds X-AIP-Action-ID and Idempotency-Key, and uses the configured\napiaccesstoken. Do not place the token in Action input or evidence.\n\nMutation safety\n\nAll 14 mutations share this AIP contract:\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| Collision behavior | Revalidate input hash |\n| Connector retry support | No |\n| Retry safety | 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\nAn idempotency key binds one intent inside the external-account scope. The\nconnector forwards that key to Chatwoot, but the contract does not prove that\nevery pinned provider route deduplicates requests.\n\nIf dispatch may have occurred, retain the original Action and key. Inspect\nauthoritative Chatwoot state before any corrective mutation. Do not create a\nnew Action merely because the original response was lost.\n\nResult contract\n\nA successful catalogue call returns:\n\n{\n  \"httpstatus\": 200,\n  \"body\": {},\n  \"providerrequestid\": null\n}\n\nhttpstatus contains the successful provider status. body contains parsed\nJSON, null for an empty response, or {\"text\":\"...\"} for a non-JSON body.\nproviderrequestid uses x-request-id when present and falls back to\nx-runtime.\n\nThe default response bound is 16 MiB and configuration can raise it only to\nthe connector's hard 128 MiB ceiling. A successful HTTP response that exceeds\nthe active bound fails before an Action result is returned.\n\nProvider response fields remain provider-owned. Preserve unknown fields and\nvalidate the specific object shape required by the application.\n\nFailures and recovery\n\n| Failure code | Typical cause | Safe response |\n\n| connector.chatwoot.invalidaction | Unknown, unadmitted, or malformed capability input | Refresh discovery or correct the path/query/body input |\n| connector.chatwoot.missingidempotencykey | Mutation has no valid key | Restore the key bound to the original intent before dispatch |\n| connector.chatwoot.authentication | Provider returned 401 or 403 | Verify account binding and credential revision |\n| connector.chatwoot.remoterejected | Provider rejected another client request | Correct provider state or payload 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 a mutation outcome as uncertain |\n| connector.chatwoot.responsetoolarge | Response crossed the configured bound | Inspect provider output and the reviewed bound; reconcile a mutation |\n| connector.chatwoot.invalidcredential | Configured token is not usable UTF-8 | Rotate or replace the owner-only credential |\n\nThe failure mapping sets retryable to false for every connector failure.\nThat prevents an error from instructing a blind retry. The capability contract\nseparately permits bounded retries for the eight reads.\n\nTransport, temporary provider, and oversized-response failures mark an\ninvocation outcome uncertain. For a mutation, uncertainty means the provider\nmay already contain the change. Read authoritative state before deciding on a\nseparately approved correction.\n\nVerify an integration\n\nRequire all of the following:\n• tenant discovery returns only the admitted family operations;\n• the Action contains no caller-selected account ID;\n• each non-account path placeholder is present and bound to the intended\n  provider object;\n• every mutation has exact approval evidence and one retained idempotency key;\n• the completed result belongs to the submitted Action and preserves provider\n  status and request identity;\n• a read-back confirms consequential writes when the provider offers one;\n• restricted account, agent, team, and bot data follows tenant redaction and\n  retention policy;\n• uncertain mutations are reconciled instead of repeated.\n\nThese checks validate application handling. They do not establish live\nqualification of a Chatwoot version or permission to administer every object\nin the configured account.\n\nRelated documentation\n• Chatwoot capability index (README.md)\n• Authentication and account isolation (../getting-started/authentication-and-account-isolation.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": "a6021096c296de8aba2c929fc0f1533bc18737a845900cf26427b912b979c5a8"
  }
}