Quickstart Guide

Quickstart Guide

This guide will walk you through setting up Evolution API Lite using Docker and sending your first WhatsApp message. You’ll have a working instance in under 10 minutes.

Prerequisites

Before you begin, ensure you have:

• Docker and Docker Compose installed
• A text editor for configuration files
• Basic familiarity with REST APIs and cURL commands

Note

For local development without Docker, see our Development Setup Guide which covers Node.js installation and local database setup.

Step 1: Download and Configure

1. Clone or Download the Project

   git clone https://github.com/EvolutionAPI/evolution-api.git
   cd evolution-api

   Or download the docker-compose.yaml and .env.example files directly.

2. Create Environment Configuration

   Copy the example environment file and configure it:

   cp .env.example .env

   Open the .env file and update these essential settings:

   # Server Configuration
   SERVER_URL=http://localhost:8080
   
   # Database Configuration (using the default PostgreSQL setup)
   DATABASE_PROVIDER=postgresql
   DATABASE_CONNECTION_URI='postgresql://user:pass@postgres:5432/evolution?schema=public'
   
   # Authentication - Change this to a secure API key
   AUTHENTICATION_API_KEY=your-secure-api-key-here
   
   # Enable QR Code generation
   QRCODE_LIMIT=30

   Caution

   Replace your-secure-api-key-here with a strong, unique API key. This key will be used to authenticate all API requests. Learn more about the authentication system.

   Tip

   For a complete list of all available environment variables, see the Environment Variables Guide.

Step 2: Start the Services

Launch all services using Docker Compose:

docker-compose up -d

This command starts:

• Evolution API Lite on port 8080
• PostgreSQL database on port 5432
• Redis cache on port 6379

Note

The first startup may take a few minutes as Docker downloads the required images and initializes the database.

Verify the services are running:

docker-compose ps

You should see all three containers in the “Up” state.

Step 3: Create Your First Instance

Now create a WhatsApp instance using the API:

cURL

curl -X POST http://localhost:8080/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: your-secure-api-key-here" \
  -d '{
    "instanceName": "my-first-instance",
    "integration": "WHATSAPP_BAILEYS",
    "qrcode": true
  }'

JavaScript (fetch)

const response = await fetch('http://localhost:8080/instance/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    apikey: 'your-secure-api-key-here'
  },
  body: JSON.stringify({
    instanceName: 'my-first-instance',
    integration: 'WHATSAPP_BAILEYS',
    qrcode: true
  })
})

const data = await response.json()
console.log(data)

The response will include:

• Instance details (name, ID, status)
• A QR code (base64 encoded)
• Authentication hash for this specific instance

Note

Learn more about instance lifecycle and management in our Instances Guide.

Step 4: Connect to WhatsApp

1. Get the QR Code

• The API response includes a QR code in base64 format. You can:
  • Decode and display it using an online base64 → image converter
  • Use a QR code terminal tool to display it directly in your terminal
  • Or check the Docker logs for a terminal-rendered QR code:

docker-compose logs -f api

2. Scan with WhatsApp

• Open WhatsApp on your phone
• Go to Settings → Linked Devices
• Tap “Link a Device”
• Scan the QR code displayed from the API response

3. Verify Connection

Check your instance connection status:

curl -X GET http://localhost:8080/instance/my-first-instance/connectionState \
  -H "apikey: your-secure-api-key-here"

You should see “state”: “open” when successfully connected.

Step 5: Send Your First Message

Now send a text message to verify everything works:

cURL

curl -X POST http://localhost:8080/message/my-first-instance/sendText \
  -H "Content-Type: application/json" \
  -H "apikey: your-secure-api-key-here" \
  -d '{
    "number": "5511999999999",
    "text": "Hello from Evolution API Lite! 🚀"
  }'

JavaScript (fetch)

const response = await fetch('http://localhost:8080/message/my-first-instance/sendText', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    apikey: 'your-secure-api-key-here'
  },
  body: JSON.stringify({
    number: '5511999999999',
    text: 'Hello from Evolution API Lite! 🚀'
  })
})

const result = await response.json()
console.log(result)

Note

Replace 5511999999999 with a valid WhatsApp number in international format (country code + number, no spaces or special characters).

Troubleshooting

Common Issues

QR Code Not Generating

• Ensure qrcode: true is set in the instance creation request
• Check Docker logs: docker-compose logs api
• Verify the instance was created successfully

Connection Fails After Scanning

• Wait 10-15 seconds after scanning before checking connection status
• Ensure your phone has a stable internet connection
• Try restarting the instance: POST /instance/{instanceName}/restart

API Key Authentication Errors

• Verify the API key matches exactly between .env and your requests
• Ensure the apikey header is included in all requests
• Check that there are no extra spaces or characters in the key

Database Connection Issues

• Verify PostgreSQL container is running: docker-compose ps
• Check database logs: docker-compose logs postgres
• Ensure the DATABASE_CONNECTION_URI in .env is correct

Getting Help

If you encounter issues: