The API interprets the InboundXML document based on its markup. The markup, composed of basic XML elements, contains the instructions that determine how RooR API should respond. All InboundXML elements are camelcase and case-insensitive and are organized into Verbs or Nouns. Verbs - Elements that define the behavior of the call or text. Nouns - Elements that define the specifics of the behavior. These are always nested inside of verbs and they can be XML elements or plain text. For simplicity, the Verbs are referred to as Voice Elements, and the Nouns are the attribute parameters for the Voice Elements. All supported InboundXML elements are documented below. For each Voice Element definition, there is:
' " # { } < > ? and will be stripped from the URL during parsing.
The <Say> element reads text to the caller using a text-to-speech engine. <Say> is good to use with dynamic data, while <Play> may be a better choice for static information or prompts. The text to be read is nested within the <Say> element.
| Field | Required | Description |
|---|---|---|
| voice | optional |
The language, type, and gender of the voice that will read the text to the caller Note: Valid values: See the voice example below Default value: |
| loop | optional |
The amount of times the spoken text should be repeated Note: Valid values: integer greater than or equal to 1. Default value: 1 |
Say Example: <Response>
<Say loop='3' voice='woman'>Hello</Say>
<Say voice='woman'>Hello, my name is Jane.</Say>
<Say loop='1'>Now I will not stop talking.</Say>
</Response><calldetails>The
| Field | Required | Description |
|---|---|---|
| loop | optional |
The amount of times the should be repeated. 1 indicates an infinite loop. Note: Valid values: integer greater than or equal to 1 Default value: 1 |
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Play>https://docs.gynetix.com/sounds/cowbell.mp3</Play>
</Response>The element allows callers to input digits to the call using keypads which are then sent via POST or GET to a URL for processing.
There are many ways to get creative with but its most common use case is in creating IVR menus. This is done by nesting prompts for input from the caller using the or elements. Only a single or element can be nested in a tag.
By default an unlimited number of digits can be gathered. The will timeout after 5 seconds pass without any new digits or once the '#' key is pressed, then the gathered digits will be submitted to the current InboundXML document. This default behavior of can be altered using its provided element attributes.
The element cannot be nested within any other verbs besides the default element.
The and elements MUST nested within the element.
<Response>
<Gather action='https://....' method='GET' numDigits='4' finishOnKey='#'>
<Say>Please enter your 4 digit pin</Say>
</Gather>
</Response>
| Field | Required | Description |
|---|---|---|
| action | optional |
The URL where the flow of the call and the gathered digits will be forwarded to. Note: Valid values: integer greater than or equal to 1 Default value: 1 |
| method | optional |
Method used to request the action URL. Note: Valid values: POST, GET Default value: POST |
| timeout | optional |
The number of seconds should wait for digits to be entered before requesting the action URL. Timeout resets with each new digit input. Note: Valid values: integer greater than or equal to 0 Default value: 5 |
| finishOnKey | optional |
The key a caller can press to end the Note: Valid values: digits 0 to 9, #, or * Default value: # |
| numDigits | optional |
The maximum number of digits to . Note: Valid values: integer greater than or equal to 1 Default value: 1 |
| input | optional |
Specify which inputs (DTMF or speech) RooR should accept with the input attribute. Note: The default input for Valid values: dtmf, speech, dtmf speech Default value: dtmf |
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Gather input="speech" action="https://...">
<Say>Welcome to Twilio, please tell us why you're calling</Say>
</Gather>
</Response>The element is used to record audio during a call. It can occur anywhere within an InboundXML document but will only begin recording once it has been reached. This means it would have to be the first element after for the entire call to be recorded.
When the recording is complete, a URL of the recorded audio is created and submitted as a GET or POST to the action URL. Similar to the element, a timeout value sets how much silence to allow before the recording ends, maxLength sets how long the recording may be, and the finishOnKey is used to set which keys will end the recording.
By default, the action and method specify that should make a POST to the URL of the current InboundXML document.
###Element AttributesThe element cannot be nested within any other verbs besides the default element. The element cannot nest any other elements within itself.
<Response>
<Say>Please state your name.</Say>
<Record background="false" action="https://..." timeout="100" method="POST" finishOnKey="#"></Record>
</Response>
| Field | Required | Description |
|---|---|---|
| action | optional | URL where some parameters specific to will be sent for further processing. |
| method | optional |
Method used to request the action URL. Valid values: POST, GET Default value: POST |
| timeout | optional |
The number of seconds should wait during silence before ending. Valid values: integer greater than or equal to 1 Default value: 5 |
| finishOnKey | optional |
The key a caller can press to end the Valid values: digits 0 to 9, #, or * Default value: # |
| maxLength | optional |
The maximum length in seconds a recording should be. Valid values: integer greater than or equal to 1 Default value: 3600 |
| playBeep | optional |
Boolean value specifying if a beep should be played when the recording begins. Valid values: true, false Default value: false |
| background | optional |
Begin recording the call while continuing the execution of any other present InboundXML in the background (true) or block the execution of subsequent InboundXML until the record element finishes (via finishOnKey or timeout). Note that the timeout, finishOnKey, and playBeep attributes have no effect when the background is set to true. Valid values: true, false Default value: true |
| trimSilence | optional |
Trims all silence from the beginning of the recording. Any other value will default to "false". Valid values: true, false Default value: true |
The element starts an outgoing dial from the current call. Once the dial is complete, the next element in the InboundXML document will be processed unless the action attribute is set. In that case, the result of the dial is submitted as a GET or POST (depending on the method attribute) to the action URL, and the call continues using the InboundXML of that URL.
By default the outgoing call will timeout if it is not answered after 60 seconds. However, the timeout attribute can be used to set a custom time. The length of the call is limited by the timeLimit attribute which is 4 hours (14400 seconds) by default.
The callerId attribute can be set to any number and will default to the caller ID of the original caller. The number to be dialed should be nested within the element.
In it's most basic form the tag will look like:
+15557774545 The element can't be nested within any other verbs besides the default element.
The element can be nested within the element.
<Dial> Example
<Response>
<Dial action="https://..."
callerid="949XXXYYYY">714XXXYYYY
</Dial>
</Response>
| Field | Required | Description |
|---|---|---|
| action | optional | URL where some perameters specific to will be sent for furhter processing. The calling party can be redirected here upon the hangup of the B leg caller. |
| method | optional |
Method used to request the action URL. Valid values: Post, Get Default value: Post |
| timeout | optional |
Number of seconds call stays on the line while waiting for an answer. Default value: 60 |
| timeLimit | optional |
The duration in deconds a call made through should occur for before ending. Note: Valid values: integer greater than or equal to 1 Default value: 14400 |
| callerId | optional |
Number to display as calling. Defaults to the ID of the phone being used. Default value: Only valid US number |
| hideCallerId | optional |
Boolean value specifying if the caller ID should be hidden or not. Note: If value is set to TRUE, then caller ID will be hidden. Valid values: TRUE, FALSE Default value: FALSE |
| dialMusic | optional |
Audio URL to be executed in place of the call ring-tone. Valid values: mp3, wav |
| callbackURL | optional | URL requested once the dialed call connects. Note that this url only receives paramerters containing information about the call. The call does not execute XML given as a callback URL. |
| callbackMethod | optional |
Method used to request the callback URL. Valid values: POST, GET Default value: POST |
| confirmSound | optional |
Boolean value specifying if a sounds should play when dial is successful. Valid values: TRUE, FALSE Default value: FALSE |
| heartbeatUrl | optional | The URL that Roor API requests every 60 seconds during the call to notify of elapsed time as well as to pass other general information. |
| heartbeatMethod | optional |
Method used to request heartbeatUrl. Valid values: POST, GET Default value: POST |
| groupConfirmKey | optional |
This is the single digit numeric value to be pressed to accept the call. Note: Use this attribute when you are using multiple to numbers. Valid values: digits 0 to 9, #, * Default value: 1 |
| groupConfirmFile | optional |
Audio file URL which can be played adfter answering the call to accept the call Note: Use this attribute when you are using multiple to numbers Valid values: Any audio file URL with mp3 or wav format. Default value: https://... |
| onAnswerPlay | optional |
Before the dial action is performed, this plays an audio to leg B to leg B of the call (The number being called in the tag). The tag can include either onAnswerPlay or onAnswerSay but not both. Valid values: audio file URL. 8bit mono 8000Hz mu-law .mp3 or .wav format. |
| onAnswerSay | optional |
Before the dial action is performed, this reads text to Leg B to leg B of the call (The nubmer being called in teh tag) using a text-to-speech engine. The tag can include either onAnswerPlay or onAnswerSay but not both. Valid values: string |
| CallerName | optional |
A String passed in the SIP header that will display on Softphones. Valid values: string (max 25 chars) |
| PlayDTMF | optional |
A set of DTMF digits that will play when Leg B of hte call answers. Valid values: digits 0 to 9, #, * |
| PlayDTMFDelay | optional |
The amount of time in seconds the system will wait befoer executing PlayDTMF Valid values: decimal (In half second intervals) |
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>+15555555555</Dial>
<Say>Goodbye</Say>
</Response>Bi-directional Media Streams:
If you want to send media back to the call, the Stream *must* be bi-directional. To do this initialize the stream using the <Connect> verb. The <Stream> noun's url attribute must be set to a secure websocket server (wss).
Nestable:
You can nest the <Parameter> noun inside the stream to pass custom information to the web socket connection.
| Field | Required | Description |
|---|---|---|
| url | Required |
URL must be set to a secure websocket server (wss) Note: Valid values: wss Default value: |
| streamType | optional |
Setting the stream type you can either get MULAW or Signed Linear 16 bit both are at 8Khz Note: Valid values: ulaw or slin8 Default value: ulaw |
| noiseFilter | optional |
Setting this to on will tell RooR to block out background noises Note: Valid values: off or on Default value: off |
| name | optional |
Give this stream a name Note: Valid values: Default value: |
| track | optional |
The track that will be sent to your web socket. Bi directional stream only support the inbound_track Note: Valid values: inbound_track Default value: inbound_track |
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Connect>
<Stream url="wss://..." />
<Parameter name="FirstName" value="Jane" />
<Parameter name="LastName" value="Doe" />
</Connect>
</Response><calldetails>