Key takeaways
- TwiML is XML with a
<Response>root; each element inside it, such as<Say>,<Dial>or<Gather>, is called a verb. - Twilio fetches TwiML from the voice webhook URL set on a number or a TwiML App, then runs the verbs in order.
- Twilio’s helper libraries generate TwiML in code, and TwiML Bins host static TwiML without a server.
- Verbs placed after a
<Dial>run only when the dialed call ends; with an action URL on<Dial>, they never run at all (Twilio<Dial>docs).
What is TwiML (Twilio Markup Language)?
TwiML (Twilio Markup Language) is the XML a voice application returns to tell Twilio what to do on a call, so the app never handles audio itself. When a call arrives at a Twilio number, Twilio sends an HTTP request to the webhook URL configured on that number, with details such as From, To and CallSid. Your server replies with a TwiML document, and Twilio executes it: speaking, playing, dialing or gathering input as instructed (Twilio TwiML docs). When a verb finishes, it can call another URL with its result, which returns the next TwiML.
Outbound calls work the same way. An app that places a call through the API passes a URL or inline TwiML for what happens when the call connects. A browser softphone built on the Twilio Voice SDK points at a TwiML App, which tells Twilio which URL to ask when the browser places a call; that URL usually returns a <Dial> with the number to call and the caller ID to use.
What are the main TwiML verbs?
TwiML has a small vocabulary. Verbs are the actions, and nouns, such as <Number> or <Client> inside <Dial>, say what a verb acts on. Attributes tune each verb: a timeout, a caller ID, a callback URL. The verbs below cover most voice applications; the full list is in Twilio’s documentation.
| Verb | What it does | Typical use |
|---|---|---|
<Say> | Speaks text with a text-to-speech voice | Greetings, recording notices |
<Play> | Plays an audio file or keypad tones | Hold music, prerecorded messages |
<Dial> | Connects the call to a number, browser client, SIP address or conference | Outbound dialers, call forwarding, transfers |
<Gather> | Collects keypresses or speech, then posts them to a URL | Phone menus, opt-out keys |
<Record> | Records the caller and posts the recording URL | Voicemail boxes |
<Redirect> | Fetches new TwiML from another URL | Multi-step call flows |
<Hangup> | Ends the call | After a message or failed check |
How does TwiML work in an outbound dialer?
A browser dialer on Twilio follows a fixed chain. The rep clicks call; the Voice SDK in the browser sends the number to Twilio; Twilio requests the TwiML App’s voice URL; your server checks the request, picks the caller ID, and returns a <Dial> with a <Number>. The <Dial> can set record to record from answer, timeout for how long to ring, and answerOnBridge so the rep hears real ringing (Twilio `<Dial>` docs); record-from-answer-dual puts each side of the call on its own channel. The <Number> noun can carry a status callback for ringing and answer events and switch on answering machine detection with its machineDetection attribute (Twilio `<Number>` docs).
Inbound calls use the same pieces in reverse: a call to your number fetches TwiML that dials one or more browser clients with <Client> nouns, and a mobile with <Number>, so the first to answer wins. Our walkthrough on how to make outbound calls with Twilio shows the API side of the same flow.
What TwiML mistakes do developers make?
Most TwiML bugs show up as silence, Twilio’s spoken application error message or a call that ends early, and Twilio’s debugger in the Console logs the cause. Check these first.
- Returning HTML, JSON or an empty response instead of XML with the
text/xmlcontent type. - Unescaped characters, such as an ampersand in a URL, which make the XML invalid.
- Using a caller ID that is not a Twilio number or verified caller ID on the account.
- Not validating Twilio’s request signature, so anyone can call your webhook.
- Expecting verbs after a
<Dial>to run while the call is connected; they run after it ends.
When do you not need to write TwiML?
Writing TwiML means hosting a webhook server, handling callbacks and testing call flows, which is worth it when you are building a voice product or a custom phone menu. A sales team that only wants to call lists from a browser does not need to write it: Twilio Studio offers a visual builder for simple flows, and dialers that connect to your Twilio account generate the TwiML for you. Our guide to outbound calling on Twilio compares those routes.
How does TwiML (Twilio Markup Language) relate to Rapidialer?
Rapidialer writes the TwiML so you do not have to. Connecting Twilio creates an API key and a TwiML App in your own Twilio account, and syncing points your numbers’ voice webhooks at Rapidialer. On an outbound call it returns a <Dial> with your chosen caller ID and a <Number>; with call recording on, the dial records both channels from answer, and with voicemail detection on, the <Number> runs asynchronous answering machine detection. Inbound calls get a <Dial> with <Client> nouns for the browsers to ring. At Twilio’s US list prices, an outbound call from the browser costs $0.014 a minute for the phone leg plus $0.004 for the browser leg (checked November 2026).
Related terms
- WebRTCThe open standard that lets web browsers send real-time audio, video and data without plugins.
- SoftphoneSoftware that makes and receives phone calls on a computer or mobile device over the internet.
- Answering machine detection (AMD)Technology that tells whether a call was answered by a person or by voicemail.
TwiML (Twilio Markup Language): questions and answers
Is TwiML the same as XML?
TwiML is written in XML, but it is a specific vocabulary that only Twilio understands. Every TwiML document is valid XML with a <Response> root element and verbs Twilio defines, such as <Say> and <Dial>. A generic XML file will not do anything on a call unless it uses those elements, and invalid XML causes an application error.
Do I need a server to use TwiML?
Not always. TwiML Bins let you host static TwiML in the Twilio Console and point a number at it, which works for fixed messages or forwarding to one number. Anything that changes per call, such as choosing a caller ID or logging results, needs code running on a server or on Twilio Functions, Twilio’s hosted serverless option.
What is a TwiML App?
A TwiML App is a Twilio resource that holds a voice URL and a messaging URL, without being tied to a phone number. Browser and mobile softphones built on the Twilio Voice SDK use it: when the softphone places a call, Twilio fetches TwiML from the app’s voice URL to learn which number to dial and how. Software that runs on your Twilio account often creates one for you.
Can TwiML record calls?
Yes, in two ways. The <Record> verb records the caller, typically for voicemail, and posts the recording URL to your server. For conversations, the <Dial> verb’s record attribute records the connected call, in mono or dual channel, from ringing or from answer. Recording is billed per minute by Twilio, and recording laws in some states require telling everyone on the call.
What is the difference between TwiML and Twilio Studio?
TwiML is the instruction format Twilio executes on a call. Studio is a visual, drag-and-drop builder in the Twilio Console that lets you design call and message flows without writing code; behind the scenes Twilio runs those flows itself. Developers use TwiML for full control and logic in their own code; Studio suits simpler flows maintained by non-developers.
How do I generate TwiML in code?
Use Twilio’s helper library for your language, such as Node.js, Python, PHP, C#, Java or Ruby, which has a VoiceResponse class. You call methods like say, dial and gather, and the library outputs valid XML. Return that string from your webhook with the text/xml content type, and Twilio executes it on the call.