Hold a stream open and receive each human reply as it is sent

The customer side of a handoff. The widget subscribes here once the handoff has happened and receives every human reply on the ticket without reloading.

This is Server-Sent Events, not JSON. Hold the connection open and read events as they arrive. Two event names are emitted: handoff once, when the conversation is passed over, then agent_reply for each human reply. Lines beginning with a colon are keep-alives, sent about every 25 seconds, and carry no data.

session_id is the same value the handoff was created with.

Bounded on concurrent streams per session rather than on request rate, because the connection is long-lived, so what has to be capped is how many a session can hold open at once. Reconnecting after a drop is free: the slot is released when the stream closes.

Events are not replayed. A client that was disconnected should re-read the ticket rather than expect to catch up from the stream.

The server never ends this stream. There is no completion event and no final data: line to wait for: handoff is not a terminator, and an agent_reply can arrive minutes later. It ends when the client closes the connection or the connection drops, and closing it is what releases the session's slot, so a client that is finished should close rather than leave it open.

The response is sent with Cache-Control: no-cache, no-transform and X-Accel-Buffering: no. An intermediary that buffers the body anyway will hold the events back and make a working stream look dead.

Tenancy: public and unauthenticated by design. No credential and no role is required or consulted; the workspace is resolved from the request itself (a body tenant_id, a URL token, or an agent id).

Access: no credential.

Path Parameters

Response Body

curl -X GET "https://example.com/v1/widget/sessions/string/stream"

": connected\n\nevent: handoff\ndata: {\"kind\": \"handoff\", \"ticket_id\": \"5e8b0c31-7a4d-4f92-b6c8-1d3e2a5f7b90\", \"assignee_id\": \"3fe98b76-2409-5003-b75a-93e56b450433\", \"message\": \"Connecting you with a human now. They can see the conversation so far.\"}\n\n: ping\n\nevent: agent_reply\ndata: {\"kind\": \"agent_reply\", \"ticket_id\": \"5e8b0c31-7a4d-4f92-b6c8-1d3e2a5f7b90\", \"body\": \"We have refunded the duplicate charge; it should clear in 3 days.\", \"actor_name\": \"Dana Osei\"}\n\n"