Skip to main content
GET
/
v1
/
widget
/
sessions
/
{sessionId}
/
stream
Widget SSE stream
curl --request GET \
  --url https://api.example.com/v1/widget/sessions/{sessionId}/stream \
  --header 'Authorization: <authorization>'

​
Overview

Roadmap — not yet available. The embeddable widget is a future feature.
Opens a Server-Sent Events connection for a widget session. The stream delivers AI response tokens in real time as the assistant generates them, plus system events (typing indicator, session expiry warnings). Authentication: Widget session token (Authorization: Bearer <sessionToken> or X-Widget-Token header).
The stream uses Content-Type: text/event-stream. The connection stays open for the lifetime of the session. Reconnect with the same session token if disconnected.

​
Request headers

​
Authorization
string
required
Widget session token. Format: Bearer <sessionToken>. Obtain from Create widget session.

​
Path parameters

​
sessionId
string
required
The widget session identifier.

​
Event types

Event typeDescription
message.startAssistant has started generating a response
message.deltaIncremental token chunk from the assistant response
message.completeFull response assembled — includes final text
message.errorAssistant error (retry or report to support)
session.expiry_warningSession expires in 15 minutes
pingKeepalive heartbeat every 30 seconds

​
Event format

SSE lines follow the standard event: / data: format: 
id: wevt_01HX9VTPQR3KF8MZWBYD5N6JCE
event: message.start
data: {"messageId":"wmsg_01HX9VTPQR3KF8MZWBYD5N6JCE","sessionId":"wsess_01HX9VTPQR3KF8MZWBYD5N6JCE"}

id: wevt_01HX9VTPQR3KF8MZWBYD5N6JCF
event: message.delta
data: {"messageId":"wmsg_01HX9VTPQR3KF8MZWBYD5N6JCE","delta":"The root cause is a connection pool exhaustion"}

id: wevt_01HX9VTPQR3KF8MZWBYD5N6JCG
event: message.delta
data: {"messageId":"wmsg_01HX9VTPQR3KF8MZWBYD5N6JCE","delta":" triggered by the 14:25 deploy."}

id: wevt_01HX9VTPQR3KF8MZWBYD5N6JCH
event: message.complete
data: {"messageId":"wmsg_01HX9VTPQR3KF8MZWBYD5N6JCE","fullText":"The root cause is a connection pool exhaustion triggered by the 14:25 deploy.","sources":[]}

​
Reconnection

If the SSE connection drops, reconnect with the same session token and include the Last-Event-ID header with the last received event ID. The server resumes from the next event. 
GET /v1/widget/sessions/{sessionId}/stream
Last-Event-ID: wevt_01HX9VTPQR3KF8MZWBYD5N6JCH

​
Examples

const eventSource = new EventSource(
  `https://api.causeflow.ai/v1/widget/sessions/${sessionId}/stream`,
  { withCredentials: false }
);

// For custom headers, use a polyfill:
// const es = new EventSourcePolyfill(url, { headers: { Authorization: `Bearer ${sessionToken}` }});

let fullResponse = "";

eventSource.addEventListener("message.delta", (e) => {
  const { delta } = JSON.parse(e.data);
  fullResponse += delta;
  document.getElementById("response").textContent = fullResponse;
});

eventSource.addEventListener("message.complete", (e) => {
  const { fullText, sources } = JSON.parse(e.data);
  console.log("Complete:", fullText);
  eventSource.close();
});

eventSource.addEventListener("message.error", () => {
  console.error("Widget stream error");
  eventSource.close();
});

Send message

Send a user message to trigger a response

Push subscribe

Register for push notifications on widget events