Only 8 spots left$15 $2/seat/month for life for the next 8 founding teams.Claim your spot →

Glossary

What is TwiML?

TwiML (Twilio Markup Language) is the set of XML instructions that tells Twilio what to do during a phone call or message: speak text, play audio, collect keypresses, record, or connect to another number. When a call reaches a Twilio number, Twilio asks your server, or a hosted TwiML Bin, what to do, and runs the TwiML that comes back from top to bottom.

Updated · Reviewed by Jaffar Jawed

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.

Common TwiML voice verbs
VerbWhat it doesTypical use
<Say>Speaks text with a text-to-speech voiceGreetings, recording notices
<Play>Plays an audio file or keypad tonesHold music, prerecorded messages
<Dial>Connects the call to a number, browser client, SIP address or conferenceOutbound dialers, call forwarding, transfers
<Gather>Collects keypresses or speech, then posts them to a URLPhone menus, opt-out keys
<Record>Records the caller and posts the recording URLVoicemail boxes
<Redirect>Fetches new TwiML from another URLMulti-step call flows
<Hangup>Ends the callAfter 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/xml content 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).

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.

Start today

Import your list and make your first call today

Connect Twilio, upload a CSV and start dialing.