---
title: Chatwoot connector configuration
description: >-
  Look up Chatwoot host settings, defaults, limits, webhook dependencies, and
  reload boundaries
kind: reference
audience: operator
appliesTo: "1.x"
writingStandard: "aip-docs/1.0"
lastReviewedRevision: "97be86e9efedf07ecf1783b03800f683f107fb04"
connector: chatwoot
aliases:
  - Chatwoot environment variables
  - Chatwoot host settings
  - Chatwoot limits
---

# 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 |
|---|---|---:|---|---|
| `AIP_CHATWOOT_BASE_URL` | `--base-url` | Yes | None | Fixed Chatwoot origin |
| `AIP_CHATWOOT_ACCOUNT_ID` | `--account-id` | Yes | None | Account inserted into every account-scoped route |
| `AIP_CHATWOOT_API_TOKEN_FILE` | `--api-token-file` | Yes | None | Owner-only API-token file |
| `AIP_CHATWOOT_WEBHOOK_SECRET_FILE` | `--webhook-secret-file` | No | Outbound-only host | Owner-only HMAC-secret file |
| `AIP_CHATWOOT_MAX_RESPONSE_BYTES` | `--max-response-bytes` | No | `16777216` | Maximum buffered provider response |
| `AIP_CHATWOOT_OPERATIONS_FILE` | `--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
`{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.

```json
[
  "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 |
|---|---|
| `AIP_CONNECTOR_HOST_PUBLIC_ENDPOINT` | Externally reachable native endpoint ending in `/aip/v1/messages` |
| `AIP_CONNECTOR_HOST_TYPE_ID` | Admitted Chatwoot connector type |
| `AIP_CONNECTOR_HOST_VERSION_ID` | Immutable admitted version |
| `AIP_CONNECTOR_HOST_INSTANCE_ID` | Logical one-account instance |
| `AIP_CONNECTOR_HOST_REPLICA_ID` | Concrete process identity |
| `AIP_CONNECTOR_HOST_TENANT_ID` | Verified tenant owned by the instance |
| `AIP_CONNECTOR_HOST_MEMBERSHIP_ID` | Stable membership assertion |
| `AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_ID` | Deployment record for the Chatwoot account |
| `AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_SYSTEM` | Set to `chatwoot` with the external-account ID |
| `AIP_CONNECTOR_HOST_ARTIFACT_DIGEST` | Exact running OCI digest |
| `AIP_CONNECTOR_HOST_SECRET_PROVIDER_REF` | 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 `AIP_CHATWOOT_ACCOUNT_ID` outside
the binary; the reviewed code does not compare those two settings.

### Storage, signing, gateway, and lifecycle

| Setting | Required or default |
|---|---|
| `AIP_CONNECTOR_HOST_BIND` | Default `0.0.0.0:8081` |
| `AIP_CONNECTOR_HOST_DATABASE_URL_FILE` | Required owner-only PostgreSQL URL |
| `AIP_CONNECTOR_HOST_SIGNING_SEED_FILE` | Required owner-only Ed25519 seed |
| `AIP_CONNECTOR_HOST_CONTROL_ENDPOINT` | Required fixed lifecycle endpoint |
| `AIP_CONNECTOR_HOST_CONTROL_DID` or `_FILE` | Exactly one control-plane DID source |
| `AIP_CONNECTOR_HOST_GATEWAY_PRINCIPAL_ID` | Required trusted gateway principal |
| `AIP_CONNECTOR_HOST_GATEWAY_DID` or `_FILE` | Exactly one gateway DID source |
| `AIP_CONNECTOR_HOST_TRUST_DOMAIN` | Required shared trust domain |
| `AIP_CONNECTOR_HOST_TLS_CA_FILE` | Optional private-PKI root |
| `AIP_CONNECTOR_HOST_MAX_IN_FLIGHT` | Default `32` |
| `AIP_CONNECTOR_HOST_LEASE_TTL_MS` | Default `30000` |
| `AIP_CONNECTOR_HOST_HEARTBEAT_MS` | Default `10000` |
| `AIP_CONNECTOR_HOST_DRAIN_TIMEOUT_MS` | Default `30000` |
| `AIP_CONNECTOR_HOST_HEALTH_TIMEOUT_MS` | Default `2000` |
| `AIP_CONNECTOR_HOST_CONTROL_TIMEOUT_MS` | 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 `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:

```text
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:

| Environment variable | Default | Meaning |
|---|---:|---|
| `AIP_CONNECTOR_HOST_EVENT_ENDPOINT` | None | Fixed central event ingress |
| `AIP_CONNECTOR_HOST_EVENT_ALLOW_HTTP` | `false` | Permit HTTP only for an explicitly controlled deployment |
| `AIP_CONNECTOR_HOST_EVENT_ALLOW_PRIVATE` | `false` | Permit a private destination explicitly |
| `AIP_CONNECTOR_HOST_TLS_CA_FILE` | 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=<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:

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

`central_delivery` is:

| Value | Meaning |
|---|---|
| `centrally_acknowledged` | Central AIP acknowledged the durable batch before the response |
| `durably_queued` | 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 `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

| 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.invalid_timestamp` | Supply an integer timestamp generated within the freshness window |
| `webhook.authentication_failed` | Verify exact raw body, timestamp, signature encoding, and secret ownership |
| `webhook.storage_unavailable` | Preserve the provider delivery ID and repair durable state before replay |
| `connector.chatwoot.response_too_large` | 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)