Call events

Call lifecycle events track the creation, answering, and termination of voice sessions. These are the foundational events your application will handle. Phone sessions begin with call.created (inbound) or command.call.dial.accepted (outbound); standalone WebSocket sessions have a separate startup sequence described under Call Lifecycle.

call.created

Fired automatically when a new inbound phone, SIP, or WebRTC call arrives and a session is created. Outbound calls begin with command.call.dial.accepted, while standalone WebSocket sessions begin with websocket.connected or websocket.failed.

Payload schema

1
{
2
  "event": "call.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
}

call.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 call.early_media_started and is not an answer.

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

Payload schema

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

call.ended

call.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 call.
• 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": "call.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": "call.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 call. 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.

command.call.dial.accepted

Fired after a successful POST /v1/sessions:dial when the gateway begins dialing the destination. Outbound only.

Payload schema

1
{
2
  "event": "command.call.dial.accepted",
3
  "session_uuid": "acW68-...",
4
  "direction": "outbound",
5
  "type": "phone_out",
6
  "to": "+972527121102",
7
  "from": "+972747713001",
8
  "timestamp": "2025-06-06T08:53:20.123Z"
9
}

call.ringing_started

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

Payload schema

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

call.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. call.answered fires when the called party returns SIP 200 OK.

Payload schema

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

Call Lifecycle

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

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

A standalone type: "websocket" session has no phone leg and emits neither call.created nor command.call.dial.accepted. websocket.connected advances it from connecting to answered without emitting call.answered. Its lifetime is bound to the backend WebSocket: a disconnect or connection failure ends the session, and call.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: a dial may skip straight from command.call.dial.accepted to call.ended (e.g. immediate rejection), or stop at any intermediate stage. call.early_media_started reports SIP 183 early audio; call.answered reports a SIP 200 OK answer.

Timing Limits

Three platform limits surface as ordinary call.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 call.ended with answered: false and hangup_cause: "timeout". This window is measured from when dialing begins (when command.call.dial.accepted is emitted), 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 call.ended with answered: false and duration_seconds: 0.
• Standalone WebSocket connection cap. A standalone type: "websocket" session whose backend never connects within the platform’s connection window is ended and emits call.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 call.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 play a prompt and collect digits (play_and_get_digits) 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 call.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:

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