Como funciona a recepção de mensagens
Resumo: Toda vez que um cliente manda uma mensagem para um número conectado, o gateway recebe imediatamente e avisa o seu sistema. Você não precisa "buscar" mensagens — elas chegam sozinhas.
Quando usar isso
Para entender o que acontece dos bastidores quando um cliente te manda um WhatsApp ou um Direct do Instagram. Especialmente útil quando você está configurando a plataforma pela primeira vez ou tentando entender por que uma mensagem não chegou.
O fluxo passo a passo
- Cliente envia a mensagem pelo WhatsApp ou Instagram normalmente, do celular dele.
- Meta/WhatsApp recebe e direciona para o gateway (que está conectado ao número como aparelho secundário ou via WABA/Instagram API).
- O gateway processa a mensagem:
- Identifica o canal (qual número/conta foi destinatário)
- Identifica o contato (quem mandou)
- Se for mídia (imagem, áudio, vídeo, documento), baixa o arquivo e armazena temporariamente (por 7 dias)
- Padroniza o formato (não importa se veio de Baileys, WABA ou Instagram — você recebe sempre no mesmo formato)
- Notifica o seu sistema através de um webhook (uma chamada HTTP para a URL configurada).
- Seu sistema processa — salva no banco, envia para o atendente, dispara automação, o que fizer sentido.
Todo esse fluxo leva alguns segundos no total (geralmente menos de 5).
Como meu sistema "ouve" as mensagens novas?
Tem dois jeitos:
1. Webhook (mais comum)
Você configura uma URL pública do seu sistema na hora de criar o canal. Toda vez que algo acontece (mensagem chegou, foi entregue, foi lida, contato reagiu, etc.), o gateway faz uma chamada HTTP POST para essa URL com os dados do evento.
Vantagens:
- Real-time (chega assim que acontece).
- Não precisa manter conexão aberta — é "fire-and-forget".
Veja Webhooks explicado para leigo para entender em detalhe.
2. Streaming (SSE)
Para painéis em tempo real (tipo um inbox que precisa atualizar a tela conforme as mensagens chegam), o gateway tem uma conexão "stream" via Server-Sent Events — uma técnica web onde o servidor empurra atualizações para o navegador.
ℹ️ Saiba mais: SSE (Server-Sent Events) é uma tecnologia web simples — o navegador abre uma conexão e o servidor envia mensagens conforme as coisas acontecem. Geralmente isso já é gerenciado pelo seu painel; você (usuário final) só vê a tela atualizando sozinha.
Quais eventos meu sistema recebe?
Os eventos mais comuns que chegam pelo webhook:
| Evento | Quando acontece |
|---|---|
message:received | Cliente mandou uma mensagem para você |
message:sent | Sua mensagem foi entregue ao WhatsApp/Meta |
message:delivered | A mensagem chegou no celular do cliente |
message:read | O cliente abriu/leu a mensagem (✓✓ azul) |
message:failed | A mensagem falhou (cliente bloqueou, número inexistente, etc.) |
message:reacted | O cliente reagiu com emoji a uma mensagem sua |
message:edited | Cliente editou uma mensagem que ele tinha mandado |
message:deleted | Cliente apagou uma mensagem que tinha mandado |
channel:connected | O canal acabou de conectar |
channel:disconnected | O canal caiu |
channel:qrcode | Um novo QR Code foi gerado (durante conexão Baileys) |
media:transcribed | A transcrição de um áudio recebido ficou pronta |
Dúvidas comuns
Mensagens recebidas antes de eu conectar o canal aparecem? Não. O gateway só "vê" mensagens a partir do momento da conexão. Mensagens anteriores ficam só no celular.
O gateway guarda histórico das mensagens recebidas? Por padrão não. O gateway é "stateless" para mensagens — repassa pro seu sistema e não guarda o conteúdo. Quem precisa armazenar é o seu sistema. Mídias têm uma exceção: ficam por 7 dias para você baixar quando quiser.
Por que isso? Não seria mais fácil consultar o gateway? Por privacidade e custo. Guardar conversas indefinidamente exige consentimento LGPD, espaço caro e levanta riscos de vazamento. O gateway entrega e sai do caminho.
E se meu sistema estiver fora do ar quando uma mensagem chegar? O gateway tenta entregar várias vezes (com retry) por algumas horas. Se mesmo assim não conseguir, a entrega vai para uma "dead letter queue" — uma fila de eventos falhos que pode ser reprocessada manualmente.
Posso testar localmente sem expor minha máquina? Sim. Use ferramentas como ngrok ou Cloudflare Tunnel para criar uma URL pública temporária que aponta para o seu localhost.