Instalación y Configuración Básica de EvolutionAPI

Instalación y Configuración Básica de EvolutionAPI
Video técnico en YouTube: Instalación y Configuración Básica de EvolutionAPI

Contexto y problema de integrar WhatsApp con automatizaciones

Conectar flujos de automatización en n8n, sistemas CRM o agentes conversacionales de Inteligencia Artificial con WhatsApp requiere una API REST estable que gestione sesiones, eventos en tiempo real vía webhooks y persistencia confiable de mensajes. Instalar dependencias de Node.js directamente en el servidor anfitrión suele derivar en conflictos de versiones y fallos de reconexión tras reinicios.

EvolutionAPI empaquetada con Docker Compose, PostgreSQL y Redis proporciona una arquitectura desacoplada y lista para escalar: PostgreSQL almacena el estado de instancias y registros de mensajería, mientras Redis acelera la caché de sesiones y reduce la carga sobre el disco.

Requisitos previos

  • Servidor Linux con Docker y Docker Compose v2 instalados y operativos.
  • Al menos 2 GB de memoria RAM disponibles para los tres contenedores (evolution-api, postgres y redis).
  • Un dominio o subdominio configurado mediante proxy inverso con HTTPS si vas a recibir webhooks desde entornos externos.

Pasos de implementación con Docker Compose

1. Preparar variables de entorno en .env

Crea un directorio dedicado para el servicio y define tus credenciales de acceso en un archivo .env con permisos restringidos (chmod 600 .env):

AUTHENTICATION_API_KEY=TU_TOKEN_API_LARGO_Y_SEGURO
POSTGRES_PASSWORD=changeme_clave_postgres_segura
SERVER_URL=https://evo.tudominio.com

2. Definir el archivo compose.yaml

Crea compose.yaml separando la base de datos y la caché dentro de una red interna de Docker, y exponiendo el puerto 8080 únicamente hacia 127.0.0.1 para publicarlo a través de un proxy inverso TLS:

services:
  evolution-api:
    image: atendai/evolution-api:latest
    container_name: evolution-api
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - SERVER_URL=${SERVER_URL}
      - AUTHENTICATION_API_KEY=${AUTHENTICATION_API_KEY}
      - DATABASE_ENABLED=true
      - DATABASE_PROVIDER=postgresql
      - DATABASE_CONNECTION_URI=postgresql://evolution:${POSTGRES_PASSWORD}@postgres:5432/evolution
      - CACHE_REDIS_ENABLED=true
      - CACHE_REDIS_URI=redis://redis:6379/1
    volumes:
      - evolution_instances:/evolution/instances
    depends_on:
      - postgres
      - redis
    networks:
      - evo-internal

  postgres:
    image: postgres:17-alpine
    container_name: evolution-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=evolution
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=evolution
    volumes:
      - evolution_pgdata:/var/lib/postgresql/data
    networks:
      - evo-internal

  redis:
    image: redis:7-alpine
    container_name: evolution-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - evolution_redis:/data
    networks:
      - evo-internal

volumes:
  evolution_instances:
  evolution_pgdata:
  evolution_redis:

networks:
  evo-internal:
    driver: bridge

3. Levantar el stack y crear la primera instancia

Inicia los servicios y crea una instancia apuntando el webhook hacia tu flujo en n8n:

docker compose up -d
curl -X POST http://127.0.0.1:8080/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: $AUTHENTICATION_API_KEY" \
  -d '{"instanceName":"soporte-noc","qrcode":true,"integration":"WHATSAPP-BAILEYS"}'

Verificación del resultado

Verifica que los tres contenedores estén activos y consulta el estado de la instancia creada a través del endpoint administrativo:

docker compose ps
curl -s http://127.0.0.1:8080/instance/fetchInstances \
  -H "apikey: $AUTHENTICATION_API_KEY"

Una respuesta JSON con el nombre soporte-noc y estado inicial connecting o open confirma que EvolutionAPI se comunica correctamente tanto con PostgreSQL como con Redis.

Buenas prácticas de seguridad

  • Nunca expongas el puerto 8080 directo a Internet: Publica la API detrás de Nginx Proxy Manager, Caddy o Cloudflare Tunnel con cifrado HTTPS obligatorio.
  • Rota y protege AUTHENTICATION_API_KEY: Usa claves aleatorias de al menos 32 caracteres y no las subas a repositorios Git.
  • Cumple políticas de mensajería y límites de envío: Respeta el consentimiento explícito del destinatario y aplica pausas entre envíos para evitar bloqueos de cuenta o infracciones a las políticas de WhatsApp y Meta.

Si deseas automatizar la atención al cliente con WhatsApp, n8n y agentes conversacionales, ofrecemos consultoría integral para el diseño, la implementación, el despliegue y el mantenimiento de EvolutionAPI desde Valencia, Estado Carabobo (Contáctanos).