Chatwoot connector configuration This reference describes the configuration accepted by aip-host-chatwoot at the reviewed source revision. A complete process combines six Chatwoot-specific settings with the shared connector-host identity, storage, routing, lifecycle, and optional event-delivery settings. All product settings are read at startup. Only the shared non-secret credential-revision policy is re-read before provider side effects. Configuration identity | Property | Value | | Binary | aip-host-chatwoot | | AIP workspace version | 1.0.0 | | Reviewed AIP source | 97be86e9efedf07ecf1783b03800f683f107fb04 | | Connector ID | chatwoot | | Connector profile | aip.connector.chatwoot.v1 | | Pinned Chatwoot source | 8818d276b954ac4f84cffd8915c99f40e43804ed | | Full capability surface | 150 catalogue operations plus three composites | Environment variables and flags contain non-secret values or filesystem paths. API tokens, webhook secrets, database credentials, and signing material belong in bounded owner-controlled files. Chatwoot-specific settings | Environment variable | Command-line flag | Required | Default | Meaning | | AIPCHATWOOTBASEURL | --base-url | Yes | None | Fixed Chatwoot origin | | AIPCHATWOOTACCOUNTID | --account-id | Yes | None | Account inserted into every account-scoped route | | AIPCHATWOOTAPITOKENFILE | --api-token-file | Yes | None | Owner-only API-token file | | AIPCHATWOOTWEBHOOKSECRETFILE | --webhook-secret-file | No | Outbound-only host | Owner-only HMAC-secret file | | AIPCHATWOOTMAXRESPONSEBYTES | --max-response-bytes | No | 16777216 | Maximum buffered provider response | | AIPCHATWOOTOPERATIONSFILE | --operations-file | No | All 150 catalogue operations | JSON suffix allowlist | The API-token and webhook-secret readers accept at most 16 KiB. Both files must pass the common secret-file type, ownership, permission, size, UTF-8, and non-empty checks. Provider origin and account The provider base URL must be an origin: • HTTPS is required except for explicit loopback HTTP; • credentials, a path prefix, query, and fragment are rejected; • authenticated redirects are disabled; • the connection timeout is 10 seconds; • the overall provider request timeout is 120 seconds. The account ID must contain 1 to 256 bytes, must not be blank after trimming, and must not contain control characters. It is inserted for {accountid} in every catalogue path and is not exposed as Action input. Response-size setting AIPCHATWOOTMAXRESPONSEBYTES accepts an integer from 1 through 134217728 bytes. Omission uses 16777216 bytes. The connector checks a declared Content-Length and also stops while streaming when accumulated bytes exceed the active limit. An oversized response becomes connector.chatwoot.responsetoolarge and is non-retryable. For an invocation, the connector marks the external outcome uncertain because the provider may have completed before the response was rejected. Operation allowlist file The optional operations file is a JSON array of exact catalogue suffixes. It is a non-secret configuration file with a 128 KiB size bound. [ "account.get", "agent.list", "conversation.list", "message.list" ] Rules: • every value must match one of the 150 compiled suffixes; • an unknown suffix fails startup; • an empty array fails startup; • duplicate suffixes collapse to one operation; • omission enables all 150 catalogue operations; • the three connector-level composites remain available and are not filtered by this file. The allowlist changes the discovered immutable manifest. Advance the connector version and admission material when its effective set changes. Relevant shared host settings The global connector-host reference owns the complete shared matrix. The following groups are required to understand Chatwoot behavior. Identity and route binding | Setting | Role | | AIPCONNECTORHOSTPUBLICENDPOINT | Externally reachable native endpoint ending in /aip/v1/messages | | AIPCONNECTORHOSTTYPEID | Admitted Chatwoot connector type | | AIPCONNECTORHOSTVERSIONID | Immutable admitted version | | AIPCONNECTORHOSTINSTANCEID | Logical one-account instance | | AIPCONNECTORHOSTREPLICAID | Concrete process identity | | AIPCONNECTORHOSTTENANTID | Verified tenant owned by the instance | | AIPCONNECTORHOSTMEMBERSHIPID | Stable membership assertion | | AIPCONNECTORHOSTEXTERNALACCOUNTID | Deployment record for the Chatwoot account | | AIPCONNECTORHOSTEXTERNALACCOUNTSYSTEM | Set to chatwoot with the external-account ID | | AIPCONNECTORHOSTARTIFACTDIGEST | Exact running OCI digest | | AIPCONNECTORHOSTSECRETPROVIDERREF | Non-secret provider reference | The external-account ID and system are an optional pair. A Chatwoot deployment should set them and validate the ID against AIPCHATWOOTACCOUNTID outside the binary; the reviewed code does not compare those two settings. Storage, signing, gateway, and lifecycle | Setting | Required or default | | AIPCONNECTORHOSTBIND | Default 0.0.0.0:8081 | | AIPCONNECTORHOSTDATABASEURLFILE | Required owner-only PostgreSQL URL | | AIPCONNECTORHOSTSIGNINGSEEDFILE | Required owner-only Ed25519 seed | | AIPCONNECTORHOSTCONTROLENDPOINT | Required fixed lifecycle endpoint | | AIPCONNECTORHOSTCONTROLDID or FILE | Exactly one control-plane DID source | | AIPCONNECTORHOSTGATEWAYPRINCIPALID | Required trusted gateway principal | | AIPCONNECTORHOSTGATEWAYDID or FILE | Exactly one gateway DID source | | AIPCONNECTORHOSTTRUSTDOMAIN | Required shared trust domain | | AIPCONNECTORHOSTTLSCAFILE | Optional private-PKI root | | AIPCONNECTORHOSTMAXINFLIGHT | Default 32 | | AIPCONNECTORHOSTLEASETTLMS | Default 30000 | | AIPCONNECTORHOSTHEARTBEATMS | Default 10000 | | AIPCONNECTORHOSTDRAINTIMEOUTMS | Default 30000 | | AIPCONNECTORHOSTHEALTHTIMEOUTMS | Default 2000 | | AIPCONNECTORHOSTCONTROLTIMEOUTMS | Default 5000 | Shared credential ID, issuer, scopes, revision, and revision-policy settings are optional as a complete unit. They fence route authorization; they do not replace the required Chatwoot token file. Choose outbound-only or webhook-enabled mode Outbound-only Omit AIPCHATWOOTWEBHOOKSECRETFILE. The process creates no /webhooks/chatwoot route, and shared central event delivery is not required for startup. The API token remains required because discovery health and outbound capabilities use the account API. Webhook-enabled Set: AIPCHATWOOTWEBHOOKSECRETFILE=/run/secrets/chatwoot-webhook-hmac AIPCONNECTORHOSTEVENTENDPOINT=https://aipd.example.test/aip/v1/connector-events The webhook secret enables POST /webhooks/chatwoot. The central event endpoint becomes mandatory; startup fails if the publisher is absent. Related event settings are: | Environment variable | Default | Meaning | | AIPCONNECTORHOSTEVENTENDPOINT | None | Fixed central event ingress | | AIPCONNECTORHOSTEVENTALLOWHTTP | false | Permit HTTP only for an explicitly controlled deployment | | AIPCONNECTORHOSTEVENTALLOWPRIVATE | false | Permit a private destination explicitly | | AIPCONNECTORHOSTTLSCAFILE | None | Optional CA for event-delivery TLS | Network exceptions without an event endpoint fail configuration. The event destination is host-allowlisted, authenticated by the host signer, and pinned to the admitted event channel. Request and payload limits | Boundary | Reviewed value | | Native AIP request body, common default | 4 MiB | | Provider JSON body encoder | 16 MiB | | Query properties | 128 | | Items in one query array | 256 | | JSON body properties | 512 | | Multipart fields | 512 | | Multipart files | 20 | | One decoded multipart file | 25 MiB | | All decoded multipart fields and files | 64 MiB | | One multipart field | 1 MiB | | One rendered path parameter | 512 bytes | | Provider response, default | 16 MiB | | Provider response, configurable maximum | 128 MiB | | Operations file | 128 KiB | | API token or webhook secret | 16 KiB | | Webhook request body | 1 MiB | | Webhook freshness window | 300 seconds | | Webhook replay identities | 10000 per instance-scoped state set | The effective Action request ceiling is the smallest applicable boundary. A 16 MiB provider JSON encoder does not increase the common 4 MiB native envelope limit. Webhook acceptance and event delivery The webhook route requires: • X-Chatwoot-Delivery with a non-empty delivery identity; • X-Chatwoot-Timestamp parsed as an integer; • X-Chatwoot-Signature in sha256= form; • an original UTF-8 body of at most 1 MiB; • HMAC verification over timestamp, a dot, and the exact body; • a timestamp within five minutes of the host clock. After authentication, instance-scoped durable profile state fences the delivery identity. The host maps a non-looping message to a deterministic AIP event, appends it to the durable event log, and enqueues it on chatwoot-webhooks. A successful JSON response has this shape: { "acceptedevents": 1, "centraldelivery": "centrallyacknowledged" } centraldelivery is: | Value | Meaning | | centrallyacknowledged | Central AIP acknowledged the durable batch before the response | | durablyqueued | The batch is durable locally and the background publisher owns delivery | | null | No event was produced, such as for a connector-marked loop | An HTTP 200 with durablyqueued does not prove downstream consumption. Storage failure returns 503 before successful acceptance. Readiness behavior The Chatwoot product health probe performs an authenticated GET /api/v1/accounts/. A successful response supports reachability and credential validity for that account route. Host readiness also depends on durable storage, admitted identity, lifecycle lease, and common host state. It does not exercise all enabled operations, webhook delivery, approval, mutation safety, or provider compatibility beyond the health read. Startup and reload boundaries | Value | Read | | Provider origin and account | Startup | | API token | Startup | | Webhook secret and route mode | Startup | | Response limit | Startup | | Operation allowlist | Startup | | Common identity, topology, endpoints, and lifecycle limits | Startup | | Credential-revision policy file | Startup, then before provider side effects | Change any startup-owned value through a replacement replica and an admission or configuration revision. Do not edit a running process in place and assume its manifest, token, route, or webhook mode changed. Configuration failures | Failure | Cause or decision | | invalid Chatwoot base URL | Correct the origin; do not relax credentials, path, scheme, or redirect checks | | invalid Chatwoot connector configuration | Check account length, response bound, operation suffixes, and non-empty allowlist | | configured Chatwoot credential is not valid UTF-8 | Repair the owner-only token file without printing it | | Unknown operation suffix | Use an exact compiled suffix or advance the source and admission package | | Webhook ingress requires event endpoint | Configure a valid central endpoint or remove the webhook-secret setting | | Event destination policy rejects the endpoint | Correct TLS, host, and explicit network policy | | webhook.invalidtimestamp | Supply an integer timestamp generated within the freshness window | | webhook.authenticationfailed | Verify exact raw body, timestamp, signature encoding, and secret ownership | | webhook.storageunavailable | Preserve the provider delivery ID and repair durable state before replay | | connector.chatwoot.responsetoolarge | Reconcile provider state before changing limits or retrying a mutation | Related documentation • Chatwoot connector overview (../README.md) • Authenticate and isolate a Chatwoot account (../getting-started/authentication-and-account-isolation.md) • Connector host configuration (../../../reference/connector-host-configuration.md) • Connector host lifecycle (../../../guides/connector-host-lifecycle.md) • Environment variables (../../../reference/environment-variables.md)