- API & Docs
TwiML is a set of instructions you can use to tell Twilio what to do when you receive an incoming call or SMS.
When someone makes a call or sends an SMS to one of your Twilio numbers, Twilio will look up the URL associated with that phone number and make a request to that URL. Twilio will read TwiML instructions at that URL to determine what to do: record the call, play a message for the caller, prompt the caller to press digits on their keypad, etc.
For example, the following will say a short message, and then record the caller's voice:
<?xml version="1.0" encoding="UTF-8"?> <Response> <Say voice="woman">Please leave a message after the tone.</Say> <Record maxLength="20" /> </Response>
TwiML is similar to HTML. Only one TwiML document is rendered to the caller at once, but many documents can be linked together to build complex interactive voice applications.
Calls from a Twilio number to an outside number are controlled using TwiML in the same manner as incoming calls. The initial URL for the call is provided as a parameter to the Twilio REST API request you make to initiate the call.
You can use different combinations of the verbs below to create all kinds of interactive voice and SMS applications.
Say - Read text to the caller
Play - Play an audio file for the caller
Dial - Add another party to the call
Record - Record the caller's voice
Gather - Collect digits the caller types on their keypad
Sms - Send an SMS message during a phone call
Hangup - Hang up the call
Queue - Add the caller to a queue of callers.
Redirect - Redirect call flow to a different TwiML document.
Pause - Wait before executing more instructions
Reject - Decline an incoming call without being billed.
You can configure Twilio to make its initial TwiML requests to your application
via HTTP GET or POST. Subsequent call flow changes such as gathering
input from the keypad using
<Gather> or recording audio using
<Record> require further requests to your application which are
also configurable as GET or POST via each verb's 'method' parameter.
When Twilio performs an HTTP POST to a web server, metadata associated with the call (phone number, etc.) is passed as the body of the POST just as if the parameters were submitted as part of a form on a webpage. One important caveat with POSTs is that Twilio cannot cache POSTs. If you want Twilio to cache static TwiML pages, then have Twilio make requests to your application using GET.
When Twilio performs an HTTP GET to a web server, metadata associated with the call (phone number, etc.) is passed as URL query string parameters as if the parameters were submitted as part of a form on a webpage. Twilio will honor standard HTTP caching directives for HTTP GET requests and locally cache static TwiML documents and media files. Caching is especially important for large media files like MP3s.