Objective
Twilio provides Programmable Voice outbound call status tracking with Status Callbacks. These callbacks can be helpful to see if a call has failed, successfully connected, or been ringing for too long so you can redirect it. They also allow you to build advanced analytics to easily see the state of all your in-progress calls.
Note: Status Callbacks are only available for Programmable Voice calls and cannot be used for Elastic SIP Trunking (ESIPT) calls as ESIPT calls do not leverage webhooks within Twilio. Status Callbacks for ESIPT calls must be handled by your SIP infrastructure and cannot be done within Twilio. ESIPT calls will however show up in your call logs or in responses from the /Call resource of the API after they are in a completed status.
Product
Programmable Voice
Procedure
How do Status Callbacks Work?
Once a call is created, it progresses through multiple states until it is finally completed. Outbound calls initiated via the REST API cycle through these states in order:
-
Queued: Twilio has accepted your API request, and is determining the correct Super Network partner to connect your call.
NOTE: Outbound Child (bridged or forwarded) calls created with the <Dial> TwiML verb skip the queued state and go straight to initiated, then ringing and in-progress. - Initiated: Twilio has forward your call request to one of our Super Network partners.
- Ringing: Twilio has received a signal from our Super Network partner advising the destination phone is ringing.
- In-progress: Twilio has received a signal from our Super Network partner advising the call has been answered.
- Completed: The call has ended.
How to Request Status Callbacks
You can use the StatusCallbackEvent parameter to get notifications when a call reaches the initiated, ringing, answered and completed states. The StatusCallbackEvent is available for calls created via the REST API as well as outbound TwiML calls that use <Dial><Number>, <Dial><Sip> and <Dial><Client>.
For every call progress event specified in the StatusCallbackEvent parameter, Twilio will make an asynchronous webhook to the StatusCallback url parameter provided with information about the call state as well as several helpful request parameters.