TwiML™ for Programmable Voice
TwiML (the Twilio Markup Language) 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 to one of your Twilio numbers, Twilio looks up the URL associated with that phone number and sends it a request. Twilio then reads the TwiML instructions hosted at that URL to determine what to do, whether it's recording the call, playing a message for the caller, or prompting the caller to press digits on their keypad.
At its core, TwiML is an XML document with special tags defined by Twilio to help you build your Programmable Voice application.
Info
Not making phone calls? TwiML powers more than just Twilio Programmable Voice. For instance, check out the documentation on how to use TwiML with Programmable SMS.
The following will say "Hello, world!" when someone dials a Twilio number configured with this TwiML:
_10<?xml version="1.0" encoding="UTF-8"?>_10<Response>_10 <Say>Hello, world!</Say>_10</Response>
You can always return raw TwiML from your language of choice, or leverage the Twilio helper libraries to automatically create valid TwiML for you. In the code sample below, toggle to your preferred web programming language to see how the above TwiML looks using the helper library.
Info
Check out our short tutorial on responding to incoming phone calls, available in our six supported helper library languages. You can also leverage Twilio's TwiML bins, our serverless solution that lets you write TwiML that Twilio will host for you so you can quickly prototype a solution without spinning up a web server.
Outbound calls (calls from a Twilio number to an outside number) are controlled using TwiML in the same manner. When you initiate an outbound call with the Twilio API, Twilio then requests your TwiML to learn how to handle the call.
Twilio executes just one TwiML document to the caller at a time, but many TwiML documents can be linked together to build complex interactive voice applications.
In TwiML parlance, XML elements are divided into three groups: the root <Response> element, verbs, and nouns.
Warning
TwiML elements (verbs and nouns) have case-sensitive names. For example, using <say> instead of <Say> will result in an error. Attribute names are also case sensitive and camelCased.
You can use XML comments freely in your TwiML; the interpreter ignores them.
In any TwiML response to a Twilio request, you must nest all verb elements within <Response>, the root element of Twilio's XML markup:
_10<?xml version="1.0" encoding="UTF-8"?>_10<Response>_10 <Say>_10 This message must be nested in a Response element_10 in order for Twilio to say it to your caller._10 </Say>_10</Response>
Any other structure is considered invalid.
TwiML verbs tell Twilio what actions to take on a given call. Because of this, most elements in a TwiML document are TwiML verbs. Verb names are case sensitive, as are their attribute names.
You can use different combinations of TwiML verbs to create all kinds of interactive voice applications. The core TwiML verbs for Programmable Voice are:
-
<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
The following verbs may be used to control the flow of your call:
-
<Hangup>— Hang up the call. -
<Enqueue>— Add the caller to a queue of callers. -
<Leave>— Remove a caller from a queue of callers. -
<Pause>— Wait before executing more instructions. -
<Redirect>— Redirect call flow to a different TwiML document. -
<Refer>— Twilio initiates SIP REFER towards IP communication infrastructure. -
<Reject>— Decline an incoming call without being billed.
The following nouns provide advanced capabilities:
-
<VirtualAgent>— Build AI-powered Conversational IVR.
Warning
There are certain situations when the TwiML interpreter may not reach verbs in a TwiML document because control flow has passed to a different document. This usually happens when a verb's action attribute is set.
For example, if a <Say> verb is followed by a <Redirect> and then another <Say>, the second <Say> is unreachable because <Redirect> transfers full control of a call to the TwiML at a different URL.
A TwiML noun describes the phone numbers and API resources you want to take action on. Effectively, a TwiML noun is anything nested inside a verb that is not itself a verb: it's whatever the verb is acting on.
TwiML nouns are usually just text. However, as in the case of <Dial> with its <Number> and <Conference> nouns, at times there are nested XML elements that are nouns.
When someone makes an inbound call to one of your Twilio phone numbers, Twilio needs to request TwiML from your application to get instructions for handling the call.
You can configure your Twilio phone number to point to your application's URL by visiting the phone numbers section of the Console. Select your phone number, then scroll to the Voice & Fax section to set a webhook, TwiML bin, or Twilio Function for Twilio to send that HTTP request when a call comes in: