Skip to contentSkip to navigationSkip to topbar
On this page

TwiML™ for Programmable Voice



What is TwiML?

what-is-twiml page anchor

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.

How TwiML works

how-twiml-works page anchor

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(link takes you to an external page) document with special tags defined by Twilio to help you build your Programmable Voice application.

(information)

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:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Say>Hello, world!</Say>
4
</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.

<Say> 'Hello' to an inbound callerLink to code sample: <Say> 'Hello' to an inbound caller
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
const response = new VoiceResponse();
4
response.say('Hello!');
5
6
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Say>Hello!</Say>
4
</Response>
(information)

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(link takes you to an external page), 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)

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.

The <Response> element

the-response-element page anchor

In any TwiML response to a Twilio request, you must nest all verb elements within <Response>, the root element of Twilio's XML markup:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Say>
4
This message must be nested in a Response element
5
in order for Twilio to say it to your caller.
6
</Say>
7
</Response>

Any other structure is considered invalid.

TwiML verbs for Programmable Voice

twiml-verbs-for-programmable-voice page anchor

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)

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.


Twilio's request to your application

twilios-request-to-your-application page anchor

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(link takes you to an external page). 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:

Configure webhook on phone number for voice.

Twilio makes its request over HTTP, either as a GET or POST, just like requesting a web page in your browser or submitting a form.

(warning)

Warning

Twilio cannot cache POSTs. If you want Twilio to cache static TwiML pages, then have Twilio make requests to your application using GET.

By including parameters and values in its request, Twilio sends data to your application that you can act upon before responding.

Twilio always sends the following parameters when it sends a request to your application to retrieve instructions for how to handle a call.

These will send as either POST parameters or URL query parameters, depending on which HTTP method you've configured.

ParameterDescription
CallSidA unique identifier for this call, generated by Twilio.
AccountSidYour Twilio account ID. It is 34 characters long, and always starts with the letters AC.
FromThe phone number or client identifier of the party that initiated the call. Phone numbers are formatted with a '+' and country code, e.g., +16175551212 (E.164 format). Client identifiers begin with the client: URI scheme; for example, on a call from a client named 'charlie', the From parameter will be client:charlie. If a caller ID is withheld or otherwise unavailable, you may receive a string that contains anonymous, unknown, or other descriptions.
ToThe phone number or client identifier of the called party. Phone numbers are formatted with a '+' and country code, e.g., +16175551212(E.164 format). Client identifiers begin with the client: URI scheme; for example, for a call to a client named 'joey', the To parameter will be client:joey.
CallStatusA descriptive status for the call. The value is one of the following: queued, ringing, in-progress, completed, busy, failed or no-answer. See the CallStatus section below for more details.
ApiVersionThe version of the Twilio API used to handle this call. For incoming calls, this is determined by the API version set on the called number. For outgoing calls, this is the version used by the REST API request from the outgoing call.
DirectionA string describing the direction of the call: inbound for inbound calls outbound-api for calls initiated via the REST API outbound-dial for calls initiated by a <Dial> verb.
ForwardedFromThis parameter is set only when Twilio receives a forwarded call, but its value depends on the caller's carrier including information when forwarding. Not all carriers support passing this information.
CallerNameThis parameter is set when the IncomingPhoneNumber that received the call has had its VoiceCallerIdLookup value set to true ($0.01 per lookup).
ParentCallSidA unique identifier for the call that created this leg. This parameter is not passed if this is the first leg of a call.
CallTokenA token string needed to invoke a forwarded call.

Twilio also attempts to look up geographic data based on the To and From phone numbers. If available, Twilio will send the following parameters with its request:

ParameterDescription
FromCityThe city of the caller
FromStateThe state or province of the caller
FromZipThe postal code of the caller
FromCountryThe country of the caller
ToCityThe city of the called party
ToStateThe state or province of the called party
ToZipThe postal code of the called party
ToCountryThe country of the called party

Twilio will provide the parameters listed above when it makes a request to your application to retrieve instructions for how to handle a call. This might occur when an inbound call comes to your Twilio number, or after a TwiML verb has completed and you've provided an action URL where Twilio can retrieve the next set of instructions. Depending on what is happening on a call, other variables may also be sent.

For example, when Twilio receives SIP, it will send additional parameters to your web application: you'll find the list of parameters sent with SIP in our guide SIP and TwiML Interaction.

(information)

Info

There are some instances in which Twilio will send a request that doesn't contain all of the above parameters. For example, if you have provided a statusCallback URL in a TwiML noun such as <VirtualAgent> or <Pay>, Twilio's request to your application will not contain all of the parameters listed above, as they might not all be relevant for the particular status callback. In those instances, you can find the expected parameters in the specific TwiML verb's documentation.

The following are the possible values for the CallStatus parameter. These values also apply to the DialCallStatus parameter, which is sent with HTTP requests to a <Dial> action URL.

StatusDescription
queuedThe call is ready and waiting in line before going out.
ringingThe call is currently ringing.
in-progressThe call was answered and is actively in progress.
completedThe call was answered and has ended normally.
busyThe caller received a busy signal.
failedThe call could not be completed as dialed, most likely because the phone number was non-existent.
no-answerThe call ended without being answered.
canceledThe call was canceled via the REST API while queued or ringing.

Ending the call: callback requests

ending-the-call-callback-requests page anchor

After receiving a call, requesting TwiML from your app, processing it, and finally ending the call, Twilio will make an asynchronous HTTP request to the StatusCallback URL configured for the Twilio number that was called.

You need to explicitly provide this URL to your application in the StatusCallback parameter of each message for which you want the status callbacks. The raw TwiML for this looks like:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Number
5
statusCallbackEvent="initiated ringing answered completed"
6
statusCallback="https://myapp.com/calls/events"
7
statusCallbackMethod="POST">
8
+12316851234
9
</Number>
10
</Dial>
11
</Response>

The code sample below shows how to set your status callback URL with plain TwiML or using the helper library of your choice:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.number({
7
statusCallbackEvent: 'initiated ringing answered completed',
8
statusCallback: 'https://myapp.com/calls/events',
9
statusCallbackMethod: 'POST'
10
}, '+12349013030');
11
12
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Number
5
statusCallbackEvent="initiated ringing answered completed"
6
statusCallback="https://myapp.com/calls/events"
7
statusCallbackMethod="POST">
8
+12349013030
9
</Number>
10
</Dial>
11
</Response>

By providing a StatusCallback URL for your Twilio number and capturing this request, you can determine when a call ends and receive information about the call. Please note that non-relative URLs must contain a valid hostname, and underscores are not permitted.

StatusCallback request parameters

statuscallback-request-parameters page anchor

When Twilio sends parameters to your application in an asynchronous request to the StatusCallback URL, they include the same parameters passed in a synchronous TwiML request.

The status callback request also passes these additional parameters:

ParameterDescription
CallDurationThe duration in seconds of the just-completed call.
RecordingUrlThe URL of the phone call's recorded audio. This parameter is included only if Record=true is set on the REST API request, and does not include recordings from <Dial> or <Record>.
RecordingSidThe unique id of the Recording from this call.
RecordingDurationThe duration of the recorded audio (in seconds).

All phone numbers in requests from Twilio are in E.164 format if possible. For example, (231) 685-1234 would come through as '+12316851234'. However, there are occasionally cases where Twilio cannot normalize an incoming caller ID to E.164. In these situations, Twilio will report the raw caller ID string.

All dates and times in requests from Twilio are GMT in RFC 2822(link takes you to an external page) format. For example, 6:13 PM PDT on August 19th, 2010 would be 'Fri, 20 Aug 2010 01:13:42 +0000'.

Twilio is a well-behaved HTTP client

twilio-is-a-well-behaved-http-client page anchor

Twilio behaves just like a web browser when making HTTP requests to URLs:

  • Cookies: Twilio accepts HTTP cookies and will include them in each request, just like a normal web browser.
  • Redirects: Twilio follows HTTP Redirects (HTTP status codes 301, 307, etc.), just like a normal web browser. Twilio supports a maximum of 10 redirects before failing the request with error code 11215.
  • Caching: Twilio will cache files when HTTP headers allow it (via ETag and Last-Modified headers) and when the HTTP method is GET, just like a normal web browser.

Twilio understands MIME types

twilio-understands-mime-types page anchor

Twilio does the right thing when your application responds with different MIME types:

MIME TypeBehavior
text/xml, application/xml, text/htmlTwilio interprets the returned document as an XML Instruction Set (which we like to call TwiML). This is the most commonly used response.
Various audio typesTwilio plays the audio file to the caller, and then hangs up. See the <Play> documentation for supported MIME types.
text/plainIf the response is valid TwiML, we will execute the provided instructions, otherwise Twilio reads the content of the text out loud to the caller, and then hangs up.

In your response to Twilio's request to your configured URL, you can tell Twilio what to do on a call.

How the TwiML interpreter works

how-the-twiml-interpreter-works page anchor

When your application responds to a Twilio request with XML, Twilio runs your document through the TwiML interpreter. The TwiML interpreter only understands the few specially-named XML elements that make up TwiML: <Response> verbs, and nouns.

The interpreter starts at the top of your TwiML document and executes instructions (verbs) in order from top to bottom.

The following code snippet reads "Hello World" to the caller before playing Cowbell.mp3 for the caller and then hanging up.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Say>Hello, World!</Say>
4
<Play>https://api.twilio.com/Cowbell.mp3</Play>
5
</Response>

Just as with all TwiML, you can use the helper libraries to help you play some music to a caller. Include the loop attribute to tell Twilio to loop this recording 10 times (or until the caller hangs up):

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
response.play({
6
loop: 10
7
}, 'https://api.twilio.com/cowbell.mp3');
8
9
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Play loop="10">https://api.twilio.com/cowbell.mp3</Play>
4
</Response>

Status callbacks in your response

status-callbacks-in-your-response page anchor

Status callbacks do not control call flow, so TwiML does not need to be returned. If you do respond, use status code 204 No Content or 200 OK with Content-Type: text/xml and an empty <Response/> in the body. Not responding properly will result in warnings in Debugger.

Go in-depth to learn more about the various TwiML verbs you'll use with Twilio's Programmable Voice, such as <Dial> to connect a call or <Gather> for speech recognition and collecting user key presses. You'll find all in-depth reference documents linked above.

You may also wish to explore how to generate TwiML with Twilio's helper libraries, provided to let you generate TwiML in your favorite language.

For a guided walkthrough, check out our quickstarts that will show you how to make and receive phone calls with Twilio in C#/.NET, Java, Node.js, PHP, Python, or Ruby.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.