Skip to main content

Attach Live Sideband

GET 

wss://api.knox.chat/v1/live/sessions/:session_id/attach

Open a sideband WebSocket on an existing Live session. Audio continues on the primary WebSocket or WebRTC/SIP media path. Use the sideband from your server to:

  • Watch transcripts, session.delegation.created, and nested response.events
  • Send session.thinking.append / session.commentary.append / session.update
  • Send session.close to hang up and collect final usage

Closing the sideband does not end the primary session. Knox also uses a sideband internally to bill WebRTC and SIP duration.

You must own the session (or present a valid Knox key for an incoming SIP id that is not yet in Knox’s table). See the GPT-Live guide and OpenAI server-side controls.

Request​

Path Parameters​

NameTypeRequiredDescription
session_idStringYesLive session id from session.started or the create response.

Request Headers​

NameTypeRequiredDescription
AuthorizationStringYesBearer sk-… or Bearer ek_knox_….
UpgradeStringYesMust be websocket.

A non-WebSocket GET returns 400: connect to /v1/live/sessions/{id}/attach over WebSocket.

Connection example​

import WebSocket from "ws";

const sessionId = "sess_…";
const ws = new WebSocket(
`wss://api.knox.chat/v1/live/sessions/${sessionId}/attach`,
{ headers: { Authorization: "Bearer " + process.env.KNOX_API_KEY } }
);

ws.on("message", (data) => {
const event = JSON.parse(data.toString());
console.log(event.type);
});

// End the call from the server:
// ws.send(JSON.stringify({ type: "session.close" }));

session.update on the sideband is validated the same way as on the primary connection (delegation.responses.model must be allowed).

Error Responses​

StatusWhen
400Not a WebSocket upgrade, or invalid session id.
401Missing or invalid Knox API key.
403Token is not authorized for gpt-live-1.
404Session not found, or it belongs to another user.
502Upstream attach failed.