Skip to main content

08 - WebSocket API

Real-time event streaming via WebSocket.

8.1 Connection​

const ws = new WebSocket('ws://localhost:3001/ws?apiKey=YOUR_API_KEY');

Connection Acknowledgment​

{
  "type": "ack",
  "payload": {
    "message": "Connected to MultiWA WebSocket API",
    "clientId": "abc123",
    "timestamp": "2026-02-05T10:00:00.000Z"
  }
}

8.2 Message Protocol​

Subscribe to Events​

{
  "type": "subscribe",
  "payload": {
    "profileId": "profile-123",
    "events": ["message.received", "session.status"]
  },
  "requestId": "req_001"
}

Unsubscribe​

{
  "type": "unsubscribe",
  "requestId": "req_002"
}

Keep-Alive Ping​

{
  "type": "ping",
  "requestId": "ping_001"
}

Pong Response​

{
  "type": "pong",
  "payload": { "timestamp": "2026-02-05T10:00:00.000Z" },
  "requestId": "ping_001"
}

8.3 Event Types​

EventDescription
qr.updatedNew QR code generated
session.statusConnection status changed
message.receivedIncoming message
message.ackMessage status (sent/delivered/read)
*Subscribe to all events

8.4 Event Payloads​

message.received​

{
  "type": "event",
  "payload": {
    "event": "message.received",
    "profileId": "profile-123",
    "data": {
      "id": "true_628xxx_3EB0ABC",
      "from": "628123456789@c.us",
      "body": "Hello!",
      "type": "chat",
      "timestamp": "2026-02-05T10:00:00.000Z",
      "hasMedia": false
    },
    "timestamp": "2026-02-05T10:00:00.000Z"
  }
}

session.status​

{
  "type": "event",
  "payload": {
    "event": "session.status",
    "profileId": "profile-123",
    "data": {
      "status": "connected",
      "phone": "628123456789"
    },
    "timestamp": "2026-02-05T10:00:00.000Z"
  }
}

8.5 JavaScript Client Example​

const ws = new WebSocket('ws://localhost:3001/ws?apiKey=YOUR_API_KEY');
let pingInterval;

ws.onopen = () => {
  console.log('Connected');
  
  // Subscribe to events
  ws.send(JSON.stringify({
    type: 'subscribe',
    payload: {
      profileId: 'profile-123',
      events: ['message.received', 'session.status']
    },
    requestId: 'sub_001'
  }));

  // Keep-alive ping every 30s
  pingInterval = setInterval(() => {
    ws.send(JSON.stringify({ type: 'ping', requestId: `ping_${Date.now()}` }));
  }, 30000);
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  
  if (msg.type === 'event') {
    console.log('Event:', msg.payload.event, msg.payload.data);
  } else if (msg.type === 'ack') {
    console.log('Ack:', msg.payload);
  }
};

ws.onclose = () => {
  if (pingInterval) clearInterval(pingInterval);
  console.log('Disconnected');
};

← API Specification · Documentation Index · Webhook Events →