Call events

Call lifecycle events track the creation, answering, and termination of calls. These are the foundational events your application handles.

call.new

Fired when a new inbound call arrives and a channel is created. This is the first event you receive for any call, and is not triggered by any API command.

Payload schema

Field	Type	Description
event	string	Always "call.new". required
session_uuid	string	Unique session identifier (prefixed with node hash). required
caller_id	string	Caller ID number of the incoming call. required
did	string	Called DID (Direct Inward Dialing) number. required

{
  "event": "call.new",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "caller_id": "+15551234567",
  "did": "+15559876543"
}

call.answered

Fired when the call channel is answered. This event may fire twice: once automatically when the channel is answered at the network level, and once when an explicit answer command completes. The command-triggered variant includes command_uid and success.

Payload schema

Field	Type	Description
event	string	Always "call.answered". required
session_uuid	string	Unique session identifier. required
command_uid	string	Present only when triggered by an answer command. Matches the original request. optional
success	boolean	Present only when command-triggered. Whether the answer completed successfully. optional

Example — automatic:

{
  "event": "call.answered",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Example — command-triggered:

{
  "event": "call.answered",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "command_uid": "my-answer-cmd-001",
  "success": true
}

call.hangup

Fired when the call ends. Also fired synthetically when an orphaned session is detected (for example, a bridge timeout after ~120 s of inactivity).

Payload schema

Field	Type	Description
event	string	Always "call.hangup". required
session_uuid	string	Unique session identifier. required
hangup_cause	string	Sanitized cause: completed, busy, rejected, no_answer, unavailable, failed. required
duration_seconds	integer	Call duration in seconds. 0 for synthetic hangups from orphan cleanup. required

{
  "event": "call.hangup",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "hangup_cause": "completed",
  "duration_seconds": 45
}