WebSocket Integration

This page covers the real-time WebSocket connection used by the dashboard to stay up to date without manual refreshes.

If you’re embedding the website widget: the widget chat flow uses normal HTTP requests (see POST /api/widgets/:tenantId/chat). You don’t need to implement WebSockets to use the widget.

---

Tenant updates WebSocket (/api/ws/tenant)

The dashboard opens a WebSocket connection for real-time updates such as:

• conversation:new
• conversation:updated
• conversation:qualified
• message:new
• campaign:progress

Connection

const ws = new WebSocket('wss://api.yourdomain.com/api/ws/tenant');

Authentication (required within 5 seconds)

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'auth', token: jwtToken }));
};

Event handling

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case 'conversation:new':
    case 'conversation:updated':
    case 'message:new':
      // Update your UI
      break;
    case 'error':
      // Handle errors
      break;
  }
};

---

About /ws/chat

You may see references to a /ws/chat endpoint in older docs or prototypes. In the current codebase, widget chat is handled via the HTTP widget endpoints, and the /ws/chat path is not used for production widget messaging.