Skip to main content
With Chatwoot enabled, GOWA forwards WhatsApp messages (incoming, and outgoing ones sent from the phone) into a Chatwoot API channel inbox, and sends agent replies from Chatwoot back to WhatsApp. Text, images, audio, video, documents, stickers, locations and contacts are supported; group chats appear as one conversation per group, with the sender name prefixed.

Requirements

  • GOWA reachable from Chatwoot over a public URL (for agent-reply webhooks).
  • A Chatwoot account with admin access and a user API access token.
  • At least one logged-in WhatsApp device.

Set up

1

Create an API channel inbox

In Chatwoot go to Settings → Inboxes → Add Inbox → API. Note the numeric inbox ID from the inbox URL, and the webhook secret Chatwoot shows for the channel. Alternatively, let GOWA create the inbox (see Auto-provisioning).
2

Collect IDs and token

The account ID is the number in /app/accounts/<id>/.... Copy a user access token from Profile Settings. Both IDs must be the numeric IDs, not the channel identifier or hmac_token.
3

Configure GOWA

.env
Restart GOWA: the Chatwoot routes are registered at startup.
4

Point Chatwoot at GOWA

Set the API channel’s webhook URL to https://gowa.example.com/chatwoot/webhook (with APP_BASE_PATH, include the base path). This route is public: it is protected by the webhook secret, not Basic Auth.
5

Test

Message the WhatsApp number from another phone; it should appear in the inbox. Reply from Chatwoot and check it arrives on WhatsApp.

Configuration

Most settings also have a --chatwoot-* flag; CHATWOOT_URL, CHATWOOT_API_TOKEN, CHATWOOT_ACCOUNT_ID and CHATWOOT_INBOX_ID are environment-only. See the configuration reference. On GOWA main after v9.9.0, set CHATWOOT_EVENTS=message to keep mirroring messages to Chatwoot while filtering ordinary webhook deliveries separately. The message selector also allows reactions, receipts, edits, and deletes through the Chatwoot filter. The separate read, edit, and delete settings still apply. Leave CHATWOOT_EVENTS empty to inherit WHATSAPP_WEBHOOK_EVENTS. If the effective filter is empty, it allows all supported events. If it excludes message, GOWA logs a warning at startup and stops mirroring WhatsApp messages to Chatwoot. On those builds, GOWA sends the Chatwoot user token in the api-access-token header so nginx can pass it through with its default header settings.

Webhook secret

An empty effective webhook secret rejects the delivery. CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true explicitly permits unsigned delivery when the effective secret is empty. With a secret configured, every request must prove it by one of:
  1. Chatwoot’s signature (X-Chatwoot-Signature + X-Chatwoot-Timestamp), recommended. Use the API channel’s own webhook secret. GOWA checks the HMAC-SHA256 of <timestamp>.<raw body> and rejects timestamps outside the configured tolerance.
  2. An X-Hub-Signature-256 HMAC of the body.
  3. The secret in an X-Chatwoot-Webhook-Secret or X-Gowa-Chatwoot-Secret header.
  4. ?secret= in the webhook URL, only for Chatwoot versions that cannot sign or add headers. The secret then appears in access logs.
Failures return 401; GOWA logs the reason (signature does not match means the wrong secret, timestamp outside the tolerance window means clock drift). The device’s webhook_secret replaces the global secret for that device on both the shared and per-device endpoints. Without a device secret, the global secret applies. GOWA verifies the secret for the routed device before sending, deleting, marking read, or writing data. Prefer the per-device callback URL when several devices use the same account and inbox IDs. A repeated Chatwoot-signed request that already received 2xx is acknowledged with 200 and skipped inside the timestamp window. Failed requests remain retryable. An identical request still in progress can return 503 after waiting up to 30 seconds. Replay memory is local to the process, is lost on restart, and is bounded to 65,536 accepted requests. It is not shared between GOWA instances. Two separately signed deliveries of the same Chatwoot message can still send twice. Body-only HMACs, secret headers, and query secrets do not provide this delivery deduplication.

Auto-provisioning

With CHATWOOT_AUTO_CREATE=true and no CHATWOOT_INBOX_ID, GOWA looks for an API inbox named CHATWOOT_INBOX_NAME at startup and reuses it, or creates one with CHATWOOT_WEBHOOK_URL as its webhook.

One inbox per device

The environment variables configure one destination shared by all devices. To route each device to its own inbox, account or Chatwoot server, store per-device configs (Basic Auth applies):
The response includes webhook_url (<base>/chatwoot/webhook/<device_id>); set it as that inbox’s webhook. Other routes: GET /chatwoot/configs, GET and DELETE /devices/{device_id}/chatwoot/config.
Once any per-device config exists, the CHATWOOT_* destination is no longer used as a fallback. Devices without a config are not mirrored.
  • api_token is stored in GOWA’s database and masked in reads; webhook_secret is never returned.
  • chatwoot_url must be HTTP or HTTPS without credentials. Without CHATWOOT_ALLOWED_HOSTS, private, loopback, link-local, and metadata addresses are rejected. An explicit matching host in CHATWOOT_ALLOWED_HOSTS is trusted and can target self-hosted Chatwoot on a private network. Set this allowlist only to hosts you control.
  • Changing chatwoot_url, account_id or inbox_id after conversations are linked returns 409; delete and recreate the config instead.
  • A config can be created before the device pairs.
  • Direct database import works only in single (environment) config mode.

Replies and formatting

When an agent uses Reply in Chatwoot, GOWA quotes the original WhatsApp message when it can resolve it in the sending device’s local store and the same chat. This applies to text and every attachment, including the audio-to-file fallback. The caption stays on the first attachment only. For an inbound WhatsApp message, GOWA resolves in_reply_to_external_id with the WAID:<id> prefix. For an earlier agent reply, the numeric in_reply_to resolves through a durable message link in the same device, conversation, account, inbox, and config. A message with multiple attachments quotes its first file. If the target cannot be resolved, the reply is delivered without a quote. Incoming WhatsApp replies and reactions thread onto the referenced message in Chatwoot. Agent reply Markdown links and emphasis are converted to readable WhatsApp text. Lists, line breaks, and code are preserved. Empty signature separators are removed. CHATWOOT_SIGN_MSG prefixes the agent’s name after this conversion. Only eligible public outgoing agent messages are sent. Private notes and excluded chats are not forwarded. GOWA uses the configured device and account/inbox identity to route shared callbacks. Per-device callbacks provide an unambiguous route.

Polls and agent deletes

On GOWA main after v9.9.0, Chatwoot mirrors poll creation, edits, and added options. To process individual votes, subscribe to message in WhatsApp webhooks and read the structured poll data. On those builds, set CHATWOOT_REVOKE_ON_DELETE=true to sync deletes from Chatwoot to WhatsApp only. The delete must match durable links to outgoing messages under the active Chatwoot configuration. GOWA revokes each linked WhatsApp message, including attachments sent separately. With CHATWOOT_FORWARD_DELETES=true, deletes from WhatsApp still appear as private notes. Use CHATWOOT_MESSAGE_DELETE=true to delete linked messages in both directions.

Import history

The defaults are days_limit=3, include_media=true, and include_groups=true. The sync reads GOWA’s local chat storage and runs in the background. Each device can run one sync at a time. On GOWA main after v9.9.0, history sync can ask the phone to re-upload expired media. The phone must be online and still have the file. If the phone fails to answer within 30 seconds, the sync skips further re-upload requests for that run and continues importing messages. A message whose file stays unavailable is imported without the attachment. The REST path cannot set original timestamps; imported messages get the import time. For self-hosted Chatwoot, CHATWOOT_IMPORT_DB_URI writes directly to Chatwoot’s PostgreSQL and preserves them. With CHATWOOT_REOPEN_CONVERSATION=true on GOWA main after v9.9.0, history sync only reopens a resolved conversation when it has a new message to import. REST sync reopens the conversation before posting and retries the chat on the next sync if the reopen fails. Direct PostgreSQL import reopens it in the same transaction as the message write. With the setting off, REST sync creates a fresh conversation for new messages, while direct import keeps using the resolved conversation.

Delivery and retries

Live messages that hit a transient Chatwoot error (network error, HTTP 429 or 5xx) are queued in local storage and retried in the background with capped exponential backoff. Other 4xx errors are logged and dropped.

Troubleshooting

Run with APP_DEBUG=true and look for log lines starting with Chatwoot: and Chatwoot Webhook:. The upstream Chatwoot guide covers direct database import and formatting rules in more depth.