Skip to main content
RabbitMQ integration enables you to stream WhatsApp events to RabbitMQ queues for asynchronous processing, load balancing, and microservices architecture.

​
Configuration

Configure RabbitMQ connection and event routing through environment variables.

​
Connection Settings

.env
# Enable RabbitMQ integration
RABBITMQ_ENABLED=true

# RabbitMQ connection URI
RABBITMQ_URI=amqp://username:password@localhost:5672

# Exchange name for routing events
RABBITMQ_EXCHANGE_NAME=evolution

# Maximum frame size (bytes)
RABBITMQ_FRAME_MAX=8192
The connection URI format is: amqp://username:password@host:port/vhost
  • Default port: 5672
  • Default vhost: /
  • For RabbitMQ with SSL, use amqps:// protocol

​
Global vs Instance Events

You can configure RabbitMQ to work in two modes:
Each instance gets its own queues and exchange:
.env
RABBITMQ_ENABLED=true
RABBITMQ_GLOBAL_ENABLED=false
Creates queues like:
  • my_instance.messages.upsert
  • my_instance.qrcode.updated
  • my_instance.connection.update

​
Exchange and Queue Setup

Evolution API automatically creates:
1

Topic Exchange

A topic exchange with the configured name (default: evolution)
  • Durable: Survives broker restarts
  • Type: Topic (enables routing pattern matching)
2

Quorum Queues

Queues for each enabled event:
  • Durable: Messages persist to disk
  • Type: Quorum (replicated, highly available)
  • Auto-delete: Disabled
3

Queue Bindings

Bindings between queues and exchange using routing keys:
  • Routing key format: event name (e.g., MESSAGES_UPSERT)
  • Enables selective event consumption

​
Available Events

Configure which events are sent to RabbitMQ:
.env
# Application lifecycle
RABBITMQ_EVENTS_APPLICATION_STARTUP=false
RABBITMQ_EVENTS_INSTANCE_CREATE=false
RABBITMQ_EVENTS_INSTANCE_DELETE=false

# Connection events
RABBITMQ_EVENTS_QRCODE_UPDATED=true
RABBITMQ_EVENTS_CONNECTION_UPDATE=true
RABBITMQ_EVENTS_REMOVE_INSTANCE=false
RABBITMQ_EVENTS_LOGOUT_INSTANCE=false

​
Per-Instance Configuration

Configure RabbitMQ events for a specific instance via API: 
curl -X POST https://your-api.com/rabbitmq/set/instance_name \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rabbitmq": {
      "enabled": true,
      "events": [
        "MESSAGES_UPSERT",
        "MESSAGES_UPDATE",
        "QRCODE_UPDATED",
        "CONNECTION_UPDATE"
      ]
    }
  }'

​
Message Format

Messages published to RabbitMQ have the following JSON structure: 
{
  "event": "messages.upsert",
  "instance": "my_instance",
  "data": {
    // Event-specific data
  },
  "server_url": "https://your-evolution-api.com",
  "date_time": "2024-03-04T10:30:00.000Z",
  "sender": "5511999999999",
  "apikey": "instance_api_key"
}

​
Consuming Events

Here are examples of consuming events from RabbitMQ: 
const amqp = require('amqplib');

async function consumeEvents() {
  const connection = await amqp.connect('amqp://localhost');
  const channel = await connection.createChannel();
  
  const exchange = 'evolution';
  const queue = 'evolution.messages.upsert';
  
  // Ensure exchange exists
  await channel.assertExchange(exchange, 'topic', { durable: true });
  
  // Ensure queue exists
  await channel.assertQueue(queue, {
    durable: true,
    arguments: { 'x-queue-type': 'quorum' }
  });
  
  // Bind queue to exchange
  await channel.bindQueue(queue, exchange, 'MESSAGES_UPSERT');
  
  console.log('Waiting for messages...');
  
  // Consume messages
  channel.consume(queue, (msg) => {
    if (msg !== null) {
      const event = JSON.parse(msg.content.toString());
      console.log('Received event:', event.event);
      console.log('Instance:', event.instance);
      console.log('Data:', event.data);
      
      // Acknowledge message
      channel.ack(msg);
    }
  });
}

consumeEvents().catch(console.error);

​
Connection Resilience

Evolution API implements automatic reconnection with exponential backoff:
  • Initial delay: 5 seconds
  • Maximum attempts: 10
  • Exponential backoff: Delay doubles each attempt (up to 5 times)
  • Heartbeat: 30 seconds to detect connection loss
During connection loss, Evolution API will queue events in memory and retry delivery. Monitor your RabbitMQ connection status in the logs.

​
Best Practices

1

Use Quorum Queues

Evolution API creates quorum queues by default for high availability and data safety. Ensure your RabbitMQ cluster has at least 3 nodes for optimal quorum queue performance.
2

Enable Acknowledgments

Always acknowledge messages after successful processing to prevent message loss:
channel.ack(msg);
3

Handle Processing Errors

Implement error handling and use dead letter queues for failed messages:
try {
  await processEvent(event);
  channel.ack(msg);
} catch (error) {
  console.error('Processing failed:', error);
  channel.nack(msg, false, false); // Send to DLQ
}
4

Set Prefetch Count

Limit concurrent message processing per consumer:
channel.prefetch(10); // Process 10 messages at a time
5

Monitor Queue Depth

Set up alerts for queue depth to detect processing bottlenecks.
Quorum queues require RabbitMQ 3.8.0 or later. If you’re using an older version, Evolution API will fall back to classic durable queues.

​
Troubleshooting

  1. Verify RabbitMQ is running: systemctl status rabbitmq-server
  2. Check the connection URI in your .env file
  3. Ensure firewall allows port 5672 (or your configured port)
  4. Verify credentials are correct
  1. Check that specific events are enabled in configuration
  2. Verify RABBITMQ_ENABLED=true
  3. Check Evolution API logs for RabbitMQ errors
  4. Ensure the instance is connected to WhatsApp
  1. Verify queue binding to exchange
  2. Check routing key matches event name
  3. Ensure consumer is acknowledging messages
  4. Check for messages in dead letter queue
  1. Check queue depth - consumers may be too slow
  2. Increase number of consumers
  3. Optimize message processing code
  4. Consider increasing RABBITMQ_FRAME_MAX if messages are large

Build docs developers (and LLMs) love

Get started for freeTalk to us