Skip to main content
Evolution API is a production-ready, multi-tenant WhatsApp API platform built with Node.js, TypeScript, and Express.js. The API follows RESTful principles and provides comprehensive endpoints for managing WhatsApp instances and interactions.

​
REST Architecture

Evolution API is built on a RESTful architecture with the following characteristics:
  • Stateless operations: Each request contains all information needed for processing
  • Resource-based URLs: Endpoints represent resources (instances, messages, chats, etc.)
  • Standard HTTP methods: Uses POST, GET, PUT, and DELETE appropriately
  • JSON payloads: All request and response bodies use JSON format
  • HTTP status codes: Returns semantic status codes (200, 201, 400, 401, 404, 500)

​
Base URL Configuration

Configure your Evolution API base URL using the SERVER_URL environment variable: 
SERVER_URL=https://api.yourdomain.com
The server configuration is defined in src/config/env.config.ts:39 and includes:
​
SERVER.URL
string
required
The base URL where your Evolution API is accessible
​
SERVER.PORT
number
default:"8080"
The port on which the API server listens
​
SERVER.TYPE
string
default:"http"
Server protocol type: http or https

​
Making Your First Request

All requests to Evolution API follow this pattern: 
POST {SERVER_URL}/endpoint
Content-Type: application/json
apikey: YOUR_API_KEY

curl -X GET https://api.yourdomain.com/ \
  -H "apikey: YOUR_API_KEY"

​
API Versioning

Evolution API currently uses implicit versioning through the package version. The API version is included in root endpoint responses: 
{
  "status": 200,
  "message": "Welcome to the Evolution API, it is working!",
  "version": "2.1.0",
  "documentation": "https://doc.evolution-api.com"
}
Future versions may introduce explicit URL-based versioning (e.g., /v2/instance/create). Monitor the changelog for updates.

​
Endpoint Categories

Evolution API organizes endpoints into logical categories. Each category is defined in src/api/routes/index.router.ts:

​
Instance Management

Manage WhatsApp instances with full lifecycle control.
  • Base Path: /instance
  • Router: src/api/routes/instance.router.ts
  • Operations: Create, connect, disconnect, restart, delete instances

​
Message Operations

Send various types of WhatsApp messages.
  • Base Path: /message
  • Router: src/api/routes/sendMessage.router.ts
  • Message Types: Text, media, audio, location, contact, reaction, poll, list, buttons, stickers

​
Chat Management

Manage WhatsApp conversations and chat metadata.
  • Base Path: /chat
  • Router: src/api/routes/chat.router.ts
  • Operations: Find chats, archive, delete, mark as read/unread, fetch messages

​
Group Operations

Manage WhatsApp groups and participants.
  • Base Path: /group
  • Router: src/api/routes/group.router.ts
  • Operations: Create groups, manage participants, update settings, fetch group info

​
Business Profile

Manage WhatsApp Business profile information.
  • Base Path: /business
  • Router: src/api/routes/business.router.ts
  • Operations: Update profile, fetch business info

​
Call Management

Handle WhatsApp call events and actions.
  • Base Path: /call
  • Router: src/api/routes/call.router.ts
  • Operations: Reject calls, fetch call history

​
Labels

Manage WhatsApp message labels for organization.
  • Base Path: /label
  • Router: src/api/routes/label.router.ts
  • Operations: Create, update, delete labels

​
Templates

Manage WhatsApp Business message templates.
  • Base Path: /template
  • Router: src/api/routes/template.router.ts
  • Operations: Create, update, fetch templates

​
Settings

Configure instance-specific settings.
  • Base Path: /settings
  • Router: src/api/routes/settings.router.ts
  • Operations: Update instance settings, fetch configuration

​
Proxy Configuration

Manage proxy settings for instances.
  • Base Path: /proxy
  • Router: src/api/routes/proxy.router.ts
  • Operations: Configure proxy, remove proxy settings

​
Integrations

Evolution API supports multiple integration categories:
  • Channels: WhatsApp providers (Baileys, Business API, Evolution)
  • Chatbots: AI integrations (OpenAI, Dify, Typebot, Chatwoot, N8N)
  • Events: Event systems (WebSocket, RabbitMQ, SQS, NATS, Kafka, Pusher)
  • Storage: File storage (S3, MinIO)
Integration endpoints are mounted directly on the root path:
  • Channel Router: Manages WhatsApp provider integrations
  • Event Router: Configures webhook and event delivery
  • Chatbot Router: Connects AI and automation platforms
  • Storage Router: Configures cloud storage for media
See the respective integration documentation for detailed endpoint information.

​
Request/Response Flow

Evolution API follows a consistent request/response pattern:

​
Successful Request Example

POST https://api.yourdomain.com/instance/create
Content-Type: application/json
apikey: YOUR_GLOBAL_API_KEY

{
  "instanceName": "my-instance",
  "token": "my-instance-token",
  "qrcode": true
}

​
Error Request Example

GET https://api.yourdomain.com/instance/connectionState/nonexistent
Content-Type: application/json
apikey: INVALID_KEY

​
Multi-Tenant Architecture

Evolution API is built for multi-tenancy with complete data isolation:
Critical: All operations must be scoped by instanceName or instanceId. Cross-tenant data access is prevented at the database and application layers.

​
Instance Isolation

Each instance represents a separate WhatsApp connection with:
  • Isolated authentication: Per-instance API keys (tokens)
  • Separate data: Messages, chats, and contacts are instance-specific
  • Independent configuration: Settings, webhooks, and integrations per instance
  • Resource boundaries: Memory and connection management per instance

​
URL Pattern for Instance Operations

Most endpoints follow this pattern: 
/endpoint/:instanceName
Example: 
GET /chat/findChats/my-instance
The instanceName parameter is extracted from the URL path and validated before processing (src/api/abstract/abstract.router.ts:34).

​
Rate Limiting

Evolution API does not currently implement built-in rate limiting at the application level. You should implement rate limiting at the infrastructure level using:
  • Reverse proxy: Nginx, Apache, or Traefik with rate limit modules
  • API Gateway: AWS API Gateway, Kong, or similar solutions
  • Load balancer: CloudFlare, AWS ALB with rate limiting rules
For WhatsApp API compliance and stability:
  • Message sending: 80 messages per second per instance (WhatsApp limit)
  • API requests: 100 requests per second per client
  • Instance creation: 10 instances per minute per API key
  • Webhook retries: Exponential backoff with max 5 attempts

​
CORS Configuration

Configure Cross-Origin Resource Sharing (CORS) via environment variables: 
CORS_ORIGIN=https://app.yourdomain.com,https://admin.yourdomain.com
CORS_METHODS=POST,GET,PUT,DELETE
CORS_CREDENTIALS=true
The CORS configuration is defined in src/config/env.config.ts and applied at the Express application level.

​
Health Check Endpoint

Use the root endpoint for health checks: 
GET /
Response: 
{
  "status": 200,
  "message": "Welcome to the Evolution API, it is working!",
  "version": "2.1.0",
  "clientName": "your-client",
  "manager": "https://api.yourdomain.com/manager",
  "documentation": "https://doc.evolution-api.com",
  "whatsappWebVersion": "2.2412.54"
}
No authentication is required for the health check endpoint.

​
Metrics and Monitoring

Evolution API supports Prometheus metrics when enabled: 
PROMETHEUS_METRICS=true
METRICS_ALLOWED_IPS=127.0.0.1,10.0.0.0/8
METRICS_AUTH_REQUIRED=true
METRICS_USER=admin
METRICS_PASSWORD=secure-password
Metrics Endpoint: 
GET /metrics
Authorization: Basic base64(user:password)
Available metrics (defined in src/api/routes/index.router.ts:106-160):
  • evolution_environment_info: Environment and version information
  • evolution_instances_total: Total number of active instances
  • evolution_instance_up: Instance connection status (1 = connected, 0 = disconnected)
  • evolution_instance_state: Detailed instance state with labels

​
Next Steps

Authentication

Learn how to authenticate your API requests

Error Handling

Understand error codes and troubleshooting

Instance Management

Create and manage WhatsApp instances

Send Messages

Send messages, media, and interactive content

Build docs developers (and LLMs) love

Get started for freeTalk to us