Evolution GO

Evolution Passkey Helper is a browser extension designed to complete the passkey (WebAuthn) pairing process for WhatsApp Web when connecting to Evolution GO.

Because WhatsApp requires a WebAuthn ceremony (navigator.credentials.get) for certain accounts, the process must be executed on the whatsapp.com origin. This extension runs exclusively on web.whatsapp.com to act as a bridge, allowing the browser to trigger the required biometric or PIN authentication without interacting with the WhatsApp login itself or collecting user data.

The Message API provides a complete set of endpoints for sending and managing WhatsApp messages. It is divided into two main functional areas:

1. Sending Messages: Capabilities include sending text, links with previews, media, polls, stickers, locations, and contacts. For interactive elements like buttons, lists, and carousels, refer to the Interactive Message API.
2. Managing Messages: Capabilities include reacting to messages, marking messages as read, editing, deleting, managing chat presence, downloading media, and checking message status.

Evolution GO is a WhatsApp API gateway built in Go that provides a RESTful interface for integrating with the WhatsApp Web protocol. It acts as an abstraction layer between your applications and WhatsApp, enabling message automation, multi-instance management, and standardized API integrations.

It is built on top of the whatsmeow library (a Go implementation of the WhatsApp Web Multi-Device protocol) and adds enterprise-grade features such as REST APIs, an event system, data persistence, and multi-instance management.

Evolution GO provides a robust set of features for WhatsApp integration:

• Multi-instance Management: Manage multiple WhatsApp accounts simultaneously.
• Multi-device Support: Native support for the WhatsApp Multi-Device protocol.
• Real-time Events: Receive events via Webhooks, RabbitMQ, NATS, or WebSockets.
• Media Storage: Integrated support for MinIO and S3 for storing media files.
• High Performance: Built with Go for high-throughput API gateway capabilities.
• Extensive API: 79 documented REST endpoints covering messages, instances, users, groups, chats, labels, calls, communities, and newsletters.

Evolution GO supports three main deployment strategies depending on your requirements for complexity and scalability:

• Docker Compose: Best for development, testing, and small deployments. It is low complexity but limited to a single host.
• Docker Swarm: Recommended for small to medium production environments requiring High Availability (HA). It offers moderate complexity and good multi-host scalability.
• Kubernetes: Designed for enterprise-grade production and advanced orchestration. It has high complexity but provides excellent scalability.

The Evolution GO stack typically consists of the Evolution GO API (Port 4000), PostgreSQL (Auth and Users DB), RabbitMQ (Events), MinIO (Media), and optionally NATS.

An instance is an independent WhatsApp connection. Each instance operates in complete isolation, meaning they do not share messages, contacts, or configurations.

Key characteristics include:

• Isolation: Each instance has its own unique WhatsApp number and operates independently.
• Persistence: Connections are saved. If the server restarts, the instance reconnects automatically without needing to re-scan the QR Code.
• Multi-Device: Uses the WhatsApp Web protocol, allowing it to function like WhatsApp on a computer without disconnecting the mobile phone (up to 4 devices per number).

The Evolution GO Events System provides real-time WhatsApp event notifications through multiple communication channels. You can activate multiple channels simultaneously, and events will be dispatched to all configured destinations.

Available Channels

The connection follows a specific state machine. Understanding these states is critical for managing the UI and handling connection logic:

• CREATED: Instance created, never connected.
• CONNECTING: WebSocket is initiating.
• WAITING_QR: Waiting for the user to scan the QR Code.
• PAIRING: Cryptographic keys are being exchanged.
• OPEN: Connected and authenticated.
• DISCONNECTED: Connection lost or user logged out.

When sending messages to a group, you can mention specific users or all users.

Mention specific users: Use mentionedJid with an array of JIDs.

Mention all users: Use mentionAll: true.

Example:

{
  "number": "120363XXXXXXXXXX@g.us",
  "text": "Hello @user, how are you?",
  "mentionedJid": "5511888888888@s.whatsapp.net"
}

Example (Mention All):

{
  "number": "120363XXXXXXXXXX@g.us",
  "text": "@everyone Meeting at 3pm!",
  "mentionAll": true
}

Evolution GO uses a two-tier classification system for events:

1. Event Categories (used in subscribe): Written in UPPERCASE (e.g., MESSAGE, GROUP, CALL). These are used to filter which groups of events you want to receive.
2. Individual Events (the actual emitted events): Written in lowercase (e.g., message, groupinfo, calloffer). These are the specific event names found in the webhook or queue payload.

Mapping Example:

• Category MESSAGE $\rightarrow$ Individual events: Message, SendMessage, Receipt.
• Category GROUP $\rightarrow$ Individual events: GroupInfo, JoinedGroup.
• Category CALL $\rightarrow$ Individual events: CallOffer, CallAccept, CallTerminate.

You can manage privacy settings using two endpoints:

1. Consult Privacy: GET /user/privacy retrieves current settings for GroupAdd, LastSeen, Status, Profile, ReadReceipts, CallAdd, and Online.
2. Configure Privacy: POST /user/privacy updates these settings.

Allowed values for all privacy fields:

• all: Everyone
• contacts: Only contacts
• contact_blacklist: My contacts except...
• none: No one
• match_last_seen: Same as 'Last Seen' setting

# Example: Configure privacy settings
curl -X POST http://localhost:4000/user/privacy \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "groupAdd": "contacts",
    "lastSeen": "contacts",
    "status": "contacts",
    "profile": "all",
    "readReceipts": "all",
    "callAdd": "all",
    "online": "all"
  }'