It can be helpful to track the different states of a call to see if a call has been ringing for too long so you can decide whether to redirect it or build advanced analytics to easily see the state of all your in-progress calls.
Once a call is created it progresses through multiple states until it is finally completed. Outbound calls initiated via the API go through the states of being queued, initiated, ringing and in-progress as shown below. The transition between states is marked by a specific event: "initiated", "ringing", "answered" and "completed". Child calls created with <Dial> skip the queued state and go straight to initiated, then ringing and in-progress.
You can use the
StatusCallbackEvent parameter to get notifications when a call reaches the
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.