Conectar un número de WhatsApp en EvolutionAPI

Esta guía te lleva desde el servidor con EvolutionAPI ya funcionando hasta el primer mensaje entregando el webhook en tu API. Tiempo total: ~10 minutos.

Requisitos previos

• EvolutionAPI ejecutándose en un dominio HTTPS público (ej.: https://evo.sua-empresa.com.br)
• AUTHENTICATION_API_KEY definido en el .env de EvolutionAPI
• Número de WhatsApp dedicado (no uses el personal)
• Acceso al celular para escanear el código QR

Paso 1: crear la instancia

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

La respuesta es algo como:

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

Paso 2: abrir el código QR

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

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

Paso 3: escanear en WhatsApp

Paso 4: confirmar la conexión

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

Respuesta esperada:

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

Estados posibles:

• open: conectado y listo
• connecting: vinculando (espera)
• close: desconectado (necesita un nuevo QR)

Paso 5: enviar un mensaje de prueba

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

Paso 6: configurar el webhook

Para recibir eventos (mensajes entrantes), configura un 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
    }
  }'

Consulta Webhooks en EvolutionAPI para ver los detalles del payload y las mejores prácticas.

Paso 7: probar el webhook

Envía un mensaje al número conectado (desde otro celular). En ~1s, tu URL recibe un POST con:

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

Solución de problemas

Mantener la conexión estable

La sesión de WhatsApp Web se cae eventualmente (caídas de red, actualización de la app). EvolutionAPI se reconecta sola si el número no fue bloqueado. Si se cae con frecuencia:

• Confirma que el celular está en línea (chip activo, internet)
• No abras WhatsApp Web en la PC con el mismo número
• No intentes vincularlo en 2 instancias de EvolutionAPI al mismo tiempo
• Servidor con swap configurado (sin swap, el OOM tumba la sesión)

Próximos pasos

• Webhooks completos
• Multiinstancia
• Stack n8n + EvolutionAPI + OpenAI