Working with Twilio Voice, your web application can receive several different types of webhooks.
The first type of webhook is an incoming voice call. When someone dials a phone number associated with your Twilio account, you may choose to process that request within your web application.
The second type of webhook is a status callback, which you will receive after completing an outbound call through Twilio.
The final type of webhook to consider is a recording status callback. Twilio will send one of these callbacks after a call recording is completed and the audio of the recording has been processed into a file.
Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks, or status callbacks. For more, check out our guide to Getting Started with Twilio Webhooks. Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.
Each Twilio phone number has settings for how you'd like Twilio to handle the incoming voice call. Some of these ways include:
You can decide which of these should be used to handle an incoming voice call in the Twilio Console, or you can use the IncomingPhoneNumber resource in the Twilio REST API to programmatically configure your phone number.
If you set up a webhook to handle incoming calls, Twilio will send an HTTP (or HTTPS) request to your web application. That call will either be a POST or a GET request, depending on how you have the phone number configured. POST is typically preferred for most web applications.
Twilio will send information about the incoming phone call to your application. These parameters are documented in Twilio's request to your application. Your application should respond to Twilio by returning Twilio Markup Language for Programmable Voice (TwiML for Voice).
Keeping user information confidential and secure is very important with webhooks - please use HTTPS for your web application, and verify that Twilio sent the webhook to your URL. For more, read our guide on Webhooks Security.
Learn more about how to set up webhooks for incoming voice calls with our step-by-step directions for the following languages:
Whether your Twilio phone number receives a call or your application places an outgoing call, Twilio will send an asynchronous HTTP or HTTPS request to your server after the call ends.
There are two ways to tell Twilio which URL to use. You can:
StatusCallback parameter on a Call resource for an outgoing phone call that uses the REST API.Specify which HTTP method to use (either GET or POST) using the StatusCallbackMethod parameter or statusCallbackMethod attribute.
By default, Twilio will send a callback when the call is completed, but there are additional call status events that your application can listen for. Specify those events (initiated, ringing, answered, completed) in a StatusCallbackEvent parameter on a Call resource or statusCallbackEvent attribute in TwiML.
For more about status callbacks, including how to set a status callback from your code or from TwiML, see the Ending the call: callback requests section of the TwiML voice docs.
StatusCallback and StatusCallbackEvent can only be defined on Programmable Voice calls. For Elastic SIP Trunking calls, any StatusCallback would need to be handled by the SIP Infrastructure that is receiving the SIP signaling.
If you use Twilio to record your voice calls, there is some processing done to the audio file to transcode it into a compressed audio format after the voice call is complete. As this can take time to complete, Twilio will make a recording status callback to your web application after the process is over.
This status can be one of four different statuses - in-progress, completed, absent, or failed. After the voice recording is complete and the file is available, a webhook with the completed status will be sent to your application. The RecordingUrl parameter will contain a link to an audio file that your web application can download.
For more about voice recording with Twilio, see the Call Recording Resource documentation.
For more about recording status callbacks, see this support article for Getting Started with Recording Status Callbacks.