Configurar WhatsApp (Evolution API)

O PopinaFlow usa a Evolution API — uma solução auto-hospedada — para enviar mensagens de WhatsApp aos seus clientes. Ela conecta via QR code (como o WhatsApp Web) e não exige conta Business Meta nem aprovação de templates.

O que é enviado automaticamente?

Gatilho	Mensagem enviada
Pedido muda para Em preparo	🍳 "Seu pedido #XXXX está sendo preparado!"
Pedido muda para Pronto	✅ "Seu pedido #XXXX está pronto!"
Pedido muda para Saiu para entrega	🛵 "Seu pedido #XXXX saiu para entrega."
24h antes de uma reserva	Lembrete de confirmação (responder SIM ou NÃO)
2h antes de uma reserva	Segundo lembrete de confirmação
2h após o horário da reserva	Pesquisa NPS de satisfação (nota 0–10)

As mensagens só são enviadas se o cliente informou o telefone no pedido ou reserva.

---

Pré-requisitos

• Docker instalado no servidor onde a Evolution API será hospedada
• Um número de WhatsApp exclusivo para o restaurante (chip ou virtual — não pode ser um número já em uso no celular)

---

Passo a Passo

1. Subir a Evolution API com Docker

Cole no terminal do servidor:

docker run -d \
  --name evolution-api \
  --restart always \
  -p 8080:8080 \
  -e AUTHENTICATION_API_KEY=minha-chave-secreta \
  -e DATABASE_ENABLED=false \
  -v evolution_store:/evolution/store \
  atendai/evolution-api:latest

Troque minha-chave-secreta por uma senha forte. Essa será a EVOLUTION_API_KEY.

Verifique se subiu:

curl http://localhost:8080/
# Deve retornar: {"status": 200, "message": "Welcome to the Evolution API..."}

2. Criar a instância (número)

curl -X POST http://localhost:8080/instance/create \
  -H "apikey: minha-chave-secreta" \
  -H "Content-Type: application/json" \
  -d '{"instanceName": "popina", "qrcode": true}'

Anote o valor de instanceName — será o EVOLUTION_INSTANCE.

3. Conectar o WhatsApp pelo QR Code

curl http://localhost:8080/instance/connect/popina \
  -H "apikey: minha-chave-secreta"

A resposta contém uma URL de imagem do QR code (campo base64). Abra o WhatsApp no celular → Dispositivos Vinculados → Vincular Dispositivo e escaneie.

Verifique a conexão:

curl http://localhost:8080/instance/connectionState/popina \
  -H "apikey: minha-chave-secreta"
# state: "open" = conectado ✓

4. Configurar as variáveis no PopinaFlow

No arquivo backend/.env do servidor PopinaFlow, adicione:

EVOLUTION_API_URL=http://localhost:8080
EVOLUTION_API_KEY=minha-chave-secreta
EVOLUTION_INSTANCE=popina

Se a Evolution API estiver em outro servidor, use o IP ou domínio dele no lugar de localhost.

Reinicie o backend:

docker compose restart api

5. Testar

Crie um pedido de teste e mude o status para Em preparo no painel admin. A mensagem deve chegar em segundos.

Verifique os logs para confirmar:

docker compose logs api | grep -i whatsapp
# Linha com "messageId" = sucesso ✓
# Linha com "not configured" = variáveis não foram carregadas

---

Manter a conexão ativa

O WhatsApp pode desconectar após longos períodos sem uso ou quando o celular fica offline. Para reconectar:

curl http://localhost:8080/instance/connect/popina \
  -H "apikey: minha-chave-secreta"

Escaneie o QR code novamente. Para evitar desconexões, mantenha o celular com bateria e conexão estável.

---

Atualizar a Evolution API

docker pull atendai/evolution-api:latest
docker stop evolution-api && docker rm evolution-api
# Repita o docker run do Passo 1 com os mesmos parâmetros

---

Perguntas Frequentes

O cliente não recebeu a mensagem — o que verificar?

1. Confirme que o telefone foi preenchido com DDD (ex: 11 99999-9999)
2. O PopinaFlow adiciona o código do país +55 automaticamente
3. Verifique o estado da instância: curl .../instance/connectionState/popina -H "apikey: ..."
4. Veja os logs: docker compose logs api | grep -i whatsapp

Posso usar o mesmo número que uso no celular? Não — ao conectar na Evolution API, o número é desconectado do celular. Use um número dedicado.

Existe limite de mensagens? A Evolution API não impõe limite técnico, mas o WhatsApp pode banir números que enviam muitas mensagens em pouco tempo ou com conteúdo suspeito. Para volumes altos, espaçe os envios e evite mensagens com links encurtados.

A Evolution API precisa de internet? Sim — ela precisa de acesso à internet para comunicar com os servidores do WhatsApp. Não funciona em rede local isolada.