Session events

Session lifecycle events track the creation, answering, and termination of voice sessions. These are the foundational events your application will handle. Inbound phone sessions begin with session.created; outbound admission is acknowledged by the dial request’s 202 Accepted response. Standalone WebSocket sessions have a separate startup sequence described under Session lifecycle.

session.created

Fired automatically when a new inbound phone, SIP, or WebRTC call arrives and a session is created. Outbound calls are admitted by the dial request’s 202 Accepted response, while standalone WebSocket sessions begin with websocket.connected or websocket.failed.

Payload schema

1
{
2
  "event": "session.created",
3
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
4
  "caller_id": "+972527121102",
5
  "did": "+972747713001",
6
  "type": "phone_in",
7
  "timestamp": "2025-06-06T08:53:20.000Z"
8
}

session.answered

Fired exactly once when the call is answered. In terms of SIP response codes, this event corresponds strictly to a 200 OK from the called party — 183 Session Progress is reported separately as session.early_media_started and is not an answer.

When you issue an explicit answer command, a SIP 200 OK emits one session.answered event. An unanswered call emits session.ended with answered: false. The session.answered payload omits operation_uuid and success.

Payload schema

1
{
2
  "event": "session.answered",
3
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
4
  "timestamp": "2025-06-06T08:53:22.000Z"
5
}

session.ended

session.ended is the single terminal event for every session. It fires exactly once per session — whether or not the call was ever answered. Use the answered boolean to distinguish the two cases:

• Post-answer termination: answered: true, a real duration_seconds, and hangup_by identifying the party who ended the session.
• Pre-answer termination (dial never connected, rejected, or cancelled before answer): answered: false, duration_seconds: 0, and hangup_by identifying the responsible party where it can be attributed (e.g. "system" for a ring/dial timeout) or "unknown" when the originator is indeterminate.

It is also fired synthetically when a session becomes orphaned — i.e. it has had no media or signalling activity for approximately 120 seconds and is cleaned up by the platform (see Timing Limits). Synthetic hangups carry answered: false and duration_seconds: 0.

Payload schema

Example — answered:

1
{
2
  "event": "session.ended",
3
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
4
  "answered": true,
5
  "hangup_cause": "completed",
6
  "hangup_by": "caller",
7
  "hangup_description": "The caller hung up.",
8
  "duration_seconds": 45,
9
  "timestamp": "2025-06-06T08:54:07.000Z"
10
}

Example — pre-answer termination:

1
{
2
  "event": "session.ended",
3
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
4
  "answered": false,
5
  "hangup_cause": "cancelled",
6
  "hangup_by": "unknown",
7
  "hangup_description": "The caller cancelled before the call was answered.",
8
  "duration_seconds": 0,
9
  "timestamp": "2025-06-06T08:53:52.000Z"
10
}

Hangup Causes

Treat any unrecognized hangup_cause value as failed — the bucket vocabulary may gain values in future.

Hangup By

hangup_by identifies which party ended the session. It is orthogonal to hangup_cause (the reason): a single cause may originate from either side.

Hangup Description

Human-readable English summary of why the call ended. Presentation only — the wording may change without notice, so branch on hangup_cause / hangup_by, never on this string.

session.ringing_started

Fired when the far end indicates ringing on an outbound dial.

Payload schema

1
{
2
  "event": "session.ringing_started",
3
  "session_uuid": "acW68-...",
4
  "timestamp": "2025-06-06T08:53:21.123Z"
5
}

session.early_media_started

Fired when the far end starts sending early media (audio before answer, e.g. ringback or carrier announcements). This corresponds to SIP 183 Session Progress.

Early media indicates that audio is flowing before the called party answers. session.answered fires when the called party returns SIP 200 OK.

Payload schema

1
{
2
  "event": "session.early_media_started",
3
  "session_uuid": "acW68-...",
4
  "timestamp": "2025-06-06T08:53:22.123Z"
5
}

Session lifecycle

Every session moves through a sequence of lifecycle events and ends with exactly one terminal session.ended, including unanswered calls (answered: false). The optional states (?) may or may not fire depending on far-end signalling.

Outbound (POST /v1/sessions:dial):
  202 Accepted
      └─▶ session.ringing_started?
              └─▶ session.early_media_started?          (SIP 183 — NOT an answer)
                      ├─▶ session.answered ─▶ … ─▶ session.ended { answered: true }
                      └────────────────────▶ session.ended { answered: false }
                                              (timeout / busy / rejected / cancelled,
                                               duration_seconds: 0; hangup_by is "system"
                                               for a ring/dial timeout, else "unknown")
Inbound (incoming call):
  session.created
      └─▶ session.answered ─▶ … ─▶ session.ended { answered: true }
      └──────────────────────▶ session.ended { answered: false }   (caller gives up before answer)
Standalone WebSocket session (POST /v1/sessions:connectWebsocket):
  websocket.connected ─▶ … ─▶ websocket.disconnected ─▶ session.ended
       or
  websocket.failed ──────────────────▶ session.ended
       or
  connection timeout ─────────▶ session.ended

A standalone type: "websocket" session has no phone leg and does not emit session.created. websocket.connected advances it from connecting to answered without emitting session.answered. Its lifetime is bound to the WebSocket server connection: a disconnect or connection failure ends the session, and session.ended follows the corresponding WebSocket event. See Create Session for the full contract.

Outbound Call Origination Lifecycle

A POST /v1/sessions:dial produces the following outbound lifecycle events. Every event below carries a timestamp (RFC 3339 UTC string). For this session, preserve the delivery order guaranteed above.

Each intermediate event is emitted at most once and only advances forward: after the 202 response, a dial may skip straight to session.ended (e.g. immediate rejection), or stop at any intermediate stage. session.early_media_started reports SIP 183 early audio; session.answered reports a SIP 200 OK answer.

Timing Limits

Three platform limits surface as ordinary session.ended events:

• Outbound dial cap (ring_timeout_sec). Every outbound dial supplies this value explicitly. If an outbound dial is not answered within that window, the platform stops the attempt and emits session.ended with answered: false and hangup_cause: "timeout". This window is measured from when dialing begins (when the dial request returns 202 Accepted), not from when the far end starts ringing — see Ring timeout timing.
• Bridge limit (~120 seconds of inactivity). A session that becomes orphaned (no media or signalling activity) for approximately 120 seconds is cleaned up and emits a synthetic session.ended with answered: false and duration_seconds: 0.
• Standalone WebSocket connection cap. A standalone type: "websocket" session whose WebSocket server never connects within the platform’s connection window is ended and emits session.ended.

These windows are platform behaviour and may change; treat the exact values as approximate and branch on hangup_cause, not on elapsed time you measure yourself.

Answering Machine Detection (AMD)

Lifecycle and interaction signals alone make voicemail detection necessarily heuristic. Common signals an application can combine:

• Long uninterrupted single-party audio after answer. Voicemail greetings are continuous monologues. If, after session.answered, the far end produces a long stretch of audio with no DTMF (no dtmf.received) and no natural pause where a person would respond to your prompt, treat it as a likely machine.
• No interactive response to a prompt. If you use DTMF collection and consistently get digits.collected with status: "no_input" or "partial_then_timeout", the answering party may be a machine that cannot respond.
• Early media that never becomes an answer. A session.early_media_started followed by a long delay and then a hangup with answered: false typically reflects ringback or a carrier announcement, not a person — this is the unanswered case, distinct from a machine that actually answers.

For reliable detection, analyze the call audio with a dedicated answering-machine-detection algorithm. You can supply it with real-time audio through a WebSocket audio relay, or stream an active recording from its live_url. Combine that analysis with lifecycle events and interaction signals as appropriate for your traffic. If the result indicates a recording, delete the session, passing the event’s session_uuid as {uuid}.

Triggered By

These events are produced by the following endpoints and lifecycle triggers:

• session.created — automatic: fires on incoming calls (no API trigger).
• session.answered — automatic or answer command.
• session.ended — automatic (single terminal event, answered or not) or session deletion.
• session.ringing_started — automatic on outbound ring indication.
• session.early_media_started — automatic on SIP 183 progress (NOT an answer).