WebSocket API

Live chat goes over Socket.IO at namespace /chat. Customers, agents, and read-only broadcast viewers all share this namespace — server-side handlers gate per role.

Connection

Connect with { token, orgId } in the handshake auth. The token is a JWT issued by POST /profile/signin (agent/user) or POST /profile/customer/signin (customer).

import { io } from 'socket.io-client';

const socket = io('https://appengine.appmint.io/chat', {
  transports: ['websocket'],
  auth: {
    token: '<jwt>',
    orgId: '<your-org-id>',
    deviceId: 'device-stable-uuid',
    context: {
      chatSessionId: localStorage.getItem('chatSessionId') || undefined,
      configId: '<chat-config-id>',
      currentUrl: window.location.href,
    },
  },
});

socket.on('authenticate', (result) => {
  if (!result.success) return console.error(result.error);
  if (result.chatSessionId) {
    localStorage.setItem('chatSessionId', result.chatSessionId);
  }
});

The server emits authenticate once it has verified the token. Failure causes an immediate disconnect.

Authentication response

{
  success: true,
  user: { email: '[email protected]', name: 'Alice', role: 'customer' },
  chatSessionId: 'cs_abc...',  // customer only
  isGuest: false,              // customer only
  config: {                    // when configId was passed
    configId: '...',
    ai: '<assistantId>',
    agents: [{ user: '[email protected]' }],
    status: 'active',
    defaultPath: '/'
  }
}

Events the client emits

chat-message — primary send path

socket.emit('chat-message', {
  message: 'Hi, I need help with my order',
  chatSessionId: '<session>',  // customer
  files: [],                   // optional uploads
  assistantId: '<override>',   // optional, defaults to session.assistantId
});

Behaviour depends on session state:

• AI path — config has an ai assistant and no human is assigned. The server broadcasts the user message to the chat room, then streams AI tokens via chat-stream.
• Agent path — a human agent is assigned (via pick-next or takeover-chat). The message is delivered as message to the agent's identity room.
• Queue path — no AI, no agent. The customer is enqueued and the agent panels receive queue-notification.

Other client events

Events the server emits

chat-stream — AI streaming

socket.on('chat-stream', (evt) => {
  switch (evt.event) {
    case 'chunk':       appendText(evt.data); break;
    case 'tool-use':    showTool(evt.tool, evt.input); break;
    case 'tool-result': showResult(evt.tool, evt.result); break;
    case 'end':         finalize(evt.sk); break;
    case 'error':       showError(evt.error); break;
  }
});

Other server events

Message shape

The server sends both flat and nested fields so widget and admin clients both work:

{
  messageId: 'sk-abc',
  sk: 'sk-abc',
  chatId: 'customer:[email protected]',
  from: '[email protected]',
  to: '[email protected]',
  content: 'Hello',
  type: 'user' | 'ai-assistant' | 'system',
  senderRole: 'customer' | 'agent',
  sentTime: 1714000000000,
  status: 'sent',
  files: [...],
  data: { /* same fields nested */ },
}

Inactivity timeouts

Once an agent picks up a customer, two Redis keys arm:

• chat-response-timeout:{orgId}:{chatId} — 5 min, expects a customer reply
• chat-global-timeout:{orgId}:{chatId} — 30 min hard cap

Warnings fire 1 minute before each timeout. On expiry the server emits a system message, then chat-ended with reason: 'inactivity'. Any new customer message resets both keys.