> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt > Use this file to discover all available pages before exploring further. # Environment Variables > Complete reference for all Evolution API 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`: ```bash theme={null} 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. The name identifier for your Evolution API server. ```bash theme={null} SERVER_NAME=evolution ``` Server protocol type. Use `http` or `https`. ```bash theme={null} SERVER_TYPE=http ``` The port your API server will listen on. ```bash theme={null} SERVER_PORT=8080 ``` The full URL where your Evolution API is accessible. Used for webhooks and callbacks. ```bash theme={null} SERVER_URL=http://localhost:8080 # Or for production: SERVER_URL=https://api.yourdomain.com ``` ### SSL Configuration Path to your SSL private key file. ```bash theme={null} SSL_CONF_PRIVKEY=/path/to/cert.key ``` Path to your SSL certificate file. ```bash theme={null} SSL_CONF_FULLCHAIN=/path/to/cert.crt ``` ## Authentication Global API key for authenticating requests. This key is required in the `apikey` header for all API calls. ```bash theme={null} AUTHENTICATION_API_KEY=429683C4C977415CAAFCCE10F7D57E11 ``` Use a strong, randomly generated key. This key provides full access to your Evolution API. Whether to expose instances in the fetch instances endpoint. ```bash theme={null} AUTHENTICATION_EXPOSE_IN_FETCH_INSTANCES=true ``` ## Database Configuration Evolution API supports PostgreSQL, MySQL, and PostgreSQL with PgBouncer. Database provider to use. Options: `postgresql`, `mysql`, `psql_bouncer` ```bash theme={null} DATABASE_PROVIDER=postgresql ``` Database connection string in URI format. **PostgreSQL:** ```bash theme={null} DATABASE_CONNECTION_URI='postgresql://user:pass@postgres:5432/evolution_db?schema=evolution_api' ``` **MySQL:** ```bash theme={null} DATABASE_CONNECTION_URI='mysql://user:pass@mysql:3306/evolution_db' ``` Client name for database connection. Used to separate multiple Evolution API installations using the same database. ```bash theme={null} DATABASE_CONNECTION_CLIENT_NAME=evolution_exchange ``` PostgreSQL connection URI with PgBouncer. Only used when `DATABASE_PROVIDER=psql_bouncer`. ```bash theme={null} 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: Save instance data to database. ```bash theme={null} DATABASE_SAVE_DATA_INSTANCE=true ``` Save new messages to database. ```bash theme={null} DATABASE_SAVE_DATA_NEW_MESSAGE=true ``` Save message updates (delivery status, read status) to database. ```bash theme={null} DATABASE_SAVE_MESSAGE_UPDATE=true ``` Save contacts to database. ```bash theme={null} DATABASE_SAVE_DATA_CONTACTS=true ``` Save chats to database. ```bash theme={null} DATABASE_SAVE_DATA_CHATS=true ``` Save labels to database. ```bash theme={null} DATABASE_SAVE_DATA_LABELS=true ``` Save message history to database. ```bash theme={null} DATABASE_SAVE_DATA_HISTORIC=true ``` Save WhatsApp number verification data. ```bash theme={null} DATABASE_SAVE_IS_ON_WHATSAPP=true ``` Number of days to keep WhatsApp verification data. ```bash theme={null} DATABASE_SAVE_IS_ON_WHATSAPP_DAYS=7 ``` Delete messages from database when deleted in WhatsApp. ```bash theme={null} DATABASE_DELETE_MESSAGE=true ``` ## Cache Configuration Evolution API supports Redis and local caching. ### Redis Cache Enable Redis caching. ```bash theme={null} CACHE_REDIS_ENABLED=true ``` Redis connection URI. ```bash theme={null} CACHE_REDIS_URI=redis://localhost:6379/6 ``` Time-to-live for cached data in seconds (default: 7 days). ```bash theme={null} CACHE_REDIS_TTL=604800 ``` Prefix for Redis keys. Used to separate data from multiple installations. ```bash theme={null} CACHE_REDIS_PREFIX_KEY=evolution ``` Save WhatsApp instance connection data in Redis instead of database. ```bash theme={null} CACHE_REDIS_SAVE_INSTANCES=false ``` ### Local Cache Enable local in-memory caching. ```bash theme={null} CACHE_LOCAL_ENABLED=false ``` ## CORS Configuration Allowed origins for CORS. Use `*` for all or comma-separated domains. ```bash theme={null} CORS_ORIGIN=* # Or specific domains: CORS_ORIGIN=yourdomain1.com,yourdomain2.com ``` Allowed HTTP methods for CORS. ```bash theme={null} CORS_METHODS=GET,POST,PUT,DELETE ``` Allow credentials in CORS requests. ```bash theme={null} CORS_CREDENTIALS=true ``` ## Logging Comma-separated list of log levels to display. ```bash theme={null} LOG_LEVEL=ERROR,WARN,DEBUG,INFO,LOG,VERBOSE,DARK,WEBHOOKS,WEBSOCKET ``` Enable colored log output. ```bash theme={null} LOG_COLOR=true ``` Baileys library log level. Options: `fatal`, `error`, `warn`, `info`, `debug`, `trace` ```bash theme={null} LOG_BAILEYS=error ``` ## WhatsApp Configuration Name displayed on the smartphone when connecting. ```bash theme={null} CONFIG_SESSION_PHONE_CLIENT=Evolution API ``` Browser name displayed. Options: `Chrome`, `Firefox`, `Edge`, `Opera`, `Safari` ```bash theme={null} CONFIG_SESSION_PHONE_NAME=Chrome ``` Maximum number of QR code generation attempts. ```bash theme={null} QRCODE_LIMIT=30 ``` QR code color in hex format. ```bash theme={null} QRCODE_COLOR='#175197' ``` ## Storage Configuration ### Amazon S3 / MinIO Enable S3-compatible storage for media files. ```bash theme={null} S3_ENABLED=false ``` S3 access key ID. ```bash theme={null} S3_ACCESS_KEY=your_access_key ``` S3 secret access key. ```bash theme={null} S3_SECRET_KEY=your_secret_key ``` S3 bucket name. ```bash theme={null} S3_BUCKET=evolution ``` S3 endpoint port. ```bash theme={null} S3_PORT=443 ``` S3 endpoint URL. ```bash theme={null} S3_ENDPOINT=s3.domain.com ``` S3 region. ```bash theme={null} S3_REGION=eu-west-3 ``` Use SSL for S3 connections. ```bash theme={null} S3_USE_SSL=true ``` ## Webhook Configuration Enable global webhooks for all instances. ```bash theme={null} WEBHOOK_GLOBAL_ENABLED=false ``` Global webhook URL that receives events from all instances. ```bash theme={null} WEBHOOK_GLOBAL_URL='https://your-webhook-endpoint.com' ``` Send each event type to a separate webhook URL. ```bash theme={null} WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=false ``` ### Webhook Retry Configuration Webhook request timeout in milliseconds. ```bash theme={null} WEBHOOK_REQUEST_TIMEOUT_MS=60000 ``` Maximum number of retry attempts for failed webhooks. ```bash theme={null} WEBHOOK_RETRY_MAX_ATTEMPTS=10 ``` Initial delay before first retry in seconds. ```bash theme={null} WEBHOOK_RETRY_INITIAL_DELAY_SECONDS=5 ``` Use exponential backoff for retries. ```bash theme={null} WEBHOOK_RETRY_USE_EXPONENTIAL_BACKOFF=true ``` Maximum delay between retries in seconds. ```bash theme={null} WEBHOOK_RETRY_MAX_DELAY_SECONDS=300 ``` Random jitter factor for retry delays (0.0 to 1.0). ```bash theme={null} WEBHOOK_RETRY_JITTER_FACTOR=0.2 ``` HTTP status codes that should not trigger retries. ```bash theme={null} WEBHOOK_RETRY_NON_RETRYABLE_STATUS_CODES=400,401,403,404,422 ``` ## Event Integration ### RabbitMQ Enable RabbitMQ event integration. ```bash theme={null} RABBITMQ_ENABLED=false ``` RabbitMQ connection URI. ```bash theme={null} RABBITMQ_URI=amqp://localhost ``` RabbitMQ exchange name. ```bash theme={null} RABBITMQ_EXCHANGE_NAME=evolution ``` Send events from all instances to the same queue. ```bash theme={null} RABBITMQ_GLOBAL_ENABLED=false ``` ### SQS Enable Amazon SQS event integration. ```bash theme={null} SQS_ENABLED=false ``` AWS access key ID for SQS. ```bash theme={null} SQS_ACCESS_KEY_ID=your_access_key ``` AWS secret access key for SQS. ```bash theme={null} SQS_SECRET_ACCESS_KEY=your_secret_key ``` AWS account ID. ```bash theme={null} SQS_ACCOUNT_ID=123456789012 ``` AWS region for SQS. ```bash theme={null} SQS_REGION=us-east-1 ``` ### WebSocket Enable WebSocket event streaming. ```bash theme={null} WEBSOCKET_ENABLED=false ``` Stream events from all instances. ```bash theme={null} WEBSOCKET_GLOBAL_EVENTS=false ``` Comma-separated list of allowed hosts for WebSocket connections. ```bash theme={null} WEBSOCKET_ALLOWED_HOSTS=127.0.0.1,::1,::ffff:127.0.0.1 ``` ## Monitoring ### Prometheus Metrics Enable Prometheus metrics endpoint. ```bash theme={null} PROMETHEUS_METRICS=false ``` Require authentication for metrics endpoint. ```bash theme={null} METRICS_AUTH_REQUIRED=true ``` Username for metrics endpoint authentication. ```bash theme={null} METRICS_USER=prometheus ``` Password for metrics endpoint authentication. ```bash theme={null} METRICS_PASSWORD=secure_random_password_here ``` Comma-separated list of allowed IP addresses for metrics endpoint. ```bash theme={null} METRICS_ALLOWED_IPS=127.0.0.1,10.0.0.100,192.168.1.50 ``` ### Telemetry Enable anonymous usage telemetry. ```bash theme={null} TELEMETRY_ENABLED=true ``` Sentry DSN for error tracking. ```bash theme={null} SENTRY_DSN=your_sentry_dsn ``` ## Proxy Configuration Global proxy host. ```bash theme={null} PROXY_HOST=proxy.example.com ``` Global proxy port. ```bash theme={null} PROXY_PORT=8080 ``` Global proxy protocol (`http` or `https`). ```bash theme={null} PROXY_PROTOCOL=http ``` Global proxy username. ```bash theme={null} PROXY_USERNAME=proxy_user ``` Global proxy password. ```bash theme={null} PROXY_PASSWORD=proxy_pass ``` ## Instance Management Delete disconnected instances after specified time (in minutes) or set to `false` to disable. ```bash theme={null} DEL_INSTANCE=false # Or delete after 5 minutes: DEL_INSTANCE=5 ``` Maximum number of event listeners per instance. ```bash theme={null} EVENT_EMITTER_MAX_LISTENERS=50 ``` API response language. Options: `en`, `pt`, `es` ```bash theme={null} LANGUAGE=en ``` ## Example Configurations ### Minimal Configuration ```bash .env theme={null} 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 ```bash .env theme={null} # 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 ``` ## Next Steps Configure your database for Evolution API Deploy Evolution API with Docker Compose