TwiML, or the Twilio Markup Language, is an XML based language which instructs Twilio on how to handle various events such as incoming and outgoing calls, SMS messages and MMS messages. When building a Twilio application you will use TwiML when communicating your desired actions to Twilio.
TwiML is the Twilio Markup Language, which is just to say that it's an XML document with special tags defined by Twilio to help you build your SMS and voice applications. TwiML is easier shown than explained. Here's some TwiML you might use to respond to an incoming phone call:
<?xml version="1.0" encoding="UTF-8"?> <Response> <Say>Thanks for calling!</Say> </Response>
And here's some TwiML you might use to respond to an incoming SMS message:
<?xml version="1.0" encoding="UTF-8"?> <Response> <Message>We got your message, thank you!</Message> </Response>
Every TwiML document will have the root <Response> element and within that can contain one or more verbs. Verbs are actions you'd like Twilio to take, such as <Say> a greeting to a caller, or send an SMS <Message> in reply to an incoming message. For a full reference on everything you can do with TwiML, refer to our TwiML API Reference.
TwiML is, at it's core, a fun language to write.
Based on XML, eXtensible Markup Language, (just like HTML) it's also very simple to learn and write. Twilio's secret sauce is working to make it a very powerful language.
How powerful? Think allow customer service agents to transfer a caller in a support conference call without dropping it in under ten lines of code powerful.
TwiML is composed of a number of verbs and nouns which act as instructions for Twilio. Those verbs include:
- 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
Nouns generally are acted on by a verb or will modify the verb's behavior. For example, the Message verb will send a text message but the text inside the tags and
Media are nouns which change exactly what Twilio will do. Depending on how you use the nouns, the Message might be a SMS, multiple SMSes, or an MMS.
Click on individual verbs to see the nouns available.
Your application will return TwiML in response to various events. Some of those events might be an incoming phone call or SMS, or perhaps a change in delivery status for a SMS your application sent.
Yes! We encourage you to look at TwiML Bins, Twilio's serverless (and codeless) solution to letting you write TwiML. It's the most frictionless way to start using Twilio: don't worry about spinning up a new VPS or exposing a route to your development machine. TwiML Bins allow you to quickly prototype your app - or even run it in production directly from our servers.
For those of you who are writing code, the Twilio helper libraries will automatically create valid TwiML for you. If you don't use one of our primary languages, don't sweat it! We've included curl commands and raw TwiML with most of our examples so you can call the API or return TwiML from your language of choice.
We can't wait to see what you build.