Voice Platform API

Session

A participant in a voice interaction, from creation through termination.
View as Markdown

A Session is the addressable unit of a voice interaction: one phone call or standalone WebSocket audio endpoint that your application can inspect and control. SIP and WebRTC participants are planned for a future release. A Room connects multiple Sessions into a shared conversation, while playback, DTMF collection, recording, and WebSocket audio operate on an individual Session.

How Sessions are created

Sessions enter your application in several ways:

OriginSession typeWhat your application receives
An incoming phone callphone_inThe platform creates the Session and sends a call.created webhook. Your application can then answer or end it.
POST /sessions:dialphone_outThe API immediately returns a session_uuid; ringing, answer, and termination progress arrives through call webhooks.
POST /sessions:connectWebsocketwebsocketThe API creates a media-only Session with no phone leg. It begins in connecting and becomes answered when the WebSocket connection is established.
A configured SIP or WebRTC connection (Future)sip or webrtcIn a future release, the Session will represent that connected voice participant and use the same Session APIs.

The lifecycle field depends on the endpoint: each item returned by GET /sessions uses state, while GET /sessions/{session_uuid} uses status. Both use the same values: new, connecting, ringing, early_media, answered, or ended. Treat either as a point-in-time snapshot for inspection and reconciliation. Webhooks are the asynchronous event stream for reacting to lifecycle changes as they happen. Every Session finishes with exactly one terminal call.ended webhook, whether it was answered, rejected, timed out, disconnected, or explicitly deleted.

What you can do with a Session

Use the session_uuid to:

  • inspect one Session or list the Sessions owned by your application;
  • answer an incoming call or request termination;
  • play audio and collect DTMF digits;
  • start and control a Session recording;
  • attach a bidirectional WebSocket audio relay; and
  • add the Session to a Room, then control its membership there.

Most control commands are asynchronous. An accepted command returns 202 Accepted with an operation_uuid; the command’s reference identifies the webhook that confirms completion or reports the resulting lifecycle change.

Methods

Session lifecycle, Playback, DTMF, and WebSocket commands operate on a session by placing its session_uuid in the {uuid} path parameter. Recording commands create and control a Recording owned by that Session.

Resource representation

The Session resource
1{
2  "caller_id": "string",
3  "created_at": "2023-01-01T00:00:00Z",
4  "did": "string",
5  "session_uuid": "string",
6  "state": "new",
7  "type": "phone_in"
8}

Properties

created_atdatetimeRequired
session_uuidstringRequired
Opaque session identifier. Return it to the API exactly as received.
stateenumRequired
typeenumRequired
caller_idstringOptional
didstringOptional