Platform behaviour

Machine-readable reference

Everything on this site is generated from one structured document. AI agents and tooling should consume these directly:

• /voiceml-spec.json — the canonical spec: every verb and noun with attributes, defaults, behaviour, callbacks, and platform rules, as JSON.
• /llms.txt — index of this reference in the llms.txt convention.
• /llms-full.txt — the complete reference as a single markdown document.

Unknown elements

Any unknown top-level element (typos like <Saw>, or vendor-specific extensions from other platforms) returns a typed unsupported-element error, visible in logs and in the parent verb's action callback when one fires.

URL validation

Every URL attribute (action URLs, callback URLs, audio URLs, stream URLs) is validated against the RFC 3986 printable-ASCII charset before use; CR/LF and backslash are rejected outright. Webhook fetches are HTTPS-only, verified against the system CA bundle.

Webhook signing

Every callback and document fetch is signed with your account's API key using the industry-standard request-signature scheme, so stock webhook-validation middleware in the official helper libraries accepts VoiceML requests without modification.

Caching

Hosted markup (voiceml.org)

Markup published to voiceml.org — the free VoiceML hosting service — is content-addressed: the URL is derived from a hash of the markup itself, so the content behind a given URL is permanent and can never change. It is served with a strong ETag and Cache-Control: max-age=31536000, immutable, and the platform caches it accordingly — effectively forever. Publishing identical markup always returns the same URL; to change what a call does, publish the new markup and point your number at the new URL.

Audio (<Play>)

Audio played by <Play> is pre-fetched to a local cache, deduplicated by upstream ETag, validated by content type, and capped at 50 MiB per file. Change the URL (fingerprinted name or query parameter) to force a refresh.

Self-hosted VoiceML documents

A VoiceML document served from your own server is cached only when that server opts in: Cache-Control: max-age=N caches the parsed document for N seconds; an ETag enables a 5-second burst-dedup window with If-None-Match revalidation; Cache-Control: no-store / no-cache (or no caching headers at all) means every call fetches fresh. Cache entries are keyed per account, so signing continues to work as expected.

The initial voice-URL fetch

The initial voice-URL fetch does not carry call-context fields (CallSid, From, To). A server that must branch per-call on first fetch should encode identifying information into the voice URL itself, or decide from an action callback later in the flow, which does carry full call context.