[META] Chatwoot integration — tracking umbrella

@lid

Meta-issue consolidating all open Chatwoot-integration reports.
Please do not open new Chatwoot issues — comment here instead.

Known symptoms

Connection / setup

401 Unauthorized when connecting Evolution to Chatwoot
Cannot use internal Docker hostname for Chatwoot URL (Validation Error 400)
Cloudflare routing loops
QR Code generation stuck when Chatwoot integration is auto-enabled

Message delivery (Evolution → Chatwoot)

Group messages sent via API don't appear in Chatwoot
Messages show as empty / blank in Chatwoot
New messages don't appear as "Open" conversations
Outgoing messages show "Waiting for message. This may take a while." after Chatwoot 4.7.0 upgrade
Quoted / reply context lost after recent updates
Audio sending fails (unsupported MIME audio/opus) on Official WhatsApp API
Voice notes don't work
Self-sent messages from linked WhatsApp app appear as outgoing instead of private notes
contactsArrayMessage silently discarded (multi-number contact cards fail)
templateMessage fails to parse ("no body message found")
Backslash added before newlines / trailing newlines in messages
Images don't arrive from Chatwoot

Import / historical data

Contact import only works if Chatwoot is connected before first QR scan
CHATWOOT_IMPORT_DATABASE_CONNECTION_URI must use chatwoot_production DB (not chatwoot)
Historical import fails for @lid conversations despite syncFullHistory=true
Timezone incorrect (UTC-3) on created_at during import

Contact / ID handling

@lid in Chatwoot breaks identification (cross-linked with @lid umbrella)
Argentinian numbers (+549) map incorrectly, creating corrupt contacts
chatwootConversationId is undefined from Meta Ads / catalog (v2.3.4)

Infrastructure / reliability

"Timed out reading data from server" when sending messages (v2.3.7)
Excessive retry behavior causing API overload (polling / Redis backlog)
CHATWOOT_MESSAGE_READ=false has no effect
receiveWebhook causes timeout
Reconnecting an instance (without deleting it) stops forwarding messages — requires server restart

Feature requests

Add linkPreview option to Chatwoot integration (feat: add linkPreview option to Chatwoot integration #2455)
Disable read confirmations on Chatwoot

Known workaround (for historical import)

Connect Chatwoot BEFORE generating the QR Code on a fresh instance
Use CHATWOOT_IMPORT_DATABASE_CONNECTION_URI pointing to chatwoot_production
If messages stop after reconnect: restart the Evolution container or delete & recreate the instance

For maintainers

All duplicate Chatwoot issues are being closed with state_reason: duplicate pointing here. Use this thread as the single source of truth for the integration's health.

Reorganized as a meta-issue as part of the 2026-04 issue triage. Original reporter (@DAVIAMERICO242) and all community contributors remain credited in the comment history.

UP, isso eu já observo há várias versões da evolution, infelizmente sempre que preciso reconectar (leia-se escanear um QRCode), só funciona 1 vez após reiniciar o container da Evolution. Se desconectar por conta de algum erro, ou até mesmo manualmente, ou pra sincronizar, já era... precisa primeiro reiniciar a docker e depois ler o QRCode, ou aparece como conectado mas não aparecem as mensagens recebidas e enviadas pelo aplicativo do Whatsapp. O curioso é que continua enviando mensagem pelo chatwoot.

Same here! I have not been able to find the root cause yet.

@luizcw

@luizcw rapaz sorte a sua, aqui nem reiniciando nem startando do 0 com uma instalação limpa. O chatwood manda, mas ele não recebe de jeito nenhum. Novas conversas não estão sendo criadas sozinhas

vitusan chama 85996144336 eu ajeito pra vc

Olá pessoal, estou com um problema nessa mesma parte, mesmo fazendo o processo de conectar o chatwoot com a evo antes de ler o qrcode, aparece o erro, estou hosteando o chatwoot no portainer. Já tentei adicionar a CHATWOOT_IMPORT_DATABASE_CONNECTION_URI pelas variaveis de ambiente do portainer e nada

Two related findings from debugging our own Evolution + Chatwoot (self-hosted, Baileys channel) setup, in case they help narrow down items already on this list:

1. Message status never reaches "delivered" (only sent → read)

chatwoot.service.ts only handles message creation (status defaults to sent) and the messages.read event (calls update_last_seen on the conversation). There's no handling for the intermediate Baileys delivery ACK (level 2) to update the individual message's status to delivered via the Chatwoot API — even though Chatwoot's own message model supports that status. Agents only ever see sent → read, never the standard delivered checkmark in between.

2. Root cause for "Timed out reading data from server" (already listed above) — at least in our case

Not a networking issue: Chatwoot has its own WEBHOOK_TIMEOUT config (lib/webhooks/trigger.rb, installation_configs table) defaulting to 5 seconds for both open_timeout and read_timeout on outgoing webhook calls (e.g. the call Chatwoot makes to Evolution to deliver an agent's reply). Evolution was actually delivering the message to WhatsApp successfully, but the HTTP response back to Chatwoot occasionally took longer than 5s (going through Cloudflare + reverse proxy, since Chatwoot's own anti-SSRF guard in WebhookJob rejects any webhook_url resolving to a private IP — confirmed you can't point it at an internal Docker hostname, "Cannot use internal Docker hostname for Chatwoot URL" above is the same underlying constraint). Chatwoot would then mark the message as failed with Net::ReadTimeout with #<TCPSocket:(closed)> even though delivery succeeded. Raising WEBHOOK_TIMEOUT to 20s (Chatwoot Super Admin → General Settings) resolved it for us — might be worth Evolution documenting this as a known Chatwoot-side tunable for anyone hitting that symptom.

Environment: Evolution API v2.3.7 (evoapicloud/evolution-api), Chatwoot v4.15.1 self-hosted, native Chatwoot integration, Baileys channel.

Root-caused the templateMessage item on this list ("no body message found").

getTypeMessage() in chatwoot.service.ts has no case for templateMessage
(WhatsApp Business template — common on a contact's first message when it's
sent via WhatsApp Business Platform). No content gets extracted,
eventWhatsapp logs "no body message found" and returns before ever
calling createConversation, so the conversation is silently dropped. It
only shows up later if/when a normal-type message follows (e.g. a reply).

Opened a one-line fix: #2666 — mirrors how templateMessage is already
handled in the getContentMessage() fallback a few lines below, which just
isn't used on this ingestion path. Tested against a live production
instance with a real inbound templateMessage. #

fix: Chatwoot integration drops templateMessage, conversation never c…

Navigation Menu

Repository navigation

[META] Chatwoot integration — tracking umbrella #2014

Known symptoms

Connection / setup

Message delivery (Evolution → Chatwoot)

Import / historical data

Contact / ID handling

Infrastructure / reliability

Feature requests

Known workaround (for historical import)

For maintainers

2 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[META] Chatwoot integration — tracking umbrella #2014

Description

Known symptoms

Connection / setup

Message delivery (Evolution → Chatwoot)

Import / historical data

Contact / ID handling

Infrastructure / reliability

Feature requests

Known workaround (for historical import)

For maintainers

Activity

luizcw commented on Sep 25, 2025

andres99x commented on Sep 25, 2025

vitusan commented on Sep 26, 2025

DAVIAMERICO242 commented on Sep 26, 2025

HectorMouraM commented on Nov 7, 2025

2 remaining items

LouDriu commented on Jul 10, 2026

pbarbagli commented on Jul 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions