Sessions

A session attaches a configuration to a single live call and runs it in realtime. While the call is connected, the session taps the audio and runs the configured operators — turn by turn as the conversation unfolds, and once over the full transcript when the call ends.

Starting a session

You create a session with the call to analyse and the configuration to apply:

• call_id — the live call to analyse. It must already be known to the platform.
• configuration_id — the uuid of the configuration to apply. It must be one of your account's active configurations.
• customer_metadata — an optional opaque object stored with the session and echoed back, verbatim, on every webhook the session fires. Use it to carry your own correlation keys.
• transcript_events — when true, transcript turns are emitted on the session's event stream alongside operator results.

The response returns a session_id; use it on every other session endpoint.

You don't have to start sessions yourself: assign a configuration to a trunk and the platform starts a session automatically for every call over it. Creating a session explicitly is the per-call alternative, for when you choose the configuration dynamically or attach per-call metadata.

Lifecycle

A session runs for the life of the call and ends automatically when the call ends — you don't tear it down yourself. As it ends, any conversation_end operators run over the full transcript. Within one session a configuration can blend both cadences: turn operators give you live signals during the call, while conversation_end operators produce the post-call analysis.

A session moves through a status over its life — established while running, then ending, ended, failed, or timed_out.

Retrieving results

A live session exposes its results two ways:

• Stream — call GET /sessions/{session_id}/stream-token for a short-lived token, then connect to GET /sessions/{session_id}/events to receive operator results over Server-Sent Events as they are produced. See Session events for the event types and payload shapes.
• Snapshot — call GET /sessions/{session_id}/operator-results for the latest result per operator without holding a stream open.

Results can also be pushed to your systems as webhooks when they meet a condition, without retrieving them yourself.

Changing or ending a session early

PATCH /sessions/{session_id} swaps the configuration in force from that point in the conversation onward, or toggles transcript streaming for the rest of the session — so you can adapt the analysis mid-call. DELETE /sessions/{session_id} ends a session before the call ends, when you want to stop analysing early; in the normal case the session ends on its own when the call does.

API reference — SessionsCreate, update, stream, and end sessions.