Connect a WhatsApp number to EvolutionAPI

This guide takes you from a server with EvolutionAPI already running to the first message delivering a webhook to your API. Total time: ~10 minutes.

Prerequisites

• EvolutionAPI running on a public HTTPS domain (e.g. https://evo.sua-empresa.com.br)
• AUTHENTICATION_API_KEY set in the EvolutionAPI .env
• A dedicated WhatsApp number (do not use your personal one)
• Access to the phone to scan the QR code

Step 1: create the instance

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"
  }'

The response looks something like this:

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

Step 2: open the QR code

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

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

Step 3: scan it in WhatsApp

Step 4: confirm the connection

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

Expected response:

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

Possible states:

• open: connected and ready
• connecting: pairing (wait)
• close: disconnected (needs a new QR code)

Step 5: send a test message

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?"
  }'

Step 6: configure the webhook

To receive events (incoming messages), point a 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
    }
  }'

See Webhooks in EvolutionAPI for payload details and best practices.

Step 7: test the webhook

Send a message to the connected number (from another phone). Within ~1s, your URL receives a POST with:

{
  "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
  }
}

Troubleshooting

Keep the connection stable

The WhatsApp Web session drops from time to time (network outages, app updates). EvolutionAPI reconnects on its own as long as the number has not been banned. If it drops often:

• Confirm the phone is online (active SIM, internet)
• Do not open WhatsApp Web on your computer with the same number
• Do not try to pair it on 2 EvolutionAPI instances at the same time
• Server with swap configured (without swap, OOM kills the session)

Next steps

• Complete webhooks guide
• Multi-instance
• n8n + EvolutionAPI + OpenAI stack