WebSocket (runtime v1)

For runtime v1 agents, the messaging client can open 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.

Runtime v1 agents only. WebSocket sessions belong to runtime v1. Runtime v2 agents stream over HTTP instead — one streamMessage call per turn gives you the same token-by-token reply, resumable with Last-Event-ID, with no socket to keep alive; a runtime v2 agent answers connect() with an error envelope explaining the session is SSE-only. Runtime v1 agents maps each socket frame to its streamMessage equivalent. (Tip: UUID thread ids mean runtime v2.)

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
  // context: { welcome_message: '...' },   // seed the opening message
  // 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`, whose `trace_info` (an `Apollo.Trace`, `runtime: "v1"`) is present when the session was opened with `include_trace` — the default
`error`	Session error (`{ error, code }`) or turn error (`{ message, status_code, error_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