WebSocket - BeforeQuery

The WebSocket transport streams chat over a persistent connection. It’s the SDK’s default (transport: "auto"), with automatic SSE fallback.

Connect

wss://api.agents.beforequery.com/api/v1/public/projects/:projectId/ws?client_key=bq_pk_...

Or with server credentials:

wss://.../ws?client_id=bq_ci_...&client_secret=bq_cs_...

Client → server

Send a chat frame:

{
  "type": "chat",
  "query": "How does OAuth work?",
  "thread_id": "thr_uuid",          // optional — continue a conversation
  "captcha_token": "...",           // required if the key enforces CAPTCHA
  "group_ids": ["grp_uuid"],        // optional — source-group scoping
  "user": { "email": "u@x.com" }    // optional
}

Server → client

Token frames stream, then a terminal frame:

{ "type": "token", "content": "OAuth in " }
{ "type": "token", "content": "this product ..." }
{ "type": "done", "thread_id": "thr_uuid", "message_id": "msg_uuid", "citations": [ ... ] }

Errors:

{ "type": "error", "code": "captcha_required", "message": "..." }

Code	Meaning
`captcha_required`	Key enforces reCAPTCHA and no token was sent
`captcha_failed`	Token verification failed
`bad_request`	Malformed frame or invalid parameters
`internal`	Server error — retry or fall back to SSE

Connection behavior

One connection serves sequential chats — send the next chat frame after done.
The server sends pings every 30 seconds to keep the connection alive.
group_ids follows the same rules as HTTP: intersected with the key’s allowed_groups, narrowing only.

Minimal browser example

const ws = new WebSocket(
  "wss://api.agents.beforequery.com/api/v1/public/projects/proj_xxx/ws?client_key=bq_pk_..."
);

ws.onopen = () => ws.send(JSON.stringify({ type: "chat", query: "How does OAuth work?" }));

ws.onmessage = (e) => {
  const frame = JSON.parse(e.data);
  if (frame.type === "token") appendToUI(frame.content);
  if (frame.type === "done") showCitations(frame.citations);
  if (frame.type === "error") console.error(frame.code, frame.message);
};

Use @beforequery/sdk instead of raw WebSocket where possible — it handles connection reuse, the 5-second connect timeout, and automatic SSE fallback for you.

​Connect

​Client → server

​Server → client

​Connection behavior

​Minimal browser example

Connect

Client → server

Server → client

Connection behavior

Minimal browser example