Evolution API began as a WhatsApp controller API based on CodeChat, which in turn implemented the Baileys library. While originally focused on WhatsApp, Evolution API has grown into a comprehensive platform supporting multiple messaging services and integrations. We continue to acknowledge CodeChat for laying the groundwork.

Today, Evolution API is not limited to WhatsApp. It integrates with various platforms such as Typebot, Chatwoot, Dify, and OpenAI, offering a broad array of functionalities beyond messaging. Evolution API supports both the Baileys-based WhatsApp API and the official WhatsApp Business API, with upcoming support for Instagram and Messenger.

For those who need a more streamlined and performance-optimized version, check out Evolution API Lite. It's designed specifically for microservices, focusing solely on connectivity without integrations or audio conversion features. Ideal for environments that prioritize simplicity and efficiency.

Evolution API supports multiple types of connections to WhatsApp, enabling flexible and powerful integration options:

• WhatsApp API - Baileys:

  • A free API based on WhatsApp Web, leveraging the Baileys library.
  • This connection type allows control over WhatsApp Web functionalities through a RESTful API, suitable for multi-service chats, service bots, and other 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 (formerly Facebook).
  • This connection type offers a robust and reliable solution designed for businesses needing higher volumes of messaging and better integration support.
  • The Cloud API supports features such as end-to-end encryption, advanced analytics, and more comprehensive customer service tools.
  • To use this API, you must comply with Meta's policies and potentially pay for usage based on message volume and other factors.

Evolution API supports various integrations to enhance its functionality. Below is a list of available integrations and their uses:

• Typebot:

  • Build conversational bots using Typebot, integrated directly into Evolution with trigger management.

• Chatwoot:

  • Direct integration with Chatwoot for handling customer service for your business.

• RabbitMQ:

  • Receive events from the Evolution API via RabbitMQ.

• Apache Kafka:

  • Receive events from the Evolution API via Apache Kafka for real-time event streaming and processing.

• Amazon SQS:

  • Receive events from the Evolution API via Amazon SQS.

• Socket.io:

  • Receive events from the Evolution API via WebSocket.

• Dify:

  • Integrate your Evolution API directly with Dify AI for seamless trigger management and multiple agents.

• OpenAI:

  • Integrate your Evolution API with OpenAI for AI capabilities, including audio-to-text conversion, available across all Evolution integrations.

• Amazon S3 / Minio:

  • Store media files received in Amazon S3 or Minio.

This section is intended for API clients that consume manual recovery operations.

• POST /instance/recovery/:instanceName starts a manual recovery operation.
• GET /instance/recovery/:operationId/:instanceName returns operation status.
• The recovery flow is asynchronous:
  • POST returns 202 Accepted with operationId.
  • The actual execution continues in background and must be tracked via GET status endpoint.

• Layer B (hard reconnect, no session reset):
  • Forces reconnect/restart flow without recycling credentials/session.
  • Lower disruption profile when session is healthy but transport/socket is unstable.
• Layer C (session recycle):
  • Performs logout + credential/session recycle + new connect attempt.
  • May require a new QR code scan depending on provider/account state.
  • Requires explicit confirmation header: x-recovery-confirmation: true (or CONFIRM_LAYER_C).

curl --request POST \
  --url http://localhost:8080/instance/recovery/my-instance \
  --header 'Content-Type: application/json' \
  --header 'apikey: <YOUR_API_KEY>' \
  --data '{
    "layer": "B",
    "reason": "Transport reconnect after repeated socket instability",
    "force": false
  }'

{
  "instanceName": "my-instance",
  "layer": "B",
  "status": "accepted",
  "operationId": "my-instance:B:1715800000000"
}

curl --request POST \
  --url http://localhost:8080/instance/recovery/my-instance \
  --header 'Content-Type: application/json' \
  --header 'apikey: <YOUR_API_KEY>' \
  --header 'x-recovery-confirmation: true' \
  --data '{
    "layer": "C",
    "reason": "Credential/session recycle after persistent auth inconsistency",
    "force": true
  }'

{
  "instanceName": "my-instance",
  "layer": "C",
  "status": "accepted",
  "operationId": "my-instance:C:1715800001000"
}

Use the operationId from POST response:

curl --request GET \
  --url http://localhost:8080/instance/recovery/my-instance:C:1715800001000/my-instance \
  --header 'apikey: <YOUR_API_KEY>'

Example status response:

{
  "status": "running",
  "layer": "C",
  "startedAt": "2026-05-20T10:30:00.000Z",
  "finishedAt": null,
  "errorMessage": null
}

Possible values for status: accepted, running, completed, failed.

• Prefer Layer B first when:
  • Instance is known and exists.
  • You need fast reconnect with minimal user impact.
  • There are transient connection issues without evidence of credential corruption.
• Use Layer C when:
  • Layer B did not restore stability.
  • There are persistent auth/session inconsistencies.
  • You are operationally ready for possible QR re-authentication.

• 409 Conflict: another recovery is already in progress for the same instance.
  • Action: read the operationInProgress payload and poll status endpoint until completion.
  • Then decide whether a new operation is still needed.
• 422 Unprocessable Entity: semantic payload issue (for example integration/client contract mismatch).
  • Action: validate layer (B or C), reason length/format, and required confirmation for Layer C.
  • Re-send request only after fixing payload semantics.
• 404 Not Found:
  • Instance not found on POST recovery.
  • operationId not found for given instance on GET status.
  • Action: confirm instanceName, keep strict mapping between operation and instance, and retry with correct identifiers.

We value community input and feedback to continuously improve Evolution API:

• Feature Requests: Submit new feature ideas and vote on community proposals
• Roadmap: View planned features and development progress
• Changelog: Stay updated with the latest releases and improvements

• WhatsApp Group: Join our community for support and discussions
• Discord Community: Real-time chat with developers and users
• GitHub Issues: Report bugs and technical issues

• Security Policy: Guidelines for reporting security vulnerabilities
• Security Contact: contato@evolution-api.com

To continuously improve our services, we have implemented telemetry that collects data on the routes used, the most accessed routes, and the version of the API in use. We would like to assure you that no sensitive or personal data is collected during this process. The telemetry helps us identify improvements and provide a better experience for users.

Join our Evolution Pro community for expert support and a weekly call to answer questions. Visit the link below to learn more and subscribe:

Click here to learn more

https://github.com/sponsors/EvolutionAPI

We are proud to collaborate with the following content creators who have contributed valuable insights and tutorials about Evolution API:

• Promovaweb
• Sandeco
• Comunidade ZDG
• Francis MNO
• Pablo Cabral
• XPop Digital
• Costar Wagner Dev
• Dante Testa
• Rubén Salazar
• OrionDesign
• IMPA 365
• Comunidade Hub Connect
• dSantana Automações
• Edison Martins
• Astra Online
• MKT Seven Automações
• Vamos automatizar

Evolution API is licensed under the Apache License 2.0, with the following additional conditions:

1. LOGO and copyright information: In the process of using Evolution API's frontend components, you may not remove or modify the LOGO or copyright information in the Evolution API console or applications. This restriction is inapplicable to uses of Evolution API that do not involve its frontend components.

2. Usage Notification Requirement: If Evolution API is used as part of any project, including closed-source systems (e.g., proprietary software), the user is required to display a clear notification within the system that Evolution API is being utilized. This notification should be visible to system administrators and accessible from the system's documentation or settings page. Failure to comply with this requirement may result in the necessity for a commercial license, as determined by the producer.

Please contact contato@evolution-api.com to inquire about licensing matters.

Apart from the specific conditions mentioned above, all other rights and restrictions follow the Apache License 2.0. Detailed information about the Apache License 2.0 can be found at http://www.apache.org/licenses/LICENSE-2.0.

© 2025 Evolution API

You can publish the root Dockerfile image to AWS ECR with helper scripts for Linux/macOS (bash) and Windows (PowerShell).

export AWS_REGION=us-east-1
export AWS_ACCOUNT_ID=123456789012
export ECR_REPOSITORY=evolution-api
export IMAGE_TAG=v2.3.1-prod
# optional stable tag
export STABLE_TAG=prod

./scripts/push-ecr.sh

$env:AWS_REGION = 'us-east-1'
$env:AWS_ACCOUNT_ID = '123456789012'
$env:ECR_REPOSITORY = 'evolution-api'
$env:IMAGE_TAG = 'v2.3.1-prod'
# optional stable tag
$env:STABLE_TAG = 'prod'

./scripts/push-ecr.ps1

The script performs this flow automatically:

1. Creates the ECR repository when it does not exist.
2. Logs in to ECR.
3. Builds Dockerfile from repository root.
4. Tags image with ECR URI.
5. Pushes image to ECR.
6. Optionally tags/pushes a stable tag (STABLE_TAG).

A complete CloudFormation template for ECS Fargate deployment is available at:

• deploy/aws/evolution-api-ecs-fargate.yaml
• deploy/aws/README-ecs-fargate.md

This setup includes:

• ECS Task Definition using image ACCOUNT.dkr.ecr.REGION.amazonaws.com/evolution-api:<tag>
• Container port 8080
• Default image entrypoint/command preserved
• Environment + Secrets split (DATABASE_CONNECTION_URI and AUTHENTICATION_API_KEY via secrets)
• Private subnets for tasks, ALB + Target Group + HTTPS listener with ACM
• Autoscaling by CPU and memory with min 1 task
• CloudWatch logs (awslogs) and alarms (5xx, latency, running tasks)
• Redis and PostgreSQL wiring for production (sslmode=require in database URI)