Skip to content

README.md

Latest commit

 

History

History
251 lines (169 loc) · 9.3 KB

README.md

File metadata and controls

251 lines (169 loc) · 9.3 KB

Evolution Foundation

Evolution API

Open-source REST API for WhatsApp and multi-channel messaging — part of the Evolution Foundation ecosystem.

Latest version License: Apache 2.0 Documentation Community Docker image

Website · Documentation · Community · Support

About

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

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

Evolution API supports multiple connection types to WhatsApp:

WhatsApp API — Baileys

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

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

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

Prerequisites

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

Installation

git clone git@github.com: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

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

# Generate Prisma client
npm run db:generate

# Deploy migrations
npm run db:deploy

Running

# Development with hot reload
npm run dev:server

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

Docker

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

License Activation

Starting from v2.4.0, every Evolution API instance must be activated against the Evolution Foundation licensing server before serving API traffic. While unactivated, business endpoints return HTTP 503 LICENSE_REQUIRED with a register_url pointing to the manager UI.

There are two ways to activate:

  1. Set a known licensing key as AUTHENTICATION_API_KEY in your .env. The server validates it on boot, persists it locally and activates the instance silently.
  2. Activate via the manager UI at https://<your-host>/manager/login. On first login the manager detects an unlicensed backend and redirects you to the registration server; once you complete the form you are redirected back and the dashboard becomes accessible.

Activation is a one-time operation — the key is persisted in the RuntimeConfig table and reused across restarts. The licensing server is only consulted again for fire-and-forget heartbeats (telemetry) and a best-effort /v1/deactivate notice on graceful shutdown.

Full activation guide: https://docs.evolutionfoundation.com.br/licensing

Architecture

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

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

Authentication

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

Message queue support

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

Media handling

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

Documentation

Resource Link
Website evolutionfoundation.com.br
Documentation docs.evolutionfoundation.com.br
Community evolutionfoundation.com.br/community
Docker Hub evoapicloud/evolution-api
Changelog CHANGELOG.md
Contributing CONTRIBUTING.md
Security SECURITY.md

Hosting

Deploy Evolution API with optimized infrastructure through our HostGator partnership:

Evolution API VPS — HostGator

Telemetry

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

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

For security issues, do not open a public issue. Email suporte@evofoundation.com.br or use GitHub's private vulnerability reporting. See SECURITY.md for details.

Acknowledgments

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

License

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 suporte@evofoundation.com.br.

Trademarks

"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.

Made by Evolution Foundation · © 2026