1. Project Overview & Quickstart (EvolutionAPI/evolution-api) Copy Chapter

Evolution API

About Copy Chapter

Evolution API is a powerful, production-ready REST API for WhatsApp and multi-channel messaging. Originally focused on WhatsApp, it has grown into a comprehensive platform supporting multiple messaging providers and integrations.

Today, Evolution API supports both the Baileys-based WhatsApp Web API and the official WhatsApp Cloud API, plus integrations with Typebot, Chatwoot, Dify, OpenAI, RabbitMQ, Apache Kafka, Amazon SQS, Socket.io, Amazon S3 / MinIO, and more.

Evolution API began as a WhatsApp controller API based on CodeChat, which in turn implemented the Baileys library. We continue to acknowledge CodeChat for laying the groundwork.

Part of the Evolution Foundation ecosystem Copy Chapter

Evolution API is one of the messaging engines maintained by Evolution Foundation. It is used as a WhatsApp provider by the Evo CRM Community and other projects in the ecosystem.

Connection Types Copy Chapter

Evolution API supports multiple connection types to WhatsApp:

WhatsApp API — Baileys Copy Section

A free API based on WhatsApp Web, leveraging the Baileys library. Suitable for multi-service chats, service bots, and WhatsApp-integrated systems. Note: this method relies on the web version of WhatsApp and may have limitations compared to official APIs.

WhatsApp Cloud API Copy Section

The official API provided by Meta. Designed for businesses with higher messaging volumes and stronger integration support, including end-to-end encryption, advanced analytics, and customer service tools. Requires compliance with Meta's policies and may incur per-message costs.

Integrations Copy Chapter

Evolution API integrates natively with many platforms:

• Typebot — conversational bots with trigger management
• Chatwoot — customer service platform
• RabbitMQ — event streaming via AMQP
• Apache Kafka — real-time event streaming and processing
• Amazon SQS — cloud-based message queuing
• Socket.io — real-time WebSocket events
• Dify — AI agent workflows
• OpenAI — AI capabilities including audio-to-text conversion
• Amazon S3 / MinIO — media file storage

Quick Start Copy Chapter

Prerequisites Copy Section

• Node.js 20+
• PostgreSQL or MySQL
• Redis (recommended for caching)

Installation Copy Section

git clone [email protected]:evolution-foundation/evolution-api.git
cd evolution-api

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your database, Redis, and API key

Database setup Copy Section

# Set the database provider
export DATABASE_PROVIDER=postgresql  # or mysql

# Generate Prisma client
npm run db:generate

# Deploy migrations
npm run db:deploy

Running Copy Section

# Development with hot reload
npm run dev:server

# Production build and run
npm run build
npm run start:prod

Docker Copy Section

docker pull evoapicloud/evolution-api:latest
docker run -p 8080:8080 --env-file .env evoapicloud/evolution-api:latest

Architecture Copy Chapter

Evolution API is built with a multi-provider, event-driven architecture:

Client / CRM
     ↓
Evolution API
  ├── Channel Integrations (Baileys / Cloud API)
  ├── Chatbot Integrations (Typebot, Chatwoot, OpenAI, Dify, Flowise, N8N)
  ├── Event Integrations (WebSocket, RabbitMQ, SQS, NATS, Pusher)
  └── Storage Integrations (S3, MinIO)

Built with Node.js 20+, TypeScript 5+, and Express.js, it provides extensive integrations with chatbots, CRM systems, and messaging platforms.

Multi-database support Copy Section

PostgreSQL and MySQL via Prisma ORM with provider-specific schemas and migrations.

Authentication Copy Section

• API key-based authentication via apikey header
• Instance-specific tokens for WhatsApp connection authentication
• Webhook signature validation for external integrations

Message queue support Copy Section

RabbitMQ, Amazon SQS, NATS, Pusher and WebSocket for events. Configurable per instance.

Media handling Copy Section

Local storage or S3/MinIO. Automatic media download from WhatsApp. Optional audio transcription via OpenAI.

Documentation Copy Chapter

Hosting Copy Chapter

Deploy Evolution API with optimized infrastructure through our HostGator partnership:

Evolution API VPS — HostGator

Telemetry Copy Chapter

Evolution API collects anonymous telemetry data (routes used, most accessed routes, API version) to help improve the service. No sensitive or personal data is collected. This information helps us identify improvements and provide a better experience for users.

Contributing Copy Chapter

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to submit issues, propose features, and open pull requests.

Join our community to discuss ideas and collaborate.

Security Copy Chapter

For security issues, do not open a public issue. Email [email protected] or use GitHub's private vulnerability reporting. See SECURITY.md for details.

Acknowledgments Copy Chapter

• CodeChat — original WhatsApp API foundation
• Baileys — WhatsApp Web library

License Copy Chapter

Evolution API is licensed under the Apache License 2.0, with additional brand-protection conditions (LOGO/copyright preservation and Usage Notification requirement). See LICENSE for full details.

For licensing inquiries, contact [email protected].

Trademarks Copy Chapter

"Evolution Foundation", "Evolution" and "Evolution API" are trademarks of Evolution Foundation. See TRADEMARKS.md for the brand assets policy.

Third-party attributions are documented in NOTICE.

2. Official Technical Reference & Guides (EvolutionAPI/docs) Copy Chapter

Mintlify Starter Kit

Use the starter kit to get your docs deployed and ready to customize.

Click the green Use this template button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with

• Guide pages
• Navigation
• Customizations
• API reference pages
• Use of popular components

Follow the full quickstart guide

AI-assisted writing Copy Chapter

Set up your AI coding tool to work with Mintlify:

npx skills add https://mintlify.com/docs

This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance.

See the AI tools guides for tool-specific setup.

Development Copy Chapter

Install the Mintlify CLI to preview your documentation changes locally. To install, use the following command:

npm i mint

Run the following command at the root of your documentation, where your docs.json is located:

mint dev

View your local preview at http://localhost:3000.

Publishing changes Copy Chapter

Install our GitHub app from your dashboard to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.

Need help? Copy Chapter

Troubleshooting Copy Section

• If your dev environment isn't running: Run mint update to ensure you have the most recent version of the CLI.
• If a page loads as a 404: Make sure you are running in a folder with a valid docs.json.

Resources Copy Section

• Mintlify documentation