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

Evolution API

--- ## 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](https://github.com/code-chat-br/whatsapp-api), which in turn implemented the [Baileys](https://github.com/WhiskeySockets/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](https://github.com/evolution-foundation/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](https://github.com/WhiskeySockets/Baileys). 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](https://typebot.io/)** — conversational bots with trigger management - **[Chatwoot](https://www.chatwoot.com/)** — customer service platform - **[RabbitMQ](https://www.rabbitmq.com/)** — event streaming via AMQP - **[Apache Kafka](https://kafka.apache.org/)** — real-time event streaming and processing - **[Amazon SQS](https://aws.amazon.com/sqs/)** — cloud-based message queuing - **[Socket.io](https://socket.io/)** — real-time WebSocket events - **[Dify](https://dify.ai/)** — AI agent workflows - **[OpenAI](https://openai.com/)** — AI capabilities including audio-to-text conversion - **Amazon S3 / [MinIO](https://min.io/)** — media file storage --- ## Quick Start ### Prerequisites - **Node.js** 20+ - **PostgreSQL** or **MySQL** - **Redis** (recommended for caching) ### Installation ```bash 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 ```bash # Set the database provider export DATABASE_PROVIDER=postgresql # or mysql # Generate Prisma client npm run db:generate # Deploy migrations npm run db:deploy ``` ### Running ```bash # Development with hot reload npm run dev:server # Production build and run npm run build npm run start:prod ``` ### Docker ```bash docker pull evoapicloud/evolution-api:latest docker run -p 8080:8080 --env-file .env evoapicloud/evolution-api:latest ``` --- ## 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](https://evolutionfoundation.com.br) | | Documentation | [docs.evolutionfoundation.com.br](https://docs.evolutionfoundation.com.br) | | Community | [evolutionfoundation.com.br/community](https://evolutionfoundation.com.br/community) | | Docker Hub | [evoapicloud/evolution-api](https://hub.docker.com/r/evoapicloud/evolution-api) | | Changelog | [CHANGELOG.md](./CHANGELOG.md) | | Contributing | [CONTRIBUTING.md](./CONTRIBUTING.md) | | Security | [SECURITY.md](./SECURITY.md) | --- ## Hosting Deploy Evolution API with optimized infrastructure through our HostGator partnership: [**Evolution API VPS — HostGator**](https://evolution-api.com/vps-evolution-api) --- ## 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](./CONTRIBUTING.md) for guidelines on how to submit issues, propose features, and open pull requests. Join our [community](https://evolutionfoundation.com.br/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](./SECURITY.md) for details. --- ## Acknowledgments - [CodeChat](https://github.com/code-chat-br/whatsapp-api) — original WhatsApp API foundation - [Baileys](https://github.com/WhiskeySockets/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](./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](./TRADEMARKS.md) for the brand assets policy. Third-party attributions are documented in [NOTICE](./NOTICE). --- ## 2. Official Technical Reference & Guides (EvolutionAPI/docs) # 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](https://starter.mintlify.com/quickstart)** ## AI-assisted writing Set up your AI coding tool to work with Mintlify: ```bash 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](/ai-tools) for tool-specific setup. ## Development Install the [Mintlify CLI](https://www.npmjs.com/package/mint) 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 Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch. ## Need help? ### Troubleshooting - 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 - [Mintlify documentation](https://mintlify.com/docs)