Skip to main content

​
Get started with Evolution API

Evolution API is a powerful WhatsApp integration platform that supports multiple messaging services. This guide will help you set up your first instance and send your first message in minutes.
Evolution API supports both WhatsApp Web (Baileys) and WhatsApp Business API. This quickstart uses the free Baileys integration.

​
Prerequisites

Before you begin, ensure you have:
  • Docker and Docker Compose installed
  • A phone with WhatsApp installed for QR code scanning
  • An API key for authentication

​
Installation

1

Clone the repository

Clone the Evolution API repository to your local machine:
git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api
2

Configure environment variables

Copy the example environment file and configure your settings:
cp .env.example .env
Edit the .env file with your configuration. At minimum, set these critical variables:
.env
# Server Configuration
SERVER_URL=http://localhost:8080

# Authentication - Generate a secure random key
AUTHENTICATION_API_KEY=your-secure-api-key-here

# Database - PostgreSQL (recommended)
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://user:pass@postgres:5432/evolution_db?schema=evolution_api'

# Cache - Redis
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://redis:6379/6
Generate a secure API key using: openssl rand -hex 32
3

Start the services

Launch Evolution API with Docker Compose:
docker-compose up -d
This starts:
  • Evolution API (port 8080)
  • Evolution Manager frontend (port 3000)
  • PostgreSQL database
  • Redis cache
Verify the services are running:
docker-compose ps

​
Create your first instance

Now let’s create a WhatsApp instance and connect it.
1

Create the instance

Send a POST request to create a new instance:
curl -X POST http://localhost:8080/instance/create \
  -H "apikey: your-secure-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "qrcode": true,
    "integration": "WHATSAPP-BAILEYS"
  }'
Response:
{
  "instance": {
    "instanceName": "my-instance",
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "integration": "WHATSAPP-BAILEYS",
    "status": "connecting"
  },
  "hash": "A1B2C3D4E5F6G7H8I9J0",
  "qrcode": {
    "code": "2@abc123...",
    "base64": "data:image/png;base64,iVBORw0KG..."
  }
}
Store the hash value securely - you’ll need it to authenticate requests for this specific instance.
2

Scan the QR code

Open WhatsApp on your phone and scan the QR code:
  1. Open WhatsApp on your phone
  2. Go to Settings > Linked Devices
  3. Tap Link a Device
  4. Scan the QR code from the response (use the base64 image)
You can also access the QR code through the Evolution Manager at http://localhost:3000
The instance will automatically connect once the QR code is scanned. You can verify the connection status:
curl -X GET http://localhost:8080/instance/connectionState/my-instance \
  -H "apikey: your-secure-api-key-here"
3

Send your first message

Once connected, send a text message:
curl -X POST http://localhost:8080/message/sendText/my-instance \
  -H "apikey: your-secure-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Hello from Evolution API! 🚀"
  }'
Response:
{
  "key": {
    "remoteJid": "[email protected]",
    "fromMe": true,
    "id": "3EB0E8F8D7A2B9C4F5E1"
  },
  "message": {
    "conversation": "Hello from Evolution API! 🚀"
  },
  "messageTimestamp": 1709568234
}
The phone number must include the country code without the + symbol (e.g., 5511999999999 for Brazil).

​
Next steps

Congratulations! You’ve successfully set up Evolution API and sent your first message. Here’s what to explore next:

Send media messages

Learn how to send images, videos, documents, and audio files

Configure webhooks

Receive real-time events for incoming messages and status updates

Connect chatbots

Integrate with OpenAI, Dify, Typebot, and more

API reference

Explore the complete API documentation

​
Common issues

If the QR code is not returned:
  1. Check the instance status: GET /instance/connectionState/{instanceName}
  2. Verify the instance is in connecting state
  3. Try connecting manually: GET /instance/connect/{instanceName}
  4. Check Docker logs: docker-compose logs -f api
If your instance keeps disconnecting:
  1. Ensure your phone has a stable internet connection
  2. Keep WhatsApp open on your phone during initial connection
  3. Check if you’ve reached the maximum number of linked devices (4)
  4. Verify Redis is running: docker-compose ps redis
If you receive authentication errors:
  1. Verify your API key matches the one in .env
  2. Ensure the apikey header is included in all requests
  3. For instance-specific requests, you can use the instance hash instead of the global API key
If you encounter database errors:
  1. Verify PostgreSQL is running: docker-compose ps evolution-postgres
  2. Check the database connection URI in .env
  3. Ensure the database schema is deployed: docker-compose exec api npm run db:deploy
  4. View database logs: docker-compose logs evolution-postgres

​
Need help?

Join our community for support:

Build docs developers (and LLMs) love

Get started for freeTalk to us