WebSocket

Receive real-time WhatsApp events through WebSocket connections for instant bidirectional communication

WebSocket integration provides real-time, bidirectional communication between Evolution API and your applications. Perfect for dashboards, live chat interfaces, and real-time monitoring.

Configuration

Configure WebSocket through environment variables:

.env

# Enable WebSocket server
WEBSOCKET_ENABLED=true

# Enable global events (all instances)
WEBSOCKET_GLOBAL_EVENTS=false

# Allowed hosts for connections (comma-separated)
WEBSOCKET_ALLOWED_HOSTS=127.0.0.1,::1,::ffff:127.0.0.1

Host Restrictions

Control which hosts can connect to your WebSocket server:

Localhost Only

Default configuration for local development:

.env

WEBSOCKET_ALLOWED_HOSTS=127.0.0.1,::1,::ffff:127.0.0.1

Specific IPs

Allow specific IP addresses:

.env

WEBSOCKET_ALLOWED_HOSTS=192.168.1.100,10.0.0.50

Allow All

Allow connections from any host:

.env

WEBSOCKET_ALLOWED_HOSTS=*

Only use * in trusted networks or with proper authentication.

Connection Modes

WebSocket supports two connection modes:

Per-Instance Namespace

Connect to a specific instance namespace:

const socket = io('http://localhost:8080/my_instance', {
  query: {
    apikey: 'YOUR_API_KEY'
  }
});

Receives events only from that instance.

Global Events

Connect to the default namespace to receive all events:

.env

WEBSOCKET_GLOBAL_EVENTS=true

const socket = io('http://localhost:8080', {
  query: {
    apikey: 'YOUR_GLOBAL_API_KEY'
  }
});

Requires global API key authentication.

Authentication

WebSocket connections require authentication via API key:

1. Query Parameter

   Pass API key in connection URL:

   const socket = io('http://localhost:8080', {
     query: {
       apikey: 'YOUR_API_KEY'
     }
   });
   
2. Header (Alternative)

   Or pass as custom header:

   const socket = io('http://localhost:8080', {
     extraHeaders: {
       apikey: 'YOUR_API_KEY'
     }
   });
   
3. Validation

   Evolution API validates the API key:

   • For instance namespaces: Instance API key
   • For global connection: Global API key

Connections without valid API keys will be rejected with an authentication error.

Connection Examples

JavaScript (Socket.IO)

const io = require('socket.io-client');

// Connect to instance namespace
const socket = io('http://localhost:8080/my_instance', {
  query: {
    apikey: 'YOUR_API_KEY'
  },
  transports: ['websocket'],
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionAttempts: 10
});

// Connection events
socket.on('connect', () => {
  console.log('Connected to WebSocket');
  console.log('Socket ID:', socket.id);
});

socket.on('disconnect', (reason) => {
  console.log('Disconnected:', reason);
});

socket.on('connect_error', (error) => {
  console.error('Connection error:', error.message);
});

// Listen for WhatsApp events
socket.on('messages.upsert', (data) => {
  console.log('New message:', data);
});

socket.on('qrcode.updated', (data) => {
  console.log('QR Code updated:', data.data.qrcode);
});

socket.on('connection.update', (data) => {
  console.log('Connection status:', data.data.state);
});

Available Events

You can listen for any WhatsApp event through WebSocket:

Instance Events

• qrcode.updated - QR code changes
• connection.update - Connection status changes

Message Events

• messages.set - Message history loaded
• messages.upsert - New messages received/sent
• messages.edited - Messages edited
• messages.update - Message status updates (read, delivered)
• messages.delete - Messages deleted
• send.message - Message sent confirmation
• send.message.update - Sent message status update

Contact Events

• contacts.set - Contacts loaded
• contacts.upsert - Contact added/updated
• contacts.update - Contact information changed
• presence.update - Contact online/offline status

Chat Events

• chats.set - Chats loaded
• chats.upsert - New chat created
• chats.update - Chat updated
• chats.delete - Chat deleted

Group Events

• groups.upsert - Group created/joined
• group.update - Group information changed
• group.participants.update - Participants added/removed

Other Events

• labels.edit - Label edited
• labels.association - Label associated with chat
• call - Incoming call

Per-Instance Configuration

Configure which events are emitted for a specific instance:

cURL

curl -X POST https://your-api.com/websocket/set/instance_name \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "websocket": {
      "enabled": true,
      "events": [
        "MESSAGES_UPSERT",
        "MESSAGES_UPDATE",
        "QRCODE_UPDATED",
        "CONNECTION_UPDATE"
      ]
    }
  }'

Event Payload Structure

All WebSocket events have a consistent 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"
}

Sending Custom Commands

Send custom commands to WhatsApp through WebSocket:

// Send a custom Baileys node/stanza
socket.emit('sendNode', {
  instanceId: 'my_instance',
  stanza: {
    tag: 'iq',
    attrs: { type: 'get', xmlns: 'w:web', to: 'c.us' },
    content: [{ tag: 'status', attrs: {} }]
  }
});

Sending custom nodes requires deep knowledge of WhatsApp’s protocol. Incorrect usage may cause connection issues.

Best Practices

1. Handle Reconnections

   Always enable automatic reconnection:

   const socket = io(url, {
     reconnection: true,
     reconnectionDelay: 1000,
     reconnectionAttempts: 10
   });
   
2. Use Event Filtering

   Configure only needed events to reduce bandwidth:

   websocket: {
     events: ['MESSAGES_UPSERT', 'CONNECTION_UPDATE']
   }
   
3. Implement Error Handling

   Handle all error events:

   socket.on('connect_error', (error) => {
     console.error('Connection failed:', error);
   });
   
   socket.on('error', (error) => {
     console.error('Socket error:', error);
   });
   
4. Secure Your Connection

   • Use HTTPS/WSS in production
   • Restrict WEBSOCKET_ALLOWED_HOSTS
   • Never expose API keys in client-side code
5. Monitor Connection State

   Track connection status in your UI:

   socket.on('connect', () => setStatus('Connected'));
   socket.on('disconnect', () => setStatus('Disconnected'));
   

CORS Configuration

WebSocket respects your CORS settings:

.env

# Allow specific origins
CORS_ORIGIN=https://your-app.com,https://dashboard.your-app.com

# Or allow all origins
CORS_ORIGIN=*

WebSocket CORS is automatically configured based on your CORS_ORIGIN setting.

Troubleshooting

Connection rejected

1. Verify API key is correct
2. Check that WebSocket is enabled: WEBSOCKET_ENABLED=true
3. Ensure your IP is in WEBSOCKET_ALLOWED_HOSTS
4. Check Evolution API logs for authentication errors

No events received

1. Verify instance is connected to WhatsApp
2. Check that specific events are enabled in instance configuration
3. Ensure you’re connected to correct namespace
4. Enable logging to see if events are being emitted

Frequent disconnections

1. Check network stability
2. Increase reconnectionDelay in client configuration
3. Monitor server resources (CPU, memory)
4. Check for firewall issues blocking WebSocket connections

Authentication failed

1. Verify API key format (no extra spaces)
2. For instance namespaces, use instance API key
3. For global events, use global API key
4. Check that instance exists and is active

CORS errors in browser

1. Add your domain to CORS_ORIGIN
2. Restart Evolution API after changing CORS settings
3. Check browser console for specific CORS error
4. Ensure protocol matches (http/https)