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.

SERVER_NAME

string

default:"evolution"

The name identifier for your Evolution API server.

SERVER_NAME=evolution

SERVER_TYPE

string

default:"http"

Server protocol type. Use http or https.

SERVER_TYPE=http

SERVER_PORT

number

default:"8080"

The port your API server will listen on.

SERVER_PORT=8080

SERVER_URL

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

SSL_CONF_PRIVKEY

string

Path to your SSL private key file.

SSL_CONF_PRIVKEY=/path/to/cert.key

SSL_CONF_FULLCHAIN

string

Path to your SSL certificate file.

SSL_CONF_FULLCHAIN=/path/to/cert.crt

Authentication

AUTHENTICATION_API_KEY

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.

AUTHENTICATION_EXPOSE_IN_FETCH_INSTANCES

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.

DATABASE_PROVIDER

enum

required

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

DATABASE_PROVIDER=postgresql

DATABASE_CONNECTION_URI

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'

DATABASE_CONNECTION_CLIENT_NAME

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

DATABASE_BOUNCER_CONNECTION_URI

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:

DATABASE_SAVE_DATA_INSTANCE

boolean

default:"true"

Save instance data to database.

DATABASE_SAVE_DATA_INSTANCE=true

DATABASE_SAVE_DATA_NEW_MESSAGE

boolean

default:"true"

Save new messages to database.

DATABASE_SAVE_DATA_NEW_MESSAGE=true

DATABASE_SAVE_MESSAGE_UPDATE

boolean

default:"true"

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

DATABASE_SAVE_MESSAGE_UPDATE=true

DATABASE_SAVE_DATA_CONTACTS

boolean

default:"true"

Save contacts to database.

DATABASE_SAVE_DATA_CONTACTS=true

DATABASE_SAVE_DATA_CHATS

boolean

default:"true"

Save chats to database.

DATABASE_SAVE_DATA_CHATS=true

DATABASE_SAVE_DATA_LABELS

boolean

default:"true"

Save labels to database.

DATABASE_SAVE_DATA_LABELS=true

DATABASE_SAVE_DATA_HISTORIC

boolean

default:"true"

Save message history to database.

DATABASE_SAVE_DATA_HISTORIC=true

DATABASE_SAVE_IS_ON_WHATSAPP

boolean

default:"true"

Save WhatsApp number verification data.

DATABASE_SAVE_IS_ON_WHATSAPP=true

DATABASE_SAVE_IS_ON_WHATSAPP_DAYS

number

default:"7"

Number of days to keep WhatsApp verification data.

DATABASE_SAVE_IS_ON_WHATSAPP_DAYS=7

DATABASE_DELETE_MESSAGE

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

CACHE_REDIS_ENABLED

boolean

default:"true"

Enable Redis caching.

CACHE_REDIS_ENABLED=true

CACHE_REDIS_URI

string

required

Redis connection URI.

CACHE_REDIS_URI=redis://localhost:6379/6

CACHE_REDIS_TTL

number

default:"604800"

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

CACHE_REDIS_TTL=604800

CACHE_REDIS_PREFIX_KEY

string

default:"evolution"

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

CACHE_REDIS_PREFIX_KEY=evolution

CACHE_REDIS_SAVE_INSTANCES

boolean

default:"false"

Save WhatsApp instance connection data in Redis instead of database.

CACHE_REDIS_SAVE_INSTANCES=false

Local Cache

CACHE_LOCAL_ENABLED

boolean

default:"false"

Enable local in-memory caching.

CACHE_LOCAL_ENABLED=false

CORS Configuration

CORS_ORIGIN

string

default:"*"

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

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

CORS_METHODS

string

default:"GET,POST,PUT,DELETE"

Allowed HTTP methods for CORS.

CORS_METHODS=GET,POST,PUT,DELETE

CORS_CREDENTIALS

boolean

default:"true"

Allow credentials in CORS requests.

CORS_CREDENTIALS=true

Logging

LOG_LEVEL

string

Comma-separated list of log levels to display.

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

LOG_COLOR

boolean

default:"true"

Enable colored log output.

LOG_COLOR=true

LOG_BAILEYS

string

default:"error"

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

LOG_BAILEYS=error

WhatsApp Configuration

CONFIG_SESSION_PHONE_CLIENT

string

default:"Evolution API"

Name displayed on the smartphone when connecting.

CONFIG_SESSION_PHONE_CLIENT=Evolution API

CONFIG_SESSION_PHONE_NAME

string

default:"Chrome"

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

CONFIG_SESSION_PHONE_NAME=Chrome

QRCODE_LIMIT

number

default:"30"

Maximum number of QR code generation attempts.

QRCODE_LIMIT=30

QRCODE_COLOR

string

default:"#175197"

QR code color in hex format.

QRCODE_COLOR='#175197'

Storage Configuration

Amazon S3 / MinIO

S3_ENABLED

boolean

default:"false"

Enable S3-compatible storage for media files.

S3_ENABLED=false

S3_ACCESS_KEY

string

S3 access key ID.

S3_ACCESS_KEY=your_access_key

S3_SECRET_KEY

string

S3 secret access key.

S3_SECRET_KEY=your_secret_key

S3_BUCKET

string

default:"evolution"

S3 bucket name.

S3_BUCKET=evolution

S3_PORT

number

default:"443"

S3 endpoint port.

S3_PORT=443

S3_ENDPOINT

string

default:"s3.domain.com"

S3 endpoint URL.

S3_ENDPOINT=s3.domain.com

S3_REGION

string

default:"eu-west-3"

S3 region.

S3_REGION=eu-west-3

S3_USE_SSL

boolean

default:"true"

Use SSL for S3 connections.

S3_USE_SSL=true

Webhook Configuration

WEBHOOK_GLOBAL_ENABLED

boolean

default:"false"

Enable global webhooks for all instances.

WEBHOOK_GLOBAL_ENABLED=false

WEBHOOK_GLOBAL_URL

string

Global webhook URL that receives events from all instances.

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

WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS

boolean

default:"false"

Send each event type to a separate webhook URL.

WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=false

Webhook Retry Configuration

WEBHOOK_REQUEST_TIMEOUT_MS

number

default:"60000"

Webhook request timeout in milliseconds.

WEBHOOK_REQUEST_TIMEOUT_MS=60000

WEBHOOK_RETRY_MAX_ATTEMPTS

number

default:"10"

Maximum number of retry attempts for failed webhooks.

WEBHOOK_RETRY_MAX_ATTEMPTS=10

WEBHOOK_RETRY_INITIAL_DELAY_SECONDS

number

default:"5"

Initial delay before first retry in seconds.

WEBHOOK_RETRY_INITIAL_DELAY_SECONDS=5

WEBHOOK_RETRY_USE_EXPONENTIAL_BACKOFF

boolean

default:"true"

Use exponential backoff for retries.

WEBHOOK_RETRY_USE_EXPONENTIAL_BACKOFF=true

WEBHOOK_RETRY_MAX_DELAY_SECONDS

number

default:"300"

Maximum delay between retries in seconds.

WEBHOOK_RETRY_MAX_DELAY_SECONDS=300

WEBHOOK_RETRY_JITTER_FACTOR

number

default:"0.2"

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

WEBHOOK_RETRY_JITTER_FACTOR=0.2

WEBHOOK_RETRY_NON_RETRYABLE_STATUS_CODES

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

RABBITMQ_ENABLED

boolean

default:"false"

Enable RabbitMQ event integration.

RABBITMQ_ENABLED=false

RABBITMQ_URI

string

default:"amqp://localhost"

RabbitMQ connection URI.

RABBITMQ_URI=amqp://localhost

RABBITMQ_EXCHANGE_NAME

string

default:"evolution"

RabbitMQ exchange name.

RABBITMQ_EXCHANGE_NAME=evolution

RABBITMQ_GLOBAL_ENABLED

boolean

default:"false"

Send events from all instances to the same queue.

RABBITMQ_GLOBAL_ENABLED=false

SQS

SQS_ENABLED

boolean

default:"false"

Enable Amazon SQS event integration.

SQS_ENABLED=false

SQS_ACCESS_KEY_ID

string

AWS access key ID for SQS.

SQS_ACCESS_KEY_ID=your_access_key

SQS_SECRET_ACCESS_KEY

string

AWS secret access key for SQS.

SQS_SECRET_ACCESS_KEY=your_secret_key

SQS_ACCOUNT_ID

string

AWS account ID.

SQS_ACCOUNT_ID=123456789012

SQS_REGION

string

AWS region for SQS.

SQS_REGION=us-east-1

WebSocket

WEBSOCKET_ENABLED

boolean

default:"false"

Enable WebSocket event streaming.

WEBSOCKET_ENABLED=false

WEBSOCKET_GLOBAL_EVENTS

boolean

default:"false"

Stream events from all instances.

WEBSOCKET_GLOBAL_EVENTS=false

WEBSOCKET_ALLOWED_HOSTS

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

PROMETHEUS_METRICS

boolean

default:"false"

Enable Prometheus metrics endpoint.

PROMETHEUS_METRICS=false

METRICS_AUTH_REQUIRED

boolean

default:"true"

Require authentication for metrics endpoint.

METRICS_AUTH_REQUIRED=true

METRICS_USER

string

default:"prometheus"

Username for metrics endpoint authentication.

METRICS_USER=prometheus

METRICS_PASSWORD

string

default:"secure_random_password_here"

Password for metrics endpoint authentication.

METRICS_PASSWORD=secure_random_password_here

METRICS_ALLOWED_IPS

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

TELEMETRY_ENABLED

boolean

default:"true"

Enable anonymous usage telemetry.

TELEMETRY_ENABLED=true

SENTRY_DSN

string

Sentry DSN for error tracking.

SENTRY_DSN=your_sentry_dsn

Proxy Configuration

PROXY_HOST

string

Global proxy host.

PROXY_HOST=proxy.example.com

PROXY_PORT

string

Global proxy port.

PROXY_PORT=8080

PROXY_PROTOCOL

string

Global proxy protocol (http or https).

PROXY_PROTOCOL=http

PROXY_USERNAME

string

Global proxy username.

PROXY_USERNAME=proxy_user

PROXY_PASSWORD

string

Global proxy password.

PROXY_PASSWORD=proxy_pass

Instance Management

DEL_INSTANCE

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

EVENT_EMITTER_MAX_LISTENERS

number

default:"50"

Maximum number of event listeners per instance.

EVENT_EMITTER_MAX_LISTENERS=50

LANGUAGE

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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

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