Cómo hospedar Evolution API

Evolution API convierte una cuenta de WhatsApp en una API REST. Tu sistema (CRM, chatbot, panel) envía un POST y el mensaje sale; cuando llega un mensaje, te avisa por webhook. Por eso mucha gente la usa en lugar de armar un bot desde cero con una librería.

Hospedarla es distinto de correrla en tu computadora. La API mantiene una conexión abierta con WhatsApp y guarda sesiones y mensajes en una base de datos. Si el proceso cae, la conexión cae. Los pasos de abajo siguen el README del repositorio; revisa las releases antes de instalar, porque los scripts y las variables pueden cambiar entre versiones.

¿Qué necesita Evolution API para correr?#

Según el README oficial:

• La versión LTS activa de Node.js (si corres sin Docker).
• PostgreSQL o MySQL, elegido en DATABASE_PROVIDER.
• Redis, recomendado para caché.
• Un proceso que permanezca activo todo el tiempo, escuchando el puerto 8080 por defecto.

También hay una imagen Docker, evoapicloud/evolution-api:latest. El repositorio incluye un docker-compose.yaml con la API, un Redis y un PostgreSQL.

¿Cómo levantarla con Docker Compose?#

Crea una carpeta con dos archivos. Primero el .env, con valores propios (no uses la clave de ejemplo del repositorio):

SERVER_PORT=8080
SERVER_URL=http://localhost:8080
AUTHENTICATION_API_KEY=cambia-por-una-clave-larga-y-aleatoria
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:cambia-la-clave@postgres:5432/evolution_db?schema=evolution_api
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://redis:6379/6
CACHE_REDIS_PREFIX_KEY=evolution
POSTGRES_DB=evolution_db
POSTGRES_USER=evolution
POSTGRES_PASSWORD=cambia-la-clave

Luego el docker-compose.yaml, simplificado a partir del archivo oficial:

services:
  api:
    image: evoapicloud/evolution-api:latest
    restart: always
    depends_on: [redis, postgres]
    ports:
      - "8080:8080"
    env_file: .env
    volumes:
      - evolution_instances:/evolution/instances

  redis:
    image: redis:latest
    restart: always
    command: redis-server --port 6379 --appendonly yes
    volumes:
      - evolution_redis:/data

  postgres:
    image: postgres:15
    restart: always
    env_file: .env
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  evolution_instances:
  evolution_redis:
  postgres_data:

Levántala con docker compose up -d. El archivo oficial publica la API solo en 127.0.0.1; el ejemplo de arriba la expone en todas las interfaces, así que pon un proxy inverso con HTTPS delante y nunca dejes el puerto abierto sin la clave.

¿Cómo correrla sin Docker?#

Sirve para entornos que ejecutan Node.js directamente. Los pasos del repositorio son:

git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api
npm install
cp .env.example .env   # edita base de datos, Redis y AUTHENTICATION_API_KEY
npm run db:generate
npm run db:deploy
npm run build
npm run start:prod

db:deploy aplica las migraciones del proveedor elegido en DATABASE_PROVIDER, así que define esa variable antes. start:prod ejecuta el dist/main compilado.

db:generate genera el cliente de Prisma para el proveedor elegido; sin él, la API no arranca. Si el entorno instala solo las dependencies (con NODE_ENV=production), dos scripts fallan: build, porque tsc es devDependency, y prepare, porque husky también lo es. En ese caso, compila en otro lugar y cambia prepare por husky || true, como sugiere la documentación de Husky.

¿Cómo crear la instancia y conectar WhatsApp?#

Cada número de WhatsApp es una instancia. La clave global (AUTHENTICATION_API_KEY) va en el header apikey:

curl -X POST http://localhost:8080/instance/create \
  -H "apikey: $AUTHENTICATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName":"mi-instancia","qrcode":true,"integration":"WHATSAPP-BAILEYS"}'

La respuesta trae el código QR en qrcode.base64. Si necesitas otro, pídelo con GET /instance/connect/mi-instancia. En el celular abre WhatsApp, entra en Dispositivos vinculados, Vincular un dispositivo y escanea el código. Después revisa el estado:

curl http://localhost:8080/instance/connectionState/mi-instancia \
  -H "apikey: $AUTHENTICATION_API_KEY"

¿Cómo enviar el primer mensaje?#

curl -X POST http://localhost:8080/message/sendText/mi-instancia \
  -H "apikey: $AUTHENTICATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"5215512345678","text":"Hola desde Evolution API"}'

El number lleva el código de país y el número, sin +. Si la respuesta trae los datos del mensaje enviado y el texto llega al celular, funcionó. Para recibir mensajes, configura el webhook de la instancia apuntando a una URL tuya.

¿Cómo proteger la instalación?#

La AUTHENTICATION_API_KEY da acceso total: crea y borra instancias y envía mensajes desde cualquier número conectado. Trátala como una contraseña de producción.

• Genera una clave larga y aleatoria y guárdala en una variable de entorno, nunca en el repositorio (mira qué son las variables de entorno).
• No expongas PostgreSQL ni Redis a internet. En Compose, déjalos solo en la red interna y quita cualquier ports de esos servicios.
• Sirve la API detrás de HTTPS y, si puedes, limita por IP quién la llama.
• Cambia SERVER_URL por la URL pública real, porque aparece en las respuestas y en los webhooks.
• Si quieres entender mejor el empaquetado, lee cómo dockerizar una aplicación.

Evolution API es un proyecto de terceros: sigue las releases del repositorio antes de cambiar la etiqueta de la imagen, en lugar de depender siempre de latest.

¿Cuáles son los errores comunes?#

• Falla al conectar con la base de datos: DATABASE_CONNECTION_URI con el host equivocado. Dentro de Compose el host es el nombre del servicio (postgres), no localhost.
• Las migraciones no corrieron: en instalación sin Docker, faltó npm run db:deploy o la variable DATABASE_PROVIDER.
• Error de TLS en la base de datos: si la base exige certificado de cliente, Prisma lo lee en la propia DATABASE_CONNECTION_URI: sslmode=require, sslcert con la CA del servidor y sslidentity con el certificado del cliente en PKCS12 (más sslpassword, si tiene). Las rutas son relativas a la carpeta prisma.
• redis disconnected en bucle con rediss://: el cliente redis de Evolution API activa el TLS por su cuenta con rediss://, pero solo confía en las CA públicas. Si el Redis usa una CA propia, apunta NODE_EXTRA_CA_CERTS al archivo de la CA en el comando que inicia el proceso, no en el .env: Node solo lee esta variable al arrancar.
• 401 en las llamadas: el header apikey no coincide con AUTHENTICATION_API_KEY.
• Pide el QR otra vez tras reiniciar: los datos de la instancia no persistieron. Revisa volúmenes y base de datos, y lee por qué el bot de WhatsApp se desconecta.
• Número restringido: la integración Baileys no es oficial. Para uso comercial a escala, compárala con la API oficial.

Cómo hacerlo en Square Cloud#

Evolution API tiene que estar en línea todo el tiempo. En Square Cloud, un hosting self-service, los contenedores están siempre activos, sin modo de suspensión, y el reinicio automático, que viene activado en el deploy desde el panel, vuelve a levantar el proceso cuando termina con error.

Corres Evolution API con el runtime Node.js, con la instalación desde el código fuente descrita arriba. No hay Dockerfile, Docker Compose ni paso de build, y las dependencias se instalan con NODE_ENV=production: compila en un CI externo, como GitHub Actions, sube el proyecto ya con la carpeta dist y ajusta prepare como se explica arriba. Como Evolution API lee el puerto de SERVER_PORT, un START como npm run db:generate && npm run db:deploy && SERVER_PORT=$PORT npm run start:prod hace que la API escuche en el puerto de la variable PORT, que define la plataforma.

Las variables de entorno son por aplicación: el panel importa un .env, y el cambio vale en el próximo reinicio. Desde el plan Standard puedes hospedar PostgreSQL, MySQL y Redis en el mismo datacenter que las aplicaciones; el Hobby no incluye bases de datos. El panel entrega la URL de conexión completa y el certificado, y el TLS es obligatorio. En PostgreSQL, el cliente también presenta el certificado descargado, configurado en la URL como se explica en los errores comunes, arriba. La RAM del plan es un pool compartido, con mínimo de 512 MB por aplicación web.

Para usar como caché un Redis hospedado en la plataforma, descarga en la página de la base de datos la opción Certificate CA (.crt), que guarda el ca-certificate.crt, pon el archivo en la raíz del proyecto y define:

# variables de entorno de la aplicación (la URL de conexión del panel)
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=rediss://default:TU_CONTRASENA@HOST:PUERTO
# comando START
npm run db:generate && npm run db:deploy && NODE_EXTRA_CA_CERTS=./ca-certificate.crt SERVER_PORT=$PORT npm run start:prod

Usa el host de la URL del panel, no una IP, para que el nombre coincida con el certificado, y no agregues /6: este Redis tiene una sola base de datos lógica y no pide certificado de cliente.

Si prefieres armar el bot directamente con Baileys, WPPConnect, whatsapp-web.js o la Cloud API oficial, consulta el hosting de bots de WhatsApp.