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.
Browse the verbs Validate your VoiceML
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.
<?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>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 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.
<Identity>
The client identity to dial, as a nested element.
<Prompt>
Customise a built-in <Pay> prompt for a specific capture step.
For AI agents and tooling
This reference is machine-readable: /voiceml-spec.json (canonical structured spec), /llms.txt, and /llms-full.txt (complete reference as one markdown document).
Run it
VoiceML runs on VoiceTel's VoiceML clusters. Point your existing helper-library code at the VoiceML API host, keep your webhook-signature validation as is, and your voice application runs unchanged — see the migration guide and compatibility matrix.