TwiML?: the Twilio Markup Language

Overview

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.

The TwiML Verbs

You can use different combinations of the verbs below to create all kinds of interactive voice and messaging 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.
• Message - Send an MMS or SMS message reply

How Twilio Interacts with Your Application

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.

POST

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.

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.