Ir para o conteúdo

Guia

Typebot na Evolution API não responde no WhatsApp

A instância do WhatsApp está conectada na Evolution API, o fluxo está pronto no Typebot, você manda uma mensagem e nada volta. Na maioria das vezes não é queda do WhatsApp nem erro de rede: a mensagem para em um de cinco pontos da própria integração entre a Evolution API v2.3.7 e o Typebot v3.19.1.

Neste artigo
  1. 1. TYPEBOT_ENABLED continua false
  2. 2. A URL aponta para o Builder ou tem barra no final
  3. 3. TYPEBOT_API_VERSION está como old no Typebot v3
  4. 4. Fluxo em rascunho ou nome errado no campo typebot
  5. 5. Sessão pausada, gatilho restrito ou teste pelo mesmo número
  6. Resumo para conferir em dois minutos

O diagrama abaixo resume o caminho que uma mensagem percorre e onde ela costuma morrer antes de gerar resposta:

Fluxo de verificação de mensagens entre WhatsApp, Evolution API e Typebot Viewer mostrando os cinco pontos em que o bot para de responder

1. TYPEBOT_ENABLED continua false

No .env.example da Evolution API, a integração vem desligada por padrão (TYPEBOT_ENABLED=false). No código do BaseChatbotController, quando essa chave não está ativa, qualquer chamada em /typebot/* falha com 400 Bad Request (Typebot is disabled), e as mensagens recebidas nem entram no fluxo do bot.

Confira a variável dentro do contêiner em execução:

bash
sudo docker compose exec evolution-api env | grep TYPEBOT

Se TYPEBOT_ENABLED não estiver como true, ajuste o .env ou o docker-compose.yml e recrie o contêiner:

yaml
services:
  evolution-api:
    environment:
      TYPEBOT_ENABLED: "true"
      TYPEBOT_API_VERSION: latest
bash
sudo docker compose up -d evolution-api

Um simples restart não basta quando a variável mudou no docker-compose.yml; use up -d para recriar o contêiner com o ambiente novo.

2. A URL aponta para o Builder ou tem barra no final

O TypebotService da Evolution API concatena o caminho da API direto no campo url salvo na instância:

text
${url}/api/v1/typebots/${typebot}/startChat

Dois erros acontecem aqui:

  • Colocar a URL do Builder (builder.example.com) em vez do Viewer (bot.example.com). O Builder é só o editor visual. Quem responde startChat e continueChat é o typebot-viewer.
  • Deixar uma barra no final (https://bot.example.com/). A concatenação vira https://bot.example.com//api/v1/..., que devolve 404.

Se o Typebot e a Evolution API estiverem no mesmo Docker Compose, use a URL interna http://typebot-viewer:3000 (sem barra no final). Se estiverem em servidores diferentes, use o domínio público do Viewer sem barra (https://bot.example.com).

Teste o Viewer diretamente com curl para eliminar qualquer dúvida sobre rede ou TLS:

bash
curl -i -X POST https://bot.example.com/api/v1/typebots/seu-public-id/startChat \
  -H "Content-Type: application/json" \
  -d '{}'

HTTP 200 com sessionId confirma que a URL e o fluxo existem. HTTP 404 indica endereço errado, barra extra ou fluxo não publicado.

3. TYPEBOT_API_VERSION está como old no Typebot v3

No typebot.service.ts da Evolution API v2.3.7, a variável TYPEBOT_API_VERSION escolhe qual contrato chamar:

Valor de TYPEBOT_API_VERSION Rota chamada pela Evolution API Compatibilidade
latest /api/v1/typebots/<id>/startChat e /api/v1/sessions/<id>/continueChat Typebot atual (v2.18+ e v3.x)
old /api/v1/sendMessage Versões antigas do Typebot

Se o contêiner estiver com TYPEBOT_API_VERSION=old contra um Typebot 3.x, o pedido bate numa rota obsoleta e o erro só aparece nos logs da Evolution API (sudo docker compose logs evolution-api). Deixe TYPEBOT_API_VERSION=latest e recrie o contêiner.

4. Fluxo em rascunho ou nome errado no campo typebot

O campo typebot da Evolution API não aceita o título legível que você deu ao bot no painel (como "Atendimento Principal"). Ele espera o public ID (o slug exibido na aba Share do Typebot, logo depois do domínio do Viewer).

Além disso, um fluxo salvo no editor mas ainda não publicado devolve 404 em startChat. Clique em Publish no Typebot Builder e confira o cadastro salvo na Evolution API:

bash
curl -fsS https://api.example.com/typebot/find/atendimento \
  -H "apikey: $EVOLUTION_API_KEY"

Compare os campos url, typebot e enabled com o que funcionou no teste manual do curl do passo 2.

5. Sessão pausada, gatilho restrito ou teste pelo mesmo número

Mesmo com a API certa, o bot fica calado em quatro situações normais de operação:

  • Teste feito do próprio número do WhatsApp com listeningFromMe: false: a Evolution API ignora mensagens marcadas como enviadas por você. Teste a partir de um segundo número.
  • Atendente humano respondeu antes com stopBotFromMe: true: a sessão do contato muda para paused e o bot não responde mais aquele número até ser reaberto ou expirado.
  • Gatilho por palavra-chave (triggerType: "keyword"): uma mensagem que não bate com triggerOperator e triggerValue não abre sessão.
  • Mensagem enviada em grupo com "@g.us" em ignoreJids: grupos são ignorados de propósito.

Veja o estado atual das sessões usando o id do bot retornado pelo /typebot/find/<instancia>:

bash
curl -fsS https://api.example.com/typebot/fetchSessions/ID_DO_BOT/atendimento \
  -H "apikey: $EVOLUTION_API_KEY"

Se o contato de teste estiver preso em paused ou closed, limpe a sessão daquele número com /typebot/changeStatus/<instancia>:

bash
curl -fsS -X POST https://api.example.com/typebot/changeStatus/atendimento \
  -H "apikey: $EVOLUTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"remoteJid":"[email protected]","status":"delete"}'

Resumo para conferir em dois minutos

Sintoma Onde conferir Correção
/typebot/* devolve Typebot is disabled docker compose exec evolution-api env Definir TYPEBOT_ENABLED=true e recriar
404 ao chamar startChat Campo url no /typebot/find/<instancia> Apontar para o Viewer sem barra no final
Erro em /api/v1/sendMessage nos logs TYPEBOT_API_VERSION Trocar para latest e recriar
404 mesmo com Viewer certo Aba Share e botão Publish no Typebot Publicar o fluxo e usar o publicId
Só um número específico não recebe resposta /typebot/fetchSessions/<botId>/<instancia> Rodar changeStatus com status: "delete"

O Compose completo com Typebot 3.19, Evolution API v2.3.7 e Caddy na mesma máquina está em Typebot e Evolution API na mesma VPS para WhatsApp. Se ainda vai montar o servidor, veja VPS para Evolution API.