InboundXML describes how Ytel API should handle a voice call or SMS message. An InboundXML document is made up of various XML elements nested inside a response element. Upon receiving a call or a text, the Ytel API follows the InboundXML instructions, enabling developers to easily build telephony apps with all the same function and power found in traditional phone systems.
When a call or SMS is initiated using the API, the URL of an InboundXML document is passed as a parameter to describe what will happen when the contacted party answers. Every phone number registered through Ytel API points to a URL containing one of these InboundXML documents.
Let's get started...
Getting started with InboundXML is simple and straightforward. The steps for creating an InboundXML document are defined below:
- Host a file on your server containing the InboundXML syntax.
- Set the Voice URL and/or SMS URL paths for the hosted InboundXML document.
- Initiate voice calls or SMS messages to the hosted InboundXML file to receive a response.
The following is a sample of a simple InboundXML document:
<Response>
<Say>Hello. Welcome to Ytel API.</Say>
<Hangup></Hangup>
</Response>
The Request Format
When handling an inbound call, Ytel API requests the Voice Request URL (or any other subsequent URLs Ytel API may interact with) using standard HTTP GET or POST methods. The HTTP method used (GET or POST) can be specified on a case by case basis but both HTTP Methods send a set of default request parameters to the API.
Refer to the table below on a list of these default call parameters that are sent. This is how Ytel API contains information about the type of call taking place.
If the initial request method is GET, these values are sent as URL query parameters. If it is POST, they are sent as POST parameters.
Field Description
-
accountSID
- The accountSID string value for the account from which the call occurred
-
to
- The telephone number being called. Must be in e.164 format (+1xxxXXXxxxx)
-
from
- The telephone number that initiated the call. Must be in 3.164 format (+1xxxXXXxxxx)
-
callSid
- The callSID string value for the call object
-
status
- Status for the call
- Valid Values:
-
in-queue
dialing
in-progress
user_busy
no_answer
insufficient_funds
unallocated_number
completed
-
Response Format
Every number tied to a Ytel account can be configured to respond to voice calls or SMS messages with an InboundXML document.
The API interprets the InboundXML document based on its markup. The markup, which is composed of basic XML elements, contains the instructions that determine how Ytel 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.
<Response>
<Say>You are about to execute a new call.</Say>
<Dial action="https://yourURLhere
<Say>We have passed the Dial. The call will now hang up.</Say>
<Hangup></Hangup>
</Response>
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:
- A description/purpose of what the element does
- A table of voice element attributes (nouns)
- Information on how the voice element can be nested, if applicable
- A code snippet
- A list of usage tips, if applicable
Note: The following special characters are disallowed in the URL query string options and will be stripped from the URL during parsing: ' " & # { } < > ?
InboundXML Voice Elements
The following section defines the InboundXML elements for Ytel API. Used together and nested, these elements define an InboundXML document.
1. Say
The 'Say' element reads text using a text-to-speech engine. The text to be read is nested within the 'Say' element. This element is good to use with dynamic data.
Attributes
-
voice
- Optional. The gender of the voice that will read the text to the caller.
- Valid values: woman
-
loop
-
Optional. The amount of times the spoken text should be repeated.
- Valid values: integer greater than or equal to 1
- Default value: 1
- 1 = infinite loop
-
Optional. The amount of times the spoken text should be repeated.
Nesting
In addition to the default 'Response' element, the 'Say' element can also be nested within the 'Gather' verb.
The 'Say' element cannot nest any other elements within itself - it must only nest the text which will be read to the caller.
Example InboundXML Document
The InboundXML example below will use a woman's voice to say "Hello" three (3) times, then "My name is Jane" once, and then repeat "Now I will not stop talking" until the caller hangs up.
<Response>
<Say loop='3' voice='woman'>Hello.</Say>
<Say voice='woman'>My name is Jane.</Say>
<Say loop='1'>Now I will not stop talking.
</Say>
</Response>
Tips
Using the 'Say' element with abbreviations, times, or phonetically challenging words can sometimes produce an output which you don't expect. Always double check your punctuation, and consider "mis-spelling" words to achieve the desired output.
2. Play
The 'Play' element plays an audio file for the caller. The content nested within the 'Play' should be the URL of an audio file. The valid audio file must be 8-bit mono 8000Hz mulaw in either .mp3 or .wav format.
Attributes
-
loop
-
Optional. The amount of times the spoken text should be repeated.
- Valid values: integer greater than or equal to 1
- Default value: 1
- 1 = infinite loop
-
Optional. The amount of times the spoken text should be repeated.
Nesting
In addition to the default 'Response' element, the 'Play' element can also be nested within the 'Gather' verb.
The 'Play' element cannot nest any other elements within itself - it must only nest the URL or tone stream which will be played to the caller.
Example InboundXML Document
<Response>
<Play loop='3'>http://yourURLhere.com/hello.wav</Play>
</Response>
Tips
Using the 'Play' element is best for static audio files.
3. Gather
The 'Gather' element allows callers to input digits to the call using their keypads which are then sent via POST or GET to a URL for further processing. There are many ways to get creative with 'Gather' but its most common use case is in creating IVR menus. This is accomplished by nesting prompts for input from the caller using the 'Say' or 'Play' elements. Only a single 'Say' or 'Play' element can be nested in a 'Gather' tag.
Be default, an unlimited number of digits can be gathered, the 'Gather' will timeout after 5 seconds pass without any new digits or once the '#' key is pressed, and the gathered digits will be submitted to the current InboundXML document. This default behavior of 'Gather' can be altered using its provided element attributes.
Attributes
-
action
-
Optional. The URL where the flow of the call and the gathered digits will be forwarded to.
- Valid values: POST, GET
- Default value: POST
-
Optional. The URL where the flow of the call and the gathered digits will be forwarded to.
-
method
-
Optional. Method used to request the action URL.
- Valid values: POST, GET
- Default value: POST
-
Optional. Method used to request the action URL.
-
timeout
-
Optional. The number of seconds 'Gather' should wait for digits to be entered before requesting the action URL. Timeout resets with each new digit input.
- Valid values: integer greater than or equal to 0
- Default value: 5
-
Optional. The number of seconds 'Gather' should wait for digits to be entered before requesting the action URL. Timeout resets with each new digit input.
-
finishonkey
-
Optional. The key a caller can press to end the 'Gather'
- Valid values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, or *
- Default value: #
-
Optional. The key a caller can press to end the 'Gather'
-
numDigits
-
Optional. The maximum number of digits to 'Gather'.
- Valid values: integer greater than or equal to 1
- Default value: 1
-
Optional. The maximum number of digits to 'Gather'.
Nesting
The 'Gather' element cannot be nested within any other verbs, not including the default 'Response' element.
The 'Say' and 'Play' elements can be nested within the 'Gather' element.
Example InboundXML Document
<Response>
<Gather action='https://yourURLhere.com/useraction/input'>
<Say>Please enter your 4-digit PIN number</Say>
</Gather>
</Response>
Tips
- If nested 'Say' or 'Play' elements are present, the timeout attribute starts after either the first key to be gathered is pressed, or say/play prompt completes.
- If the 'Gather' verb fails to execute, the next verb below (if present) will execute.
4. Record
The 'Record' element is used to record audio during a call.
While it can occur anywhere within an InboundXML document, the recording will only begin once it has been reached.
- TIP: to record the entire call, the 'Record' element will need to be first.
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.
Attributes
-
action
- Optional. The URL where some parameters specific to the call will be sent for further processing.
-
method
-
Optional. Method used to request the action URL.
- Valid values: POST, GET
- Default value: POST
-
Optional. Method used to request the action URL.
-
timeout
-
Optional. The number of seconds 'Record' should during silence before ending
- Valid values: integer greater than or equal to 1
- Default value: 5
-
Optional. The number of seconds 'Record' should during silence before ending
-
finishonkey
-
Optional. The key a caller can press to end the 'Record'
- Valid values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, or *
- Default value: #
-
Optional. The key a caller can press to end the 'Record'
-
maxLength
-
Optional. The maximum length in seconds a recording should be
- Valid values: integer greater than or equal to 1
- Default value: 3600
-
Optional. The maximum length in seconds a recording should be
-
transcribe
-
Optional. Boolean value specifying if the recording should be transcribed.
- Valid values: TRUE or FALSE
- Default value: FALSE
-
Optional. Boolean value specifying if the recording should be transcribed.
-
transribeCallback
-
Optional. The URL that some parameters regarding the transcription will be passed to once completed
- Valid values: valid URL
-
Optional. The URL that some parameters regarding the transcription will be passed to once completed
-
playBeep
-
Optional. Boolean value specifying if a beep should be played when the recording begins.
- Valid values: TRUE or FALSE
- Default value: FALSE
-
Optional. Boolean value specifying if a beep should be played when the recording begins.
-
fileFormat
-
Optional. The recording file format. Cam be .mp3 or .wav
- Valid values: mp3, wav
- Default value: mp3
-
Optional. The recording file format. Cam be .mp3 or .wav
-
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 background is set to true.
- Valid values: TRUE or FALSE
- Default value: TRUE
-
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 background is set to true.
-
trimSilence
-
Optional. Trims all silence from the beginning of the recording. Any other value will default to "false".
- Valid values: TRUE or FALSE
-
Optional. Trims all silence from the beginning of the recording. Any other value will default to "false".
The 'action' Attribute Properties
The following is a set of properties that are sent along with the action URL.
Attribute | Description
RecordingSid | A unique ID that will be created when recording is started for each call
RecordUrl | A valid mp3 or wav audio file URL which contains the recording
recordstarttime | The time when recording is started
recordduration | The duration of the recording, in seconds
recorddirection | The direction of the recording, either 'inbound' or 'outbound'
CallSid | The unique identifier created for each call
AccountSid | A valid Ytel customer account number
From | A valid e.164 format number that will be initiating the call
To | A valid e.164 format number that will receive the phone call
The 'transcribe' Attribute Properties
The following is a set of properties that are sent along with the transcribeCallback URL.
Attribute | Description
status | Status of the transcription
CallSid | The unique identifier created for each call
TranscriptionSid | The unique Transcription identifier
mediaId | The unique media identifier
transcriptionDate | Date when transcription is received
totalPrice | Total price for transcription
recording_sid | The unique Recording identifier
recording_url | A URL leading to an audio file of the recording
Nesting
The 'Gather' element cannot be nested within any other verbs, not including the default 'Response' element. The element cannot nest any other elements within itself.
Example InboundXML Document
<Response>
<Say>Please state your full name.</Say>
<Record background="false" action="https://yourURLhere.com/useraction/input'>
</Response>
5. Dial
The 'Dial' element starts an outgoing call 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 14,400 seconds (4 hours) be default.
The callerId attribute can be set to any number, and will default to the callerID of the original caller. The number to be dialed should be nested within the 'Dial' element.
Attributes
-
action
- Optional. The URL where some parameters specific to 'Dial' will be sent for further 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
-
Optional. Method used to request the action URL.
-
timeout
-
Optional. The number of seconds call stays on the line while waiting for an answer.
- Default value: 60
-
Optional. The number of seconds call stays on the line while waiting for an answer.
-
timeLimit
-
Optional. The duration in seconds a call made through 'Dial' should occur for before ending
- Valid values: interger greater than or equal to 1
- Default value: 14400
-
Optional. The duration in seconds a call made through 'Dial' should occur for before ending
-
callerID
-
Optional. Number to display as calling. Defaults to the ID of the phone being used.
- Valid values: Valid US telephone number
-
Optional. Number to display as calling. Defaults to the ID of the phone being used.
-
hideCallerId
-
Optional. Boolean value specifying if the caller ID should be hidden or not
- Valid values: TRUE or FALSE
- Default value: FALSE (if set to TRUE, the caller ID will be hidden)
-
Optional. Boolean value specifying if the caller ID should be hidden or not
-
dialMusic
-
Optional. Audio URL to be executed in place of the call ring tone
- Valid values: .mp3, .wav
-
Optional. Audio URL to be executed in place of the call ring tone
-
callbackUrl
-
Optional. URL requested once the dialed call connects
- Note that this URL only receives parameters containing information about the call. The call does not execute XML given as a callbackURL.
-
Optional. URL requested once the dialed call connects
-
callbackMethod
-
Optional. Method used to request the callback URL
- Valid values: POST, GET
- Default value: POST
-
Optional. Method used to request the callback URL
-
confirmSound
-
Optional. Boolean value specifying if a sound should play when dial is successful
- Valid values: TRUE or FALSE
- Default value: TRUE
-
Optional. Boolean value specifying if a sound should play when dial is successful
-
digitsMatch
-
Optional. Specifies digits that Ytel API should listen for and send to the callbackUL if a caller interrupts them. Additional digits or digit patterns can be separated with a comma.
- Valid values: Pattern made of up digits 0-9, #, or *
-
Optional. Specifies digits that Ytel API should listen for and send to the callbackUL if a caller interrupts them. Additional digits or digit patterns can be separated with a comma.
-
heartbeatUrl
- Optional. The URL that Ytel 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 the heartbeatUrl
- Valid values: POST, GET
- Default value: POST
-
Optional. Method used to request the heartbeatUrl
-
groupConfirmKey
-
Optional. This is the single digit numeric value to be pressed to accept the call
- Valid values: 0-9, #, *
- Default value: 1
- Note: use this attribute when you are using multiple To numbers
-
Optional. This is the single digit numeric value to be pressed to accept the call
-
groupConfirmFile
-
Optional. Audio file URL which can be played after answering the call to accept the call
- Valid values: any audio file URL with .mp3 or .wav format
- Default value: https://storage.googleapis.com/m360/global/press_1.mp3
- Note: use this attribute when you are using multiple To numbers
-
Optional. Audio file URL which can be played after answering the call to accept the call
-
onanswerplay
- Optional. Before the dial action is performed, this plays an audio file for the caller. The content should be the URL of an audio file. The valid audio file must be 8bit mono 8000Hz mulaw in either .mp3 or .wav format.
-
onanswersay
- Optional. Before the dial action is performed, this reads text to the caller using a text-to-speech engine.
Tip: The dial tag can include 'onanswerplay' or 'ononswersay' but not both
The 'action' Attribute Properties
In addition to the default voice request attributes, these 'Dial'-specific attributes are also forwarded to the callbackUrl and action URL
Attribute | Description
CallSid | The unique identifier created for each call
AccountSid | A valid Ytel customer account number
From | A valid e.164 format number that will be initiating the call
To | A valid e.164 format number that will receive the phone call
The 'heartbeatUrl' Attribute Properties
In addition to the default voice request attributes, these attributes are also forwarded to the heartbeatUrl
Attribute | Description
CallSid | The unique identifier created for each call
AccountSid | A valid Ytel customer account number
From | A valid e.164 format number that will be initiating the call
To | A valid e.164 format number that will receive the phone call
Direction | The direction of the call, either 'inbound' or 'outbound'
CallInitiate | The datetime value for when the call began
CallStartTime | The datetime value for when the call connected
Status | The status of the call, any one of 'in-queue', 'dialing', 'in-progress', 'user_busy', 'no_answer', 'insufficient_funds', 'unallocated_number', or 'completed'.
Nesting
The 'Dial' element cannot be nested within any other verbs, not including the default 'Response' element. The 'Conference' element can be nested within the 'Dial' element.
Group Calling
To make a Group Call, use the 'Dial' element and use a comma ( , ) to separate the numbers to be dialed. The attributes of 'groupConfirmKey' and 'groupConfirmFile' are required for group calls.
The maximum number of To numbers that a Group Call can initiate is ten (10).
6. Sip
The 'Sip' element is nested within the 'Dial' element, and is used to call to SIP addresses. The desired Sip address to call is nested within the opening and closing 'Sip' elements, just as with a number when using the 'Number' element. The opening and closing Sip tags is mandatory prefixing the desired Sip address with "sip:" when using it within the 'Sip' element.
Eg. <Dial> <Sip> sip:username@domain.com </Sip></Dial> .
NOTE: The 'Sip' element must be placed inside of a 'Dial' element.
Attributes
-
action
- Optional. The URL where some parameters specific to 'Dial' will be sent for further 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
-
Optional. Method used to request the action URL.
-
timeout
-
Optional. The number of seconds call stays on the line while waiting for an answer.
- Default value: 60
-
Optional. The number of seconds call stays on the line while waiting for an answer.
-
timeLimit
-
Optional. The duration in seconds a call made through 'Dial' should occur for before ending
- Valid values: interger greater than or equal to 1
- Default value: 14400
-
Optional. The duration in seconds a call made through 'Dial' should occur for before ending
-
callerID
-
Optional. Number to display as calling. Defaults to the ID of the phone being used.
- Valid values: Valid US telephone number
-
Optional. Number to display as calling. Defaults to the ID of the phone being used.
-
dialMusic
-
Optional. Audio URL to be executed in place of the call ring tone
- Valid values: .mp3, .wav
-
Optional. Audio URL to be executed in place of the call ring tone
-
callbackUrl
-
Optional. URL requested once the dialed call connects
- Note that this URL only receives parameters containing information about the call. The call does not execute XML given as a callbackURL.
-
Optional. URL requested once the dialed call connects
-
callbackMethod
-
Optional. Method used to request the callback URL
- Valid values: POST, GET
- Default value: POST
-
Optional. Method used to request the callback URL
-
heartbeatUrl
- Optional. The URL that Ytel 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 the heartbeatUrl
- Valid values: POST, GET
- Default value: POST
-
Optional. Method used to request the heartbeatUrl
Nesting
In addition to the default 'Response' element, the 'Sip' element must also be nested within the 'Dial' verb.
The 'Sip' element cannot nest any other elements within itself. It must only nest the SIP address which is to be called.
SIP format: sip:number@domain_name:port
Example: <Sip>19495551212@yourdomain.com:9999</Sip>
number | required |
@ | required |
domain_name | required |
port | optional |
Example InboundXML Document
<Response>
<Dial action="https://yourdomain.com/sip <Sip>username@domain.com</Sip>
</Dial>
</Response>
7. Conference
Like the 'Number' element, the 'Conference' element is only nested within the 'Dial' element. Instead of dialing a number, the 'Conference' element allows the ongoing call to connect to a conference room. The conference room name is nested within the 'Conference' element, and all calls connected to the same conference room name will be in the room together.
-
By default all callers will hear hold music until two callers are in the room.
- To change this behavior, startConferenceOnEnter may be set to 'true' or 'false'.
- The waitUrl attribute may be used to set a custom MP3, or for greater customization, the URL of a InboundXML document to use while callers are waiting.
- If an InboundXML document is used, the 'Gather', 'Record', and 'Dial' elements are not allowed.
- When callers enter or exit the room, a beep is heard if the beep attribute is set to the default value of 'true'.
- A participant can be initially muted by setting the muted attribute to 'true'.
- The conference room can be limited to a certain number of participants by setting the maxParticipants attribute.
- The endConferenceOnExit attribute is used to end a conference when an specific user (or any one of many users) leaves.
NOTE: The 'Conference' element must be placed inside of a 'Dial' element.
Attributes
-
name
-
Optional. A valid name for the conference.
- Valid value: alphanumeric string without special characters
-
Optional. A valid name for the conference.
-
conferenceId
-
Optional. A numeric 4-digit value without spaces for the conference
- Valid values: 4-digit integer value without spaces, ie. #### (1234)
-
Optional. A numeric 4-digit value without spaces for the conference
-
participantKey
-
Optional. Key value used to add participant through DTMF
- Valid values: *, #
- Note: If hangupOnStar attribute is set to TRUE, then participantKey CANNOT be set as *
-
Optional. Key value used to add participant through DTMF
-
muted
- Optional.
-
Boolean value specifying if the conference should be muted.
- Valid values: FALSE, TRUE
- Default value: FALSE
-
beep
-
Optional. Boolean value specifying if a beep should play upon entering a conference
- Valid values: FALSE, TRUE
- Default value: FALSE
-
Optional. Boolean value specifying if a beep should play upon entering a conference
-
maxParticipants
-
Optional. The maximum number of participants allowed in the conference call
- Valid values: integer from 1 to 10
- Default value: 10
-
Optional. The maximum number of participants allowed in the conference call
-
waitUrl
- Optional. URL conference participants can be sent to while they are waiting to be entered into conference.
-
hangupOnStar
-
Optional. Boolean value specifying if pressing * should end the conference.
- Valid values: FALSE, TRUE
- Default value: FALSE
-
Optional. Boolean value specifying if pressing * should end the conference.
-
callbackUrl
- Optional. URL where some parameters specific to 'Conference' will be sent when participants enter and exit the conference, and once it is completed.
-
callbackMethod
-
Optional. Method used to request the callbackUrl
- Valid values: POST, GET
- Default value: POST
-
Optional. Method used to request the callbackUrl
-
stayAlone
-
Optional. Boolean value specifying if the caller should stay alone in the conference call.
- Valid values: FALSE, TRUE
- Default value: FALSE
-
Optional. Boolean value specifying if the caller should stay alone in the conference call.
-
record
-
Optional. Boolean value specifying if the conference should be recorded.
- Valid values: FALSE, TRUE
- Default value: FALSE
-
Optional. Boolean value specifying if the conference should be recorded.
-
recordCallbackUrl
- Optional. URL the recording will be sent to for the conference
-
recordFormat
-
Optional. File format for the recording to be saved
- Valid values: .mp3, .wav
- Default value: .mp3
-
Optional. File format for the recording to be saved
Nesting
In addition to the default 'Response' element, the 'Conference' element must also be nested within the 'Dial' verb.
No other elements may be nested within the 'Conference' element.
Example InboundXML Document
<Response>
<Conference name="AfternoonMeeting" conferenceid="1004"></Conference>
</Response>
8. Participant
The 'Participant' element allows for the setting of properties on each participant number in a conference.
This element is to be used with the 'Conference' element.
Element Attributes
-
deaf
-
Optional. Set to whether that participant can hear the conference.
- Valid values: FALSE, TRUE
- Default value: FALSE
-
Optional. Set to whether that participant can hear the conference.
-
muted
-
Optional. Set to whether the participant can speak into the conference.
- Valid values: FALSE, TRUE
- Default value: FALSE
-
Optional. Set to whether the participant can speak into the conference.
Nesting
In addition to the default 'Response' element, the 'Participant' element must also be nested within the 'Conference' verb.
No other elements may be nested within the 'Participant' element.
Example InboundXML Document
<Response>
<Conference name="M360test" conferenceid="6543" callbackurl="http://yourdomain.com <Participant muted="TRUE" deaf="TRUE">949XXXYYYY</Participant> <Participant muted="FALSE" deaf="TRUE">714XXXYYYY</Participant> <Participant muted="TRUE" deaf="FALSE">714XXXYYYY</Participant> </Conference>
</Response>
9. Block
The 'Block' element is a chunk of InboundXML that can only be executed by the 'Goto' and 'Gosub' tags. A 'Block' element can be thought of as a container for other elements.
The 'Block' element is used with and related to both 'Goto' and 'Gosub'
Element Attributes
-
label
-
Required. The name/identifier that labels a 'Block' element. The 'Goto' and 'Gosub' elements will jump to and execute the InboundXML for this label.
- Valid values: a string value
-
Required. The name/identifier that labels a 'Block' element. The 'Goto' and 'Gosub' elements will jump to and execute the InboundXML for this label.
Nesting
The 'Block' can contain nested elements but must be nested in the default 'Response' element. This element can only be executed by the 'Goto' and 'Gosub' elements.
Example InboundXML Document (note, this sample contains a 'Goto' tag.)
<Response>
<Goto label="Here"></Goto>
<Block label="Here">
<Say>Lets go to there</Say>
<Goto label="There"></Goto>
</Block>
<Block label="There">
<Say>Whoopee, we are now Here. Sorry, I mean There.</Say>
</Block>
</Response>
10. Goto
The 'Goto' element provides the means to create more complex workflows and create reusable chunks of InboundXML. Use this element to trigger jumps in execution of InboundXML.
Element Attributes
-
label
-
Required. The name/identifier set here is the location that InboundXML will execute.
- Valid values: a string value
-
Required. The name/identifier set here is the location that InboundXML will execute.
Nesting
The 'Goto' can contain nested elements but must be placed inside the default 'Response' element.
Example InboundXML Document
<Response><!-- other tags hidden for brevity -->
<Goto label="AnswerBlock"></Goto><!-- other tags hidden for brevity
<Block label="AnswerBlock">
<Say>Press 1 for billing. Press 2 for customer service.</Block>
</Response>
11. Gosub
The 'Gosub' element provides for creating complex workflows similar to 'Goto' but the execution will return to previous execution block after being called.
Element Attributes
-
label
-
Required. The name/identifier set here is the location that InboundXML will execute.
- This element is similar to 'Goto' except that execution returns back to original position after executing. The 'hangup' attribute is not applicable here.
- Valid values: a string value
-
Required. The name/identifier set here is the location that InboundXML will execute.
Nesting
The 'Gosub' can contain nested elements but must be placed inside the default 'Response' element.
Example InboundXML Document
<Response>
<Gosub label="FirstBlock" />
<Block label="FirstBlock">
<Say>This is spoken first.</Say>
<Gosub label="SayThis" />
<Say>This is spoken after the Gosub element.</Say>
</Block>
<Gosub label="SayThis" />
<!-- other tags hidden for brevity -->
<Block label="SayThis">
<Say>Press 1 for billing. Press 2 for customer service.</Say>
</Block>
<Say>This statement will never be spoken.</Say>
</Response>
Example InboundXML Document - Block with Goto and Gosub
The following code sample contains all three elements to demonstrate how they can be put together.
<Response>
<Goto label="M360Test_1" />
<Say>This text will never execute.</Say>
<Block label="M360Test_1">
<Say>Hello. This is First block.</Say>
<Gosub label="M360Test_2" />
</Block>
<Block label="M360Test_2">
<Say>Hello. This is Second block.</Say>
<Gosub label="M360Test_3" />
<Say>This is spoken after gosub.</Say>
</Block>
<Goto label="M360Test_2" />
<Block label="M360Test_3">
<Say>Hello. This is Third block.</Say>
</Block>
<Say>This text will never execute.</Say>
</Response>
12. Hangup
The 'Hangup' element will end the current call.
Element Attributes
-
schedule
-
Optional. Specifies in seconds when the hangup should occur during a call.
- Valid values: integer greater than or equal to 1
-
Optional. Specifies in seconds when the hangup should occur during a call.
Nesting
The 'Hangup' element cannot be nested within any other elements besides the default 'Response' element.
No other elements may be nested within the 'Hangup' element.
Example InboundXML Document
<Response>
<Say>This will be spoken followed by hanging up.</Say>
<Hangup></Hangup>
</Response>
13. Redirect
The 'Redirect' element directs the call to another InboundXML document. The URL of the InboundXML document is nested within the 'Redirect' element, and the method attribute sets if the request will be a GET or a POST. In addition to the default voice request parameters, the parameter urlBase will also be forwarded when the redirect request is made. urlBase points to the base InboundXML document where the 'Response' occurred.
Element Attributes
-
method
-
Optional. Method used to request the InboundXML document when the call is being redirected.
- Valid values: POST, GET
- Default value: POST
-
Optional. Method used to request the InboundXML document when the call is being redirected.
Nesting
The 'Redirect' element cannot be nested within any other elements besides the default 'Response' element.
Example InboundXML Document
<Response>
<Say>You will now be redirected</Say>
<Redirect method="POST">http://yourdomain.com/rest.xml</Redirect>
<Say>You will never hear this.</Say>
</Response>
14. Reject
The 'Redirect' element will reject an incoming call. The reason attribute determines if the caller hears a busy signal or a not-in-service message.
Element Attributes
-
reason
-
Optional. The reason to list when the call is rejected.
- Valid values: REJECTED, BUSY
- Default value: REJECTED
-
Optional. The reason to list when the call is rejected.
Nesting
The 'Reject' element cannot be nested within any other elements besides the default 'Response' element.
Example InboundXML Document
<Response>
<Reject reason="BUSY"></Reject>
</Response>
15. Pause
The 'Pause' element will pause the call, holding for the number of milliseconds set by the length attribute.
Element Attributes
-
length
-
Optional. The length of the pause in milliseconds.
- Valid values: integer greater than 1
- Default value: 1
-
Optional. The length of the pause in milliseconds.
Nesting
In addition to the default 'Response' element, the 'Pause' element can also be nested within the 'Gather' verb.
No other elements may be nested within the 'Pause' element.
Example InboundXML Document
<Response>
<Pause length="8"></Pause>>
</Response>
InboundXML Text Elements
The following section defines the InboundXML elements for Ytel API. Used together and nested, these elements define an InboundXML document.
1. SMS
Send an SMS message to a valid 10-digit Ytel API phone number.
Element Attributes
-
From
-
Optional. The SMS-enabled Ytel API number, in e.164 format, from which the message is sent
- Default value: The Ytel API phone number, in e.164 format, to which SMS was received.
-
Optional. The SMS-enabled Ytel API number, in e.164 format, from which the message is sent
-
To
-
Optional. The SMS-enabled Ytel API number, in e.164 format, to which the message is received.
- Default value: The Ytel API phone number, in e.164 format, from which SMS was sent.
-
Optional. The SMS-enabled Ytel API number, in e.164 format, to which the message is received.
-
Body
- Optional. The body message that is to be sent in the text.
-
Method
-
Optional. Specifies the HTTP method used to request the required URL once SMS message is sent.
- Valid values: POST, GET
- Default value: POST
-
Optional. Specifies the HTTP method used to request the required URL once SMS message is sent.
-
StatusCallBack
- Optional. URL that can be requested to receive notification when SMS message was sent.
Example InboundXML Document
<Response>
<Message>
<Sms From="+1949XXXXXXX" To="+1949XXXXXX" Method="POST" StatusCallback="https://yourdomain.com/user body="This is a Test"></Sms>
</Message>
</Response>