Environment Variables

Evolution API is configured entirely through environment variables. This page documents all available options organized by category.

Getting Started

Create a .env file in your project root based on the provided .env.example:

cp .env.example .env

Edit the .env file with your configuration values.

Never commit your .env file to version control. It contains sensitive credentials and API keys.

Server Configuration

Basic server settings that control how Evolution API runs.

string

default:"evolution"

The name identifier for your Evolution API server.

SERVER_NAME=evolution

string

default:"http"

Server protocol type. Use http or https.

SERVER_TYPE=http

number

default:"8080"

The port your API server will listen on.

SERVER_PORT=8080

string

required

The full URL where your Evolution API is accessible. Used for webhooks and callbacks.

SERVER_URL=http://localhost:8080
# Or for production:
SERVER_URL=https://api.yourdomain.com

SSL Configuration

string

Path to your SSL private key file.

SSL_CONF_PRIVKEY=/path/to/cert.key

string

Path to your SSL certificate file.

SSL_CONF_FULLCHAIN=/path/to/cert.crt

Authentication

string

required

Global API key for authenticating requests. This key is required in the apikey header for all API calls.

AUTHENTICATION_API_KEY=429683C4C977415CAAFCCE10F7D57E11

Use a strong, randomly generated key. This key provides full access to your Evolution API.

boolean

default:"true"

Whether to expose instances in the fetch instances endpoint.

AUTHENTICATION_EXPOSE_IN_FETCH_INSTANCES=true

Database Configuration

Evolution API supports PostgreSQL, MySQL, and PostgreSQL with PgBouncer.

enum

required

Database provider to use. Options: postgresql, mysql, psql_bouncer

DATABASE_PROVIDER=postgresql

string

required

Database connection string in URI format.PostgreSQL:

DATABASE_CONNECTION_URI='postgresql://user:pass@postgres:5432/evolution_db?schema=evolution_api'

MySQL:

DATABASE_CONNECTION_URI='mysql://user:pass@mysql:3306/evolution_db'

string

default:"evolution_exchange"

Client name for database connection. Used to separate multiple Evolution API installations using the same database.

DATABASE_CONNECTION_CLIENT_NAME=evolution_exchange

string

PostgreSQL connection URI with PgBouncer. Only used when DATABASE_PROVIDER=psql_bouncer.

DATABASE_BOUNCER_CONNECTION_URI=postgresql://user:pass@pgbouncer:5432/evolution_db?pgbouncer=true&schema=evolution_api

Data Storage Options

Control what data is saved to the database:

boolean

default:"true"

Save instance data to database.

DATABASE_SAVE_DATA_INSTANCE=true

boolean

default:"true"

Save new messages to database.

DATABASE_SAVE_DATA_NEW_MESSAGE=true

boolean

default:"true"

Save message updates (delivery status, read status) to database.

DATABASE_SAVE_MESSAGE_UPDATE=true

boolean

default:"true"

Save contacts to database.

DATABASE_SAVE_DATA_CONTACTS=true

boolean

default:"true"

Save chats to database.

DATABASE_SAVE_DATA_CHATS=true

boolean

default:"true"

Save labels to database.

DATABASE_SAVE_DATA_LABELS=true

boolean

default:"true"

Save message history to database.

DATABASE_SAVE_DATA_HISTORIC=true

boolean

default:"true"

Save WhatsApp number verification data.

DATABASE_SAVE_IS_ON_WHATSAPP=true

number

default:"7"

Number of days to keep WhatsApp verification data.

DATABASE_SAVE_IS_ON_WHATSAPP_DAYS=7

boolean

default:"true"

Delete messages from database when deleted in WhatsApp.

DATABASE_DELETE_MESSAGE=true

Cache Configuration

Evolution API supports Redis and local caching.

Redis Cache

boolean

default:"true"

Enable Redis caching.

CACHE_REDIS_ENABLED=true

string

required

Redis connection URI.

CACHE_REDIS_URI=redis://localhost:6379/6

number

default:"604800"

Time-to-live for cached data in seconds (default: 7 days).

CACHE_REDIS_TTL=604800

string

default:"evolution"

Prefix for Redis keys. Used to separate data from multiple installations.

CACHE_REDIS_PREFIX_KEY=evolution

boolean

default:"false"

Save WhatsApp instance connection data in Redis instead of database.

CACHE_REDIS_SAVE_INSTANCES=false

Local Cache

boolean

default:"false"

Enable local in-memory caching.

CACHE_LOCAL_ENABLED=false

CORS Configuration

string

default:"*"

Allowed origins for CORS. Use * for all or comma-separated domains.

CORS_ORIGIN=*
# Or specific domains:
CORS_ORIGIN=yourdomain1.com,yourdomain2.com

string

default:"GET,POST,PUT,DELETE"

Allowed HTTP methods for CORS.

CORS_METHODS=GET,POST,PUT,DELETE

boolean

default:"true"

Allow credentials in CORS requests.

CORS_CREDENTIALS=true

Logging

string

Comma-separated list of log levels to display.

LOG_LEVEL=ERROR,WARN,DEBUG,INFO,LOG,VERBOSE,DARK,WEBHOOKS,WEBSOCKET

boolean

default:"true"

Enable colored log output.

LOG_COLOR=true

string

default:"error"

Baileys library log level. Options: fatal, error, warn, info, debug, trace

LOG_BAILEYS=error

WhatsApp Configuration

string

default:"Evolution API"

Name displayed on the smartphone when connecting.

CONFIG_SESSION_PHONE_CLIENT=Evolution API

string

default:"Chrome"

Browser name displayed. Options: Chrome, Firefox, Edge, Opera, Safari

CONFIG_SESSION_PHONE_NAME=Chrome

number

default:"30"

Maximum number of QR code generation attempts.

QRCODE_LIMIT=30

string

default:"#175197"

QR code color in hex format.

QRCODE_COLOR='#175197'

Storage Configuration

Amazon S3 / MinIO

boolean

default:"false"

Enable S3-compatible storage for media files.

S3_ENABLED=false

string

S3 access key ID.

S3_ACCESS_KEY=your_access_key

string

S3 secret access key.

S3_SECRET_KEY=your_secret_key

string

default:"evolution"

S3 bucket name.

S3_BUCKET=evolution

number

default:"443"

S3 endpoint port.

S3_PORT=443

string

default:"s3.domain.com"

S3 endpoint URL.

S3_ENDPOINT=s3.domain.com

string

default:"eu-west-3"

S3 region.

S3_REGION=eu-west-3

boolean

default:"true"

Use SSL for S3 connections.

S3_USE_SSL=true

Webhook Configuration

boolean

default:"false"

Enable global webhooks for all instances.

WEBHOOK_GLOBAL_ENABLED=false

string

Global webhook URL that receives events from all instances.

WEBHOOK_GLOBAL_URL='https://your-webhook-endpoint.com'

boolean

default:"false"

Send each event type to a separate webhook URL.

WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=false

Webhook Retry Configuration

number

default:"60000"

Webhook request timeout in milliseconds.

WEBHOOK_REQUEST_TIMEOUT_MS=60000

number

default:"10"

Maximum number of retry attempts for failed webhooks.

WEBHOOK_RETRY_MAX_ATTEMPTS=10

number

default:"5"

Initial delay before first retry in seconds.

WEBHOOK_RETRY_INITIAL_DELAY_SECONDS=5

boolean

default:"true"

Use exponential backoff for retries.

WEBHOOK_RETRY_USE_EXPONENTIAL_BACKOFF=true

number

default:"300"

Maximum delay between retries in seconds.

WEBHOOK_RETRY_MAX_DELAY_SECONDS=300

number

default:"0.2"

Random jitter factor for retry delays (0.0 to 1.0).

WEBHOOK_RETRY_JITTER_FACTOR=0.2

string

default:"400,401,403,404,422"

HTTP status codes that should not trigger retries.

WEBHOOK_RETRY_NON_RETRYABLE_STATUS_CODES=400,401,403,404,422

Event Integration

RabbitMQ

boolean

default:"false"

Enable RabbitMQ event integration.

RABBITMQ_ENABLED=false

string

default:"amqp://localhost"

RabbitMQ connection URI.

RABBITMQ_URI=amqp://localhost

string

default:"evolution"

RabbitMQ exchange name.

RABBITMQ_EXCHANGE_NAME=evolution

boolean

default:"false"

Send events from all instances to the same queue.

RABBITMQ_GLOBAL_ENABLED=false

SQS

boolean

default:"false"

Enable Amazon SQS event integration.

SQS_ENABLED=false

string

AWS access key ID for SQS.

SQS_ACCESS_KEY_ID=your_access_key

string

AWS secret access key for SQS.

SQS_SECRET_ACCESS_KEY=your_secret_key

string

AWS account ID.

SQS_ACCOUNT_ID=123456789012

string

AWS region for SQS.

SQS_REGION=us-east-1

WebSocket

boolean

default:"false"

Enable WebSocket event streaming.

WEBSOCKET_ENABLED=false

boolean

default:"false"

Stream events from all instances.

WEBSOCKET_GLOBAL_EVENTS=false

string

default:"127.0.0.1,::1,::ffff:127.0.0.1"

Comma-separated list of allowed hosts for WebSocket connections.

WEBSOCKET_ALLOWED_HOSTS=127.0.0.1,::1,::ffff:127.0.0.1

Monitoring

Prometheus Metrics

boolean

default:"false"

Enable Prometheus metrics endpoint.

PROMETHEUS_METRICS=false

boolean

default:"true"

Require authentication for metrics endpoint.

METRICS_AUTH_REQUIRED=true

string

default:"prometheus"

Username for metrics endpoint authentication.

METRICS_USER=prometheus

string

default:"secure_random_password_here"

Password for metrics endpoint authentication.

METRICS_PASSWORD=secure_random_password_here

string

default:"127.0.0.1,10.0.0.100,192.168.1.50"

Comma-separated list of allowed IP addresses for metrics endpoint.

METRICS_ALLOWED_IPS=127.0.0.1,10.0.0.100,192.168.1.50

Telemetry

boolean

default:"true"

Enable anonymous usage telemetry.

TELEMETRY_ENABLED=true

string

Sentry DSN for error tracking.

SENTRY_DSN=your_sentry_dsn

Proxy Configuration

string

Global proxy host.

PROXY_HOST=proxy.example.com

string

Global proxy port.

PROXY_PORT=8080

string

Global proxy protocol (http or https).

PROXY_PROTOCOL=http

string

Global proxy username.

PROXY_USERNAME=proxy_user

string

Global proxy password.

PROXY_PASSWORD=proxy_pass

Instance Management

string

default:"false"

Delete disconnected instances after specified time (in minutes) or set to false to disable.

DEL_INSTANCE=false
# Or delete after 5 minutes:
DEL_INSTANCE=5

number

default:"50"

Maximum number of event listeners per instance.

EVENT_EMITTER_MAX_LISTENERS=50

string

default:"en"

API response language. Options: en, pt, es

LANGUAGE=en

Example Configurations

Minimal Configuration

.env

SERVER_URL=http://localhost:8080
AUTHENTICATION_API_KEY=your_secure_api_key_here
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://user:pass@localhost:5432/evolution_db?schema=evolution_api'
CACHE_REDIS_ENABLED=false

Production Configuration

.env

# Server
SERVER_URL=https://api.yourdomain.com
SERVER_TYPE=https
SERVER_PORT=8080
AUTHENTICATION_API_KEY=your_secure_random_api_key

# Database
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://evolution:secure_pass@postgres:5432/evolution_db?schema=evolution_api'
DATABASE_SAVE_DATA_INSTANCE=true
DATABASE_SAVE_DATA_NEW_MESSAGE=true
DATABASE_SAVE_MESSAGE_UPDATE=true

# Cache
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://redis:6379/6
CACHE_REDIS_PREFIX_KEY=evolution_prod

# Storage
S3_ENABLED=true
S3_BUCKET=evolution-production
S3_ACCESS_KEY=your_s3_access_key
S3_SECRET_KEY=your_s3_secret_key
S3_REGION=us-east-1

# Logging
LOG_LEVEL=ERROR,WARN,INFO
LOG_COLOR=false

# Security
CORS_ORIGIN=yourdomain.com
CORS_CREDENTIALS=true

# Monitoring
PROMETHEUS_METRICS=true
METRICS_AUTH_REQUIRED=true
METRICS_USER=prometheus
METRICS_PASSWORD=secure_metrics_password

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

Getting Started

Server Configuration

SSL Configuration

Authentication

Database Configuration

Data Storage Options

Cache Configuration

Redis Cache

Local Cache

CORS Configuration

Logging

WhatsApp Configuration

Storage Configuration

Amazon S3 / MinIO

Webhook Configuration

Webhook Retry Configuration

Event Integration

RabbitMQ

SQS

WebSocket

Monitoring

Prometheus Metrics

Telemetry

Proxy Configuration

Instance Management

Example Configurations

Minimal Configuration

Production Configuration

Next Steps

Database Setup

Docker Deployment

​Getting Started

​Server Configuration

​SSL Configuration

​Authentication

​Database Configuration

​Data Storage Options

​Cache Configuration

​Redis Cache

​Local Cache

​CORS Configuration

​Logging

​WhatsApp Configuration

​Storage Configuration

​Amazon S3 / MinIO

​Webhook Configuration

​Webhook Retry Configuration

​Event Integration

​RabbitMQ

​SQS

​WebSocket

​Monitoring

​Prometheus Metrics

​Telemetry

​Proxy Configuration

​Instance Management

​Example Configurations

​Minimal Configuration

​Production Configuration

​Next Steps

Database Setup

Docker Deployment

Getting Started

Server Configuration

SSL Configuration

Authentication

Database Configuration

Data Storage Options

Cache Configuration

Redis Cache

Local Cache

CORS Configuration

Logging

WhatsApp Configuration

Storage Configuration

Amazon S3 / MinIO

Webhook Configuration

Webhook Retry Configuration

Event Integration

RabbitMQ

SQS

WebSocket

Monitoring

Prometheus Metrics

Telemetry

Proxy Configuration

Instance Management

Example Configurations

Minimal Configuration

Production Configuration

Next Steps