# VoiceML

> The complete reference for VoiceML, the XML markup for programmable voice: every verb, every noun, every attribute — with defaults, callback fields, and examples. VoiceML documents tell the platform what to do with a phone call: speak, play audio, gather input, record, dial, run conferences and queues, stream audio, transcribe live, or bridge to an AI voice agent.

Machine-readable: the canonical structured spec is at [voiceml-spec.json](https://voiceml.com/voiceml-spec.json) — every verb/noun with attributes, defaults, behaviour text, callbacks, and platform rules as JSON. The full reference as a single markdown document is at [llms-full.txt](https://voiceml.com/llms-full.txt).

## Verbs

- [Say](https://voiceml.com/verbs/say/): Speak text to the caller with text-to-speech.
- [Play](https://voiceml.com/verbs/play/): Play an audio file, or send touch-tone digits, to the caller.
- [Gather](https://voiceml.com/verbs/gather/): Collect digits or speech from the caller and post the result to your server.
- [Record](https://voiceml.com/verbs/record/): Record the caller's audio and post the recording to your server.
- [Dial](https://voiceml.com/verbs/dial/): Connect the caller to another party: a phone number, SIP endpoint, client, conference, queue, or saved application.
- [Enqueue](https://voiceml.com/verbs/enqueue/): Place the caller into a named waiting queue.
- [Leave](https://voiceml.com/verbs/leave/): Exit the current queue from inside an <Enqueue> wait loop.
- [Pause](https://voiceml.com/verbs/pause/): Wait silently for a number of seconds.
- [Hangup](https://voiceml.com/verbs/hangup/): End the call.
- [Reject](https://voiceml.com/verbs/reject/): Reject an incoming call without answering it.
- [Refer](https://voiceml.com/verbs/refer/): Transfer the call to a SIP endpoint.
- [Connect](https://voiceml.com/verbs/connect/): Connect the call to a streaming destination: a raw audio WebSocket or an AI voice-agent relay.
- [Start](https://voiceml.com/verbs/start/): Start a background session — audio stream, live transcription, or SIP session recording — while the document continues.
- [Stop](https://voiceml.com/verbs/stop/): Stop a background session started with <Start>.
- [Redirect](https://voiceml.com/verbs/redirect/): Fetch a new VoiceML document and continue the call with it.
- [Echo](https://voiceml.com/verbs/echo/): Echo the caller's audio back to them — a media loopback test.
- [Sms](https://voiceml.com/verbs/sms/): Send an SMS as a side-effect of the voice call (legacy form of <Message>).
- [Message](https://voiceml.com/verbs/message/): Send an SMS or MMS as a side-effect of the voice call.
- [Pay](https://voiceml.com/verbs/pay/): Capture card payment details over the phone. Accepted and validated; capture runtime is enabled per account.

## Nouns

- [Number](https://voiceml.com/nouns/number/): Dial a phone number.
- [Sip](https://voiceml.com/nouns/sip/): Dial a SIP URI directly, or name the transfer target of a <Refer>.
- [Client](https://voiceml.com/nouns/client/): Dial a registered SIP client by identity.
- [Conference](https://voiceml.com/nouns/conference/): Join the call into a named conference room.
- [Queue](https://voiceml.com/nouns/queue/): Bridge the caller (typically an agent) to the front-of-queue waiting caller.
- [Application](https://voiceml.com/nouns/application/): Hand the call leg to a saved Application's voice URL.
- [Sim](https://voiceml.com/nouns/sim/): Mobile-SIM dialing. Not supported.
- [Stream](https://voiceml.com/nouns/stream/): Fork the call audio to your WebSocket server.
- [ConversationRelay](https://voiceml.com/nouns/conversation-relay/): Bridge the call to your AI voice agent over a JSON WebSocket — the platform runs speech recognition and synthesis in-line.
- [Transcription](https://voiceml.com/nouns/transcription/): Live transcription of the call, delivered to your webhook while the document keeps executing.
- [Siprec](https://voiceml.com/nouns/siprec/): Stream both legs of the call to your session-recording server over the SIPREC standard (RFC 7866).
- [Parameter](https://voiceml.com/nouns/parameter/): A name/value pair passed through to the parent element's session.
- [Identity](https://voiceml.com/nouns/identity/): The client identity to dial, as a nested element.
- [Prompt](https://voiceml.com/nouns/prompt/): Customise a built-in <Pay> prompt for a specific capture step.

## Platform

- [Platform behaviour](https://voiceml.com/platform/): unknown-element handling, URL validation, webhook signing, and caching (hosted markup on voiceml.org, audio, self-hosted documents).

## Optional

- [VoiceML on VoiceTel](https://voicetel.com/voiceml/): the hosted runtime.
- [Compatibility matrix](https://voicetel.com/voiceml/compatibility/): REST and markup surface comparison.
- [VoiceML validator](https://voicetel.com/voiceml/validator/): paste markup, get validation.