Evolution API Documentation

To set up Evolution API on your local machine, ensure you have Node.js 20+, PostgreSQL or MySQL, and Redis installed. Follow these steps:

1. Clone the repository and enter the directory.
2. Install dependencies using npm install.
3. Create a .env file by copying .env.example.
4. Configure your .env file with database credentials, Redis settings, and your desired API key.
5. Set the DATABASE_PROVIDER environment variable (postgresql or mysql).
6. Generate the Prisma client and deploy migrations.
7. Run the server in development or production mode.

git clone git@github.com:evolution-foundation/evolution-api.git
cd evolution-api

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your database, Redis, and API key

# Database setup
export DATABASE_PROVIDER=postgresql  # or mysql
npm run db:generate
npm run db:deploy

# Running
# Development with hot reload
npm run dev:server

# Production build and run
npm run build
npm run start:prod

You can deploy the full Evolution API stack using the provided docker-compose.yaml. The setup includes the API service, a frontend manager, a Redis instance for caching/state, and a PostgreSQL database for persistence.

Key Service Details:

• api: Runs the evoapicloud/evolution-api:latest image. It maps port 8080 to 127.0.0.1:8080 on the host. It depends on redis and evolution-postgres and loads configuration from a .env file.
• frontend: Runs the evoapicloud/evolution-manager:latest image, mapping host port 3000 to container port 80.
• redis: Runs redis:latest with AOF enabled (--appendonly yes) on port 6379.
• evolution-postgres: Runs postgres:15 with optimized settings (max_connections=1000).

Prerequisites:

• A .env file must be present in the same directory as the docker-compose.yaml containing the required environment variables for the API and PostgreSQL.

version: "3.8"

services:
  api:
    container_name: evolution_api
    image: evoapicloud/evolution-api:latest
    restart: always
    depends_on:
      - redis
      - evolution-postgres
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - evolution_instances:/evolution/instances
    networks:
      - evolution-net
      - dokploy-network
    env_file:
      - .env
    expose:
      - "8080"

  frontend:
    container_name: evolution_frontend
    image: evoapicloud/evolution-manager:latest
    restart: always
    ports:
      - "3000:80"
    networks:
      - evolution-net

  redis:
    container_name: evolution_redis
    image: redis:latest
    restart: always
    command: >
      redis-server --port 6379 --appendonly yes
    volumes:
      - evolution_redis:/data
    networks:
      evolution-net:
        aliases:
          - evolution-redis
      dokploy-network:
        aliases:
          - evolution-redis
    expose:
      - "6379"

  evolution-postgres:
    container_name: evolution_postgres
    image: postgres:15
    restart: always
    env_file:
      - .env
    command:
      - postgres
      - -c
      - max_connections=1000
      - -c
      - listen_addresses=*
    environment:
      - POSTGRES_DB=${POSTGRES_DATABASE}
      - POSTGRES_USER=${POSTGRES_USERNAME}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - evolution-net
      - dokploy-network
    expose:
      - "5432"

volumes:
  evolution_instances:
  evolution_redis:
  postgres_data:

networks:
  evolution-net:
    name: evolution-net
    driver: bridge
  dokploy-network:
    external: true

Use the provided docker-compose.yaml to spin up a local Kafka broker and Zookeeper instance. This setup is configured with multiple listeners to allow communication from within the Docker network, from the host machine via localhost, and from external hosts via host.docker.internal.

version: '3.3'

services:
  zookeeper:
    container_name: zookeeper
    image: confluentinc/cp-zookeeper:7.5.0
    environment:
      - ZOOKEEPER_CLIENT_PORT=2181
      - ZOOKEEPER_TICK_TIME=2000
      - ZOOKEEPER_SYNC_LIMIT=2
    volumes:
      - zookeeper_data:/var/lib/zookeeper/
    ports:
      - 2181:2181

  kafka:
    container_name: kafka
    image: confluentinc/cp-kafka:7.5.0
    depends_on:
      - zookeeper
    environment:
      - KAFKA_BROKER_ID=1
      - KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181
      - KAFKA_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT,OUTSIDE:PLAINTEXT
      - KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092,OUTSIDE://host.docker.internal:9094
      - KAFKA_INTER_BROKER_LISTENER_NAME=PLAINTEXT
      - KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1
      - KAFKA_TRANSACTION_STATE_LOG_MIN_ISR=1
      - KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=1
      - KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS=0
      - KAFKA_AUTO_CREATE_TOPICS_ENABLE=true
      - KAFKA_LOG_RETENTION_HOURS=168
      - KAFKA_LOG_SEGMENT_BYTES=1073741824
      - KAFKA_LOG_RETENTION_CHECK_INTERVAL_MS=300000
      - KAFKA_COMPRESSION_TYPE=gzip
    ports:
      - 29092:29092
      - 9092:9092
      - 9094:9094
    volumes:
      - kafka_data:/var/lib/kafka/data

volumes:
  zookeeper_data:
  kafka_data:

networks:
  evolution-net:
    name: evolution-net
    driver: bridge

Webhooks allow the API to send notifications to external services.

Global Webhooks

• WEBHOOK_GLOBAL_URL: The destination URL for all global webhooks.
• WEBHOOK_GLOBAL_ENABLED: Enable global webhooks.
• WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS: If true, webhooks are sent per specific event type.

Event-Specific Webhooks

Enable specific events via WEBHOOK_EVENTS_* (e.g., WEBHOOK_EVENTS_MESSAGES_UPSERT, WEBHOOK_EVENTS_CONNECTION_UPDATE).

Webhook Retry Policy

• WEBHOOK_REQUEST_TIMEOUT_MS: Timeout for webhook requests (default: 30000).
• WEBHOOK_RETRY_MAX_ATTEMPTS: Maximum retry attempts (default: 10).
• WEBHOOK_RETRY_INITIAL_DELAY_SECONDS: Initial delay between retries (default: 5).
• WEBHOOK_RETRY_USE_EXPONENTIAL_BACKOFF: Use exponential backoff (default: true).
• WEBHOOK_RETRY_MAX_DELAY_SECONDS: Maximum delay between retries (default: 300).
• WEBHOOK_RETRY_JITTER_FACTOR: Jitter factor for retries (default: 0.2).
• WEBHOOK_RETRY_NON_RETRYABLE_STATUS_CODES: Comma-separated list of HTTP status codes that should NOT trigger a retry (default: 400,401,403,404,422).