VoiceML reference
Every verb. Every noun. Every option.
VoiceML is the XML markup that tells the platform what to do with a phone call: speak, play audio, gather input, record, dial out, run conferences and queues, stream audio, transcribe live, or bridge to your AI voice agent. This site is the complete customer reference for writing it.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Thanks for calling.</Say>
<Gather numDigits="1" action="https://app.example.com/menu">
<Say>For sales, press 1. For support, press 2.</Say>
</Gather>
</Response>How it works
How VoiceML works
When a call reaches your number, the platform requests your voice URL and executes the VoiceML document your server returns, verb by verb, in document order. Verbs with an action attribute post their result back to your server and continue with the document you return — that request/response loop is the whole programming model.
-
A call arrives
The platform requests the voice URL set on your number.
-
Your document runs
The VoiceML your server returns executes verb by verb, in document order.
-
Actions post back
A verb with an
actionattribute posts its result to your server; the document you return continues the call.
Verbs
Verbs
Verbs are the top-level instructions inside <Response>.
-
<Say>Speak text to the caller with text-to-speech.
-
<Play>Play an audio file, or send touch-tone digits, to the caller.
-
<Gather>Collect digits or speech from the caller and post the result to your server.
-
<Record>Record the caller's audio and post the recording to your server.
-
<Dial>Connect the caller to another party: a phone number, SIP endpoint, client, conference, queue, or saved application.
-
<Enqueue>Place the caller into a named waiting queue.
-
<Leave>Exit the current queue from inside an <Enqueue> wait loop.
-
<Pause>Wait silently for a number of seconds.
-
<Hangup>End the call.
-
<Reject>Reject an incoming call without answering it.
-
<Refer>Transfer the call to a SIP endpoint.
-
<Connect>Connect the call to a streaming destination: a raw audio WebSocket or an AI voice-agent relay.
-
<Start>Start a background session — audio stream, live transcription, or SIP session recording — while the document continues.
-
<Stop>Stop a background session started with <Start>.
-
<Redirect>Fetch a new VoiceML document and continue the call with it.
-
<Echo>Echo the caller's audio back to them — a media loopback test.
-
<Sms>Send an SMS as a side-effect of the voice call (legacy form of <Message>).
-
<Message>Send an SMS or MMS as a side-effect of the voice call.
-
<Pay>Capture card payment details over the phone. Accepted and validated; capture runtime is enabled per account.
Nouns
Nouns
Nouns are the elements nested inside a verb that name what it acts on — who to dial, where to stream, what to transcribe.
-
<Number>Dial a phone number.
-
<Sip>Dial a SIP URI directly, or name the transfer target of a <Refer>.
-
<Client>Dial a registered SIP client by identity.
-
<Conference>Join the call into a named conference room.
-
<Queue>Bridge the caller (typically an agent) to the front-of-queue waiting caller.
-
<Application>Hand the call leg to a saved Application's voice URL.
-
<Sim>Mobile-SIM dialing. Not supported.
-
<Stream>Fork the call audio to your WebSocket server.
-
<ConversationRelay>Bridge the call to your AI voice agent over a JSON WebSocket — the platform runs speech recognition and synthesis in-line.
-
<Transcription>Live transcription of the call, delivered to your webhook while the document keeps executing.
-
<Siprec>Stream both legs of the call to your session-recording server over the SIPREC standard (RFC 7866).
-
<Parameter>A name/value pair passed through to the parent element's session.
-
<Header>A custom SIP header added to the outgoing INVITE of a <Sip> dial.
-
<Identity>The client identity to dial, as a nested element.
-
<Prompt>Customise a built-in <Pay> prompt for a specific capture step.
-
<Body>The text of a <Message>, as a nested element.
-
<Media>Attach a media file to a <Message>, sending it as MMS.
VoiceML Studio
Build call flows without writing XML.
VoiceML Studio is a drag-and-drop editor for call flows. Build a flow from VoiceML steps, see problems on the canvas as you go, and export VoiceML checked against this reference, ready to publish on voiceml.org. Existing VoiceML, including Liquid templates, imports back into the flow chart.
It runs entirely in your browser: no account, and your flows stay on your device until you export them.
For AI agents and tooling
Machine-readable, end to end.
This reference is machine-readable: /voiceml-spec.json (canonical structured spec), /llms.txt, and /llms-full.txt (complete reference as one markdown document).
Publishing documents to a permanent URL and delivering voicemail, recordings, and transcripts are documented for agents at voiceml.org/llms.txt and voiceml.org/llms-full.txt.
Start with one call flow.
Build it in Studio or write it by hand, check it against the schema, then publish it on voiceml.org.