TwiML overview
TwiML (Twilio Markup Language) is XML that tells Ruut Voice what to do on a call: speak, play audio, gather input, record, or dial. The root element is always
<Response>.How TwiML executes
When a call connects (outbound) or a number rings (inbound), Ruut Voice fetches TwiML — either from your server's URL or inline from the API — and executes each verb in order. Verbs like
<Say> and <Play> run sequentially; <Gather> pauses for input; <Dial> transfers the call.Structure
1234<?xml version="1.0" encoding="UTF-8"?> <Response> <!-- verbs go here, in execution order --> </Response>
Return it correctly
Your server must return TwiML with
Content-Type: text/xml (or application/xml). The SDK builds valid TwiML for you:12345import { VoiceResponse } from "@ruut/voice-sdk"; const xml = new VoiceResponse() .say("Hello world", { voice: "alice" }) .toXml();
⚠️ Build on the
VoiceResponse object. Calling .toXml() on a sub-builder (e.g. the return of dial()) drops the <Response> root and the platform rejects it.The verbs
| Verb | Purpose | Reference |
<Say> | Speak text with text-to-speech | say |
<Play> | Play an audio file | play |
<Gather> | Collect DTMF digits or speech | gather |
<Record> | Record a message (optionally transcribe) | record |
<Dial> | Transfer to a number, SIP, client, or conference | dial |
<Pause> | Wait for a number of seconds | pause |
<Hangup> | End the call | hangup |
<Redirect> | Fetch new TwiML and continue | redirect |
Next
See the full TwiML verbs reference, or jump to a guide on receiving calls.