Skip to navigation
Compatibility REST APICallsWebhooks

Voice status callback

View as MarkdownOpen in Claude

Payload sent by SignalWire to your Voice Status Callback URL when the status of a call changes.

Configure this callback using the StatusCallback and StatusCallbackEvent parameters when creating a call via the API or using Dial with Number or SIP. A <Conference> noun’s statusCallback receives the Conference status callback instead.

Use StatusCallbackEvent to receive every call progress event — not just the final status — along with current call state and all parameters below.

SignalWire sends the parameters as a form-encoded (application/x-www-form-urlencoded) POST body, not as JSON. When StatusCallbackMethod is GET, they are sent as query parameters instead. Callbacks for the same call can arrive out of order. Timestamp records when each event occurred.

Status callbacks are advisory, best-effort notifications — delivery can be delayed or fail silently, so don’t gate time-critical actions on receiving one. See Status callback reliability.

Payload

The payload of this webhook request is an object.
AccountSidstringRequired
The unique ID of the project this call is associated with.
ApiVersionstringRequired
The version of the SignalWire API. Incoming calls use the API version placed on the number called. Outgoing calls use the version of the REST API request.
CallbackSourcestringRequired
The source of the status callback.
CallSidstringRequired
A unique identifier for the call.
CallStatusenumRequired

The status of the call.

StatusDescription
initiatedThe initial dial has begun.
ringingThe call is ringing.
answeredThe call was answered. Sent only when StatusCallbackEvent includes answered, and followed by an in-progress callback.
in-progressThe call was answered and is in progress.
queuedThe call is ready and in line to initiate.
failedThe call could not be completed. Usually occurs when the phone number does not exist. SignalWire also stops a call created through the REST API before dialing it when its caller ID is on the Do Not Originate registry, a spam rule blocks it, it exceeds the outbound call rate limit (ErrorCode 20429), no endpoint is registered to receive it, or a temporary platform error interrupts it. Retrying usually succeeds after a temporary error.
busyThe caller encountered a busy signal.
no-answerThe call ended without an answer.
completedThe call was answered and ended normally.
canceledThe REST API canceled the call while it was ringing or queued.
DirectionenumRequired

The direction of the call.

  • outbound-dial: calls launched through the Dial verb.
  • outbound-api: calls launched through the REST API.
  • inbound: inbound calls.
Allowed values:
FromstringRequired
The phone number that sent this call, in E.164 format.
TimestampstringRequired
The timestamp, in RFC 2822 format, of when the event occurred.
TostringRequired
The phone number of the call recipient, in E.164 format.
AudioInAveragePtimedoubleOptional
The average time between packets for the inbound stream.
AudioInDtmfPacketCountintegerOptional
The number of DTMF packets in the inbound media stream.
AudioInFlushPacketCountintegerOptional
The number of incoming packets removed from the jitter buffer due to buffer overflow or underflow, causing these packets to be discarded or lost.
AudioInJitterMaxVariancedoubleOptional
The largest variance measured in the time between incoming audio packets, in milliseconds squared.
AudioInJitterMinVariancedoubleOptional
The smallest variance measured in the time between incoming audio packets, in milliseconds squared.
AudioInLargestJbSizeintegerOptional
The largest jitter buffer size recorded for incoming audio RTP packets during the session.
AudioInMosdoubleOptional

The estimated Mean Opinion Score (MOS) for inbound audio quality, based on the share of incoming audio packets that arrived without loss or delay. It ranges from about 1 to 4.5, the score for a call with no lost or late packets. Sent with up to two decimal places, such as 4.37. A whole-number score is sent with one decimal place, such as 4.0.

AudioInMediaPacketCountintegerOptional
The number of audio packets received in the inbound media stream.
AudioInSkipPacketCountintegerOptional
Increased with every packet not received at a given ptime. Increases with every lost packet from the inbound stream.
AudioOutDtmfPacketCountintegerOptional
The total number of DTMF packets generated in the outbound media stream.
AudioOutJitterAvgdoubleOptional
The average jitter, in milliseconds, of the outgoing audio stream.
AudioOutJitterMaxdoubleOptional
The maximum jitter, in milliseconds, of the outgoing audio stream.
AudioOutJitterMindoubleOptional
The minimum jitter, in milliseconds, of the outgoing audio stream.
AudioOutLostintegerOptional
The number of outgoing audio RTP packets reported lost.
AudioOutMediaPacketCountintegerOptional
The number of audio packets sent in the outbound media stream.
AudioRttAvgdoubleOptional

The average audio round-trip time, in milliseconds, measured to the nearest 10 milliseconds.

AudioRttMaxdoubleOptional

The maximum audio round-trip time, in milliseconds, measured to the nearest 10 milliseconds.

AudioRttMindoubleOptional

The minimum audio round-trip time, in milliseconds, measured to the nearest 10 milliseconds.

CallDurationintegerOptional

The duration, in seconds, of the finished call, from when the call started ringing to when it ended, rounded up to the next whole second. Because it includes ringing time, it’s longer than the time the call was connected and usually longer than a recording of the call. Only present on the completed event.

ErrorCodestringOptional

The code for why the call failed, when SignalWire has one. 20429 means the call exceeded the outbound call rate limit. See Error codes.

ErrorMessagestringOptional

The description of ErrorCode.

HangupBystringOptional

The From or To value of the party that ended the call, as indicated by HangupDirection. Present once the call has ended.

HangupDirectionstringOptional

Which side ended the call. Present once the call has ended.

  • inbound: the remote party hung up, so HangupBy is From on an inbound call and To on an outbound call.
  • outbound: the call was ended from the SignalWire side, so HangupBy is To on an inbound call and From on an outbound call.
ParentCallSidstringOptional
A unique identifier for the call that created this call.
SipCallIdstringOptional

The SIP Call-ID of the call.

SipInviteResultPhrasestringOptional
A textual description of the result of the SIP INVITE request, indicating success or failure with additional details.
SipResultCodestringOptional

The numeric SIP response code received for the INVITE request, indicating the outcome of the call attempt. See the list of SIP response codes for possible values.

Response

200
Webhook received