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

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

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 {account_id} in every catalogue path and is not exposed as Action input.

Response-size setting

AIP_CHATWOOT_MAX_RESPONSE_BYTES 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.response_too_large 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

The external-account ID and system are an optional pair. A Chatwoot deployment should set them and validate the ID against AIP_CHATWOOT_ACCOUNT_ID outside the binary; the reviewed code does not compare those two settings.

Storage, signing, gateway, and lifecycle

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 AIP_CHATWOOT_WEBHOOK_SECRET_FILE. 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:

AIP_CHATWOOT_WEBHOOK_SECRET_FILE=/run/secrets/chatwoot-webhook-hmac
AIP_CONNECTOR_HOST_EVENT_ENDPOINT=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:

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

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=<hex> 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:

{
  "accepted_events": 1,
  "central_delivery": "centrally_acknowledged"
}

central_delivery is:

An HTTP 200 with durably_queued 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/<configured-account>. 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

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

Related documentation

• Chatwoot connector overview
• Authenticate and isolate a Chatwoot account
• Connector host configuration
• Connector host lifecycle
• Environment variables