WebSocket

For live chat UIs, the messaging client opens a bidirectional WebSocket session: send message frames, receive the reply as a token stream, and recover missed events after a reconnect. Authentication is handled for you, and it works in both Node and the browser.

Open a session

import { ApolloMessagingClient } from '@aui.io/aui-client';

const client = new ApolloMessagingClient({ publishableKey: 'pk_network_...' });

const socket = await client.connect();
await socket.waitForOpen();

connect() accepts optional arguments:

const socket = await client.connect({
  headers: { 'x-request-tag': 'support-widget' }, // extra connect headers
  debug: false,                                   // log socket activity
  reconnectAttempts: 30,                          // default: 30
});

Send a message

The socket sends typed frames. A message frame submits a turn — note that on the WebSocket the target agent is explicit; use the id resolved from your key:

const { agentId } = await client.getContext();

socket.sendMessage({
  type: 'message',
  agent_id: agentId!,
  user_id: 'end-user-123',
  text: 'I am looking for a built-in microwave',
  // thread_id: existingThreadId,      // omit to auto-create a thread
  // context: { url: location.href },  // originating page URL
  // agent_variables: { ... },
});

Receive envelopes

Every server frame is a sequenced envelope. Register handlers with on(event, handler) — events are open, message, error, and close:

let lastSeq = -1;
let threadId: string | undefined;

socket.on('message', (envelope) => {
  if (envelope.seq > 0) lastSeq = envelope.seq;

  switch (envelope.type) {
    case 'thread':      // announced once per thread: the resolved id
      threadId = envelope.data?.thread_id;
      break;

    case 'event': {     // streaming events while the agent works
      const name = envelope.data?.channel?.event_name;
      if (name === 'thread-message-text-content-updated') {
        process.stdout.write((envelope.data?.data as any)?.text ?? '');
      }
      break;
    }

    case 'message':     // the completed reply (plus trace_info when enabled)
      console.log('\ncomplete:', envelope.data?.text);
      break;

    case 'error':       // session- or turn-level error; the socket stays open
      console.error(envelope.data);
      break;
  }
});

socket.on('close', (event) => console.log('closed', event.code));
socket.on('error', (error) => console.error(error));

Envelope `type`	Meaning	`data`
`thread`	The resolved thread id (once per thread)	`{ thread_id }`
`event`	Streaming event; token deltas arrive as `thread-message-text-content-updated` with the text under `data.data.text`	`Apollo.StreamEvent`
`message`	Turn complete — the full reply	`Apollo.Message` + optional `trace_info`
`error`	Session error (`{ error, code }`) or turn error (`{ message, status_code }`)	varies

on() registers a single handler per event — calling it again for the same event replaces the previous handler.

Resume after a reconnect

Envelopes carry a monotonic seq (locally generated errors use -1). Track the highest value you’ve processed; after a reconnect, ask the server to replay what you missed instead of re-running the turn:

socket.sendResume({ type: 'resume', resume_after: lastSeq });

The socket reconnects automatically (up to reconnectAttempts), so a typical pattern is to send a resume frame from the open handler when lastSeq > -1.

Close the session

socket.close();

The socket also exposes readyState for connection-state checks.

Full example

import { ApolloMessagingClient } from '@aui.io/aui-client';

const client = new ApolloMessagingClient({ publishableKey: process.env.AUI_PK! });
const { agentId } = await client.getContext();

const socket = await client.connect();
let lastSeq = -1;

socket.on('open', () => {
  if (lastSeq > -1) socket.sendResume({ type: 'resume', resume_after: lastSeq });
});

socket.on('message', (envelope) => {
  if (envelope.seq > 0) lastSeq = envelope.seq;
  if (envelope.type === 'message') {
    console.log('agent:', envelope.data?.text);
    socket.close();
  }
});

await socket.waitForOpen();

socket.sendMessage({
  type: 'message',
  agent_id: agentId!,
  user_id: 'end-user-123',
  text: 'Hello over WebSocket',
});

The wire protocol underneath (URL, query parameters like include_trace and events, close codes) is documented in API → WebSocket, with the machine-readable contract published as an AsyncAPI document.

​Open a session

​Send a message

​Receive envelopes

​Resume after a reconnect

​Close the session

​Full example

Open a session

Send a message

Receive envelopes

Resume after a reconnect

Close the session

Full example