Attach Live Sideband
GETwss://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 nestedresponse.events - Send
session.thinking.append/session.commentary.append/session.update - Send
session.closeto 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
| Name | Type | Required | Description |
|---|---|---|---|
| session_id | String | Yes | Live session id from session.started or the create response. |
Request Headers
| Name | Type | Required | Description |
|---|---|---|---|
| Authorization | String | Yes | Bearer sk-… or Bearer ek_knox_…. |
| Upgrade | String | Yes | Must 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
| Status | When |
|---|---|
400 | Not a WebSocket upgrade, or invalid session id. |
401 | Missing or invalid Knox API key. |
403 | Token is not authorized for gpt-live-1. |
404 | Session not found, or it belongs to another user. |
502 | Upstream attach failed. |