Copy page

OneML reference

OneML overview

OneML is the XML markup you return from your server to control a live call. When Signals needs instructions for a call, it requests your URL and runs the OneML document your server returns, verb by verb, until the document runs out or a verb ends the call. OneML is compatible with TwiML, so most existing TwiML documents run unchanged.

Document rules

Every OneML document follows the same rules:

• The root element must be <Response>. Signals rejects any document with another root element.
• Verbs run top to bottom, in document order.
• Unknown verbs and unknown attributes are rejected. Parsing is strict: a typo in a verb or attribute name fails the whole document instead of being ignored.

Fetching OneML documents

Signals fetches OneML documents from the URLs you configure: a voice application's voice URL, the Url on a created call, and action or <Redirect> URLs inside a document. A relative action or <Redirect> URL resolves against the URL of the current document. For a GET request, call parameters are sent in the query string. For a POST request (the default), they are sent as an application/x-www-form-urlencoded body.

Signals waits at most 10 seconds for your server to respond and follows at most 5 redirects. See Webhooks for every parameter and limit.

Verbs

Verb	Description
Say	Speaks text to the caller using text-to-speech.
Play	Plays an audio file, or sends DTMF tones, to the caller.
Gather	Collects DTMF digits or speech from the caller.
Record	Records the caller's voice.
Dial	Connects the call to another phone number.
Redirect	Fetches and runs a new OneML document.
Pause	Waits silently for a set duration.
Hangup	Ends the call.
Reject	Rejects an incoming call before it is answered.
Stream	Streams call audio to a WebSocket endpoint.
Disconnect	Ends OneML control of the call without a hangup.

Limits

Limit	Value
Inline OneML document size (Twiml on create-call)	4,000 characters
Redirect loop cap	10 consecutive redirects without new caller input
loop="0" repeat cap	1,000 iterations
Webhook fetch timeout	10 seconds

Check a document before you deploy it

The Signals console includes a OneML checker. Switch the console to Programmable Voice and open OneML to paste a document, or fetch one from a voice application's URL, and review the problems it finds and the steps the document would run.

Minimal example

The following document speaks a greeting and hangs up:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Welcome to Acme Delivery.</Say>
  <Hangup/>
</Response>

A spoken one-time passcode is the same idea, passed inline when you create a call so no server is needed. Separate the digits with spaces so they are read one at a time:

Code
curl -X POST "https://api.signals.pressone.africa/2010-04-01/Accounts/ACCOUNT_SID/Calls.json" \
  -u "ACCOUNT_SID:AUTH_TOKEN" \
  --data-urlencode "To=+2348031234567" \
  --data-urlencode "From=+2342013300100" \
  --data-urlencode "Twiml=<Response><Say loop=\"2\">Your Acme verification code is 4 8 2 9 1 6.</Say></Response>"

Next steps

• Receiving calls: point a number at your server.
• Webhooks: the parameters every request carries.
• Moving from Twilio: TwiML features OneML does not support.