WebSocket (runtime v1)

For runtime v1 agents, the WebSocket session is a bidirectional transport for chat UIs: send message frames, receive the reply as a live token stream, and recover any missed events after a reconnect. It shares the conversation model and threads of the REST and SSE transports.

Runtime v1 agents only. WebSocket sessions belong to runtime v1. Runtime v2 agents stream over HTTP instead — the SSE stream endpoint gives you the same token-by-token reply per turn, resumable with Last-Event-ID, with no socket to keep alive; a runtime v2 agent answers a session with an error envelope explaining it is SSE-only. Runtime v1 agents maps each socket frame to its SSE equivalent.

Connect

wss://api-v3.aui.io/apollo-api/messaging/v1/session

Authenticate on the upgrade request with your Bearer token:

Authorization: Bearer <access_token>

Invalid or expired credentials close the connection with code 1008 (policy violation). Internal errors close with 1011.

Query parameters

boolean

default:"true"

When true, the final message envelope carries data.trace_info — the reasoning trace, the same object the trace endpoints return (sessions are runtime v1, so it is the typed runtime v1 trace, runtime: "v1").

string

Omit for the minimal stream (token deltas + completion). all or verbose opts into the full workflow/lifecycle event set.

integer

With task_id, replays buffered envelopes with seq greater than this value on connect — gap recovery after a reconnect.

string

Thread id to replay from on connect (pairs with resume_after).

Frames you send

`message` — submit a turn

{
  "type": "message",
  "agent_id": "6a344d186d3160971ec62eb6",
  "thread_id": null,
  "user_id": "my-user-123",
  "text": "I am looking for a built-in microwave",
  "context": { "url": "https://example.com/products" },
  "agent_variables": {}
}

string

required

Must be "message".

string

required

The target agent — use the agent_id returned by the token exchange.

string

Omit to auto-create a thread; its id is announced back as the first envelope. Pass it to continue an existing thread.

string

End-user reference for an auto-created thread.

string

required

The message content.

`resume` — replay after a reconnect

{ "type": "resume", "resume_after": 41 }

Replays buffered envelopes with seq > resume_after for the active thread.

Envelopes you receive

Every server frame is a sequenced envelope:

{ "seq": 42, "type": "event", "data": { ... } }

`type`	Meaning	`data`
`thread`	The resolved thread id, once per thread per connection	`{ "thread_id": "..." }`
`event`	A streaming event while the agent works	Token deltas carry `data.text` under event name `thread-message-text-content-updated`
`message`	Turn complete — the full agent reply	The same `message` object as REST, plus `trace_info` when `include_trace=true`
`error`	A recoverable error; the socket stays open	`{ "error": "...", "code": 402 }` for session errors, or the turn error’s message and status

Track the highest seq you’ve processed — that’s your resume cursor. Locally-generated errors use seq: -1 and are not resumable.

Code example

Node.js

const WebSocket = require("ws");

let lastSeq = -1;

const ws = new WebSocket(
  "wss://api-v3.aui.io/apollo-api/messaging/v1/session",
  { headers: { Authorization: `Bearer ${accessToken}` } }
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "message",
    agent_id: agentId,        // from the token exchange
    user_id: "my-user-123",
    text: "I am looking for a built-in microwave",
  }));
});

ws.on("message", (raw) => {
  const envelope = JSON.parse(raw);
  if (envelope.seq > 0) lastSeq = envelope.seq;

  switch (envelope.type) {
    case "thread":
      console.log("thread:", envelope.data.thread_id);
      break;
    case "event":
      if (envelope.data?.data?.text) {
        process.stdout.write(envelope.data.data.text); // token delta
      }
      break;
    case "message":
      console.log("\ncomplete:", envelope.data.text);
      break;
    case "error":
      console.error("error:", envelope.data);
      break;
  }
});

ws.on("close", (code) => {
  if (code !== 1000) {
    // reconnect, then recover the gap:
    // ?task_id=<thread_id>&resume_after=<lastSeq>
  }
});

Best practices

Reconnect with resume — on an abnormal close, reconnect with task_id + resume_after (or send a resume frame) instead of restarting the turn; you get exactly the envelopes you missed.
Track seq continuously — a gap in seq means you missed frames; resume from your last processed value.
Exponential backoff — back off between reconnection attempts.
Keep the thread id — persist thread_id across reconnects to stay in the same conversation.

The full machine-readable contract is published as an AsyncAPI document at /asyncapi.yaml.

Get started

Messaging

Management

Runtime v1

WebSocket (runtime v1)

Connect

Query parameters

Frames you send

`message` — submit a turn

`resume` — replay after a reconnect

Envelopes you receive

Code example

Best practices

​Connect

​Query parameters

​Frames you send

​message — submit a turn

​resume — replay after a reconnect

​Envelopes you receive

​Code example

​Best practices

Connect

Query parameters

Frames you send

`message` — submit a turn

`resume` — replay after a reconnect

Envelopes you receive

Code example

Best practices