Conectar número WhatsApp na EvolutionAPI

Este guia leva você do servidor com EvolutionAPI já rodando até a primeira mensagem entregando webhook na sua API. Tempo total: ~10 minutos.

Pré-requisitos

• EvolutionAPI rodando em domínio HTTPS público (ex: https://evo.sua-empresa.com.br)
• AUTHENTICATION_API_KEY definido no .env da EvolutionAPI
• Número WhatsApp dedicado (não use seu pessoal)
• Acesso ao celular para escanear o QR Code

Passo 1 — criar a instância

curl -X POST https://evo.sua-empresa.com.br/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: SEU_API_KEY" \
  -d '{
    "instanceName": "atendimento",
    "qrcode": true,
    "integration": "WHATSAPP-BAILEYS"
  }'

A resposta é algo como:

{
  "instance": {
    "instanceName": "atendimento",
    "instanceId": "abc-123",
    "status": "created"
  },
  "hash": { "apikey": "..." },
  "qrcode": {
    "code": "2@...",
    "base64": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Passo 2 — abrir o QR Code

echo "iVBORw0KGgo..." | base64 -d > qr.png

https://evo.sua-empresa.com.br/instance/connect/atendimento

Passo 3 — escanear no WhatsApp

Passo 4 — confirmar conexão

curl https://evo.sua-empresa.com.br/instance/connectionState/atendimento \
  -H "apikey: SEU_API_KEY"

Resposta esperada:

{
  "instance": {
    "instanceName": "atendimento",
    "state": "open"
  }
}

Estados possíveis:

• open — conectado e pronto
• connecting — pareando (aguarde)
• close — desconectado (precisa novo QR)

Passo 5 — enviar mensagem de teste

curl -X POST https://evo.sua-empresa.com.br/message/sendText/atendimento \
  -H "Content-Type: application/json" \
  -H "apikey: SEU_API_KEY" \
  -d '{
    "number": "5511999999999",
    "text": "Olá! Sou o agente automatizado da Rollin Host. Como posso ajudar?"
  }'

Passo 6 — configurar webhook

Para receber eventos (mensagens chegando), aponte um webhook:

curl -X POST https://evo.sua-empresa.com.br/webhook/set/atendimento \
  -H "Content-Type: application/json" \
  -H "apikey: SEU_API_KEY" \
  -d '{
    "webhook": {
      "enabled": true,
      "url": "https://sua-api.exemplo.com/whats-in",
      "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"],
      "webhookByEvents": false
    }
  }'

Veja Webhooks na EvolutionAPI para detalhes do payload e melhores práticas.

Passo 7 — testar webhook

Mande uma mensagem para o número conectado (de outro celular). Em ~1s, sua URL recebe um POST com:

{
  "event": "messages.upsert",
  "instance": "atendimento",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "..."
    },
    "pushName": "João Silva",
    "message": {
      "conversation": "Oi, gostaria de informações"
    },
    "messageTimestamp": 1735689600
  }
}

Solução de problemas

Manter conexão estável

A sessão WhatsApp Web cai eventualmente (quedas de rede, atualização do app). A EvolutionAPI reconecta sozinha se o número não foi banido. Se cair com frequência:

• Confirme que o celular está online (chip ativo, internet)
• Não abra WhatsApp Web no PC com o mesmo número
• Não tente parear em 2 instâncias EvolutionAPI ao mesmo tempo
• Servidor com swap configurado (sem swap, OOM derruba a sessão)

Próximos passos

• Webhooks completos
• Multi-instância
• Stack n8n + EvolutionAPI + OpenAI