Question
What are the possible call statuses, and what do they mean?
Product
Programmable Voice
Answer
Every Twilio call has a status value which describes the current state of the call. The call status may change over the course of the call, and it's value is submitted to your server in realtime with each TwiML request Twilio makes to your server.
Outbound Call Status Progression
When placing outbound calls with the REST API this is a typical sequence of status values:
queued |
Twilio has received your request to create the call. All new calls are created with a status of queued. |
initiated |
Twilio has dialed the call. |
ringing |
The destination number has started ringing. |
in-progress |
The call has been connected, and the connection is currently active. |
completed |
The connected call has now been disconnected. Completed calls will remain in this state in going forward. |
Notice: A completed
call indicates that a connection was established, and audio data was transferred. This could be seen when a phone is answered by a person, an IVR phone tree menu, or even a voicemail. Completed calls, regardless of the outcome, are charged against your project balance.
Final Call Statuses
After a call has finished, the following final status options are possible:
busy |
Twilio dialed the number, but received a busy response. |
no-answer |
Twilio dialed the number but no one answered before the timeout parameter value elapsed. This can be configured for each call, but by default is set to 60 seconds on outbound API calls, and 30 seconds on outbound <Dial> calls. |
canceled |
Prior to being answered, an outbound call was canceled via an HTTP POST request to the REST API. Also, for parent/child call flows that use the <Dial> verb's hangupOnStar attribute, if the caller presses the '*' key on the parent call before the child call is answered, then the child call will result in the canceled final call state state. |
failed |
Twilio's carriers could not connect the call. Possible causes include the destination is unreachable, or the number may have been input incorrectly. |
Notice: A call status of busy
, no-answer
, canceled
, or failed
will not be charged against your project balance. However, a completed
parent or child call related to a call with these statuses would still be charged.
Question
How can I track the status of my outbound calls?
Product
Programmable Voice
Answer
If you want to track the status of your outbound calls, you can use the StatusCallbackEvent
parameter to get notifications back to your application every time a call moves to a different status. For more information, please see our article Tracking the Status of an Outbound Call.