TwiML is the XML-based markup used by Twilio to define a set of instructions that take place when a call is placed. You do not need to indicate that text stream is XML, Dispatch will do that for you when rendering the message.

See the Official TwiML reference for details on all the specifics of TwiML. This guide will only cover the basics.

Additional note: SMS messages sent via Twilio should not be marked up in TwiML. They should be plain text with no markup of any kind.

TwiML verbs

When Dispatch requests that Twilio place a voce call, Twilio makes a HTTP request into Dispatch to return the TwiML that instructs Twilio on what to do. TwiML verbs are used to instruct Twilio to do certain things like speak text, record a response, wait for a keypress, hangup, etc. All TwiML actions need to be wrapped in a Response verb for Twilio to process the actions contained inside.

Saying text

To speak text you need to use the Say verb. The example below would speak in a women's voice the phrase "The quick brown fox jumps over the lazy dog". Many voices and languages are supported by Twilio.

More information about the Say verb.

<Response>
    <Say voice="woman">The quick brown fox jumps over the lazy dog.</Say>
</Response>

Recording the recipient

To record the caller you need to use the verb Record. This example would initially speak the first phrase "Welcome to Joke Line. Speak your name after the beep and then press any key to continue." and then record audio for up to 20 seconds. If no response was heard by Twilio, it would speak the phrase "You didn't say anything. Goodbye". If the person on the call did speak, Twilio would either wait until the 20 seconds maximum length was reached or the caller pressed any key on their handset to continue. The action parameter gives Twilio to location of the next TwiML template to respond to. In this example we have pointed Twilio at another TwiML template.

More information about the Record verb.

<Response>
    <Say voice="woman">Welcome to Joke Line. Speak your name after the beep and then press any key to continue.</Say>
    <Record maxLength="20"
            action="https://apps.its.uiowa.edu/dispatch/messages/template/123456789/${id}" />
    <Say voice="woman">You didn't say anything. Goodbye.</Say>
</Response>

Gathering input

You can prompt the caller to press a key on their phone's keypad using the verb Gather. This part of the example would say something in the default male voice then waiting five seconds for the caller to press a key on their handset to choose an option. The key they press will be passed to the template references in the Gather action and be available as an attribute of the recipient.

More information about the Gather verb.

<Response>
    <Say>${joke}</Say>
    <Gather action="https://apps.its.uiowa.edu/dispatch/messages/template/987654321/${id}" timeout="5" numDigits="1">
        <Say voice="woman">For jokes about the Cyclones, press 1. For jokes about the Panthers, press 2.</Say>
    </Gather>
</Response>

Pause reading of text

You can pause the execution of your TwiML by using the verb Pause. This part of the example would start by saying something in the default male voice, pausing one second, then finishing the call by speaking more text.

More information about the Pause verb.

<Response>
    <Say>Prepare to laugh.</Say>
    <Pause length="1">
    <Say>${joke}</Say>
</Response>

Responding to digit presses

You can have logic based on which keys are pressed by using the verb Digits. This example shows what would happen if the user had chosen an option by responding to the prompt in the above example.

Let's assume the user press the "1" key on their phone to hear jokes about the Cyclones. Twilio will send the digits pressed as parameters to the next response. Dispatch passes those digits into the template as the attribute Digits. The example below is a mix of FreeMarker syntax and TwiML.

<Response>
    <#if Digits == "1">
        <Say>Why do Iowa State students have such beautiful noses?</Say>
        <Pause length="1"/>
        <Say>They're hand picked.</Say>
    <#elseif Digits == "2">
        <Say>What does it say on the back of every Northern Iowa diploma?</Say>
        <Pause length="1"/>
        <Say>Will work for food.</Say>
    <#else>
        <Say>I'm sorry. I did not get what kind of joke you wanted.</Say>
        <Gather action="https://apps.its.uiowa.edu/dispatch/messages/template/987654321/${id}" timeout="5" numDigits="1">
            <Say voice="woman">For jokes about the Cyclones, press 1. For jokes about the Panthers, press 2.</Say>
        </Gather>
    </#if>
</Response>

Forwarding a call

You can have Twilio forward a call to a different number using the verb Dial. This example makes use of the Dial verb to forward a call to another number after the user has pressed a key on their device. The example below is a mix of FreeMarker syntax and TwiML.

More information about the Dial verb.

<Response>
    <#if Digits == "1">
        <Dial timeout="10">319-555-5555</Dial>
    <#elseif Digits == "2">
        <Dial timeout="10">319-555-6666</Dial>
    <#else>
        <Say>I'm sorry. I did not get that.</Say>
        <Gather action="https://apps.its.uiowa.edu/dispatch/messages/template/555444333/${id}" timeout="5" numDigits="1">
            <Say voice="woman">For customer service, press 1. For sales, press 2.</Say>
        </Gather>
    </#if>
</Response>
Related topics: