Chapter 3. RestComm Markup Language

The RestComm Markup Language (RCML) is composed of a set of XML tags that can be used to instruct RestComm on how to handle an on-going phone call. RestComm applications are built by combining these XML verbs and nouns in a way that is sensible for a given set of application requirements. In this chapter we will discuss what a request from RestComm to your application looks like as well as what the response from your application should look like. Then, we will dive in to how each verb and noun in the XML instruction set is used.

3.1. RestComm Request

How RestComm Passes Data to Your Application. The way RestComm passes data to you application depends on the request method for the given URI. If the request method is GET then the data is passed in the query string or the part after the question mark. If the request method is POST then the data is sent a multi-part form data just like when a browser submits a form.

RestComm Voice Request. Any time RestComm makes a request to you applications it will include the following data as request parameters.

Table 3.1. Request Parameters

Parameter	Description
CallSid	The unique identifier for this call.
AccountSid	Your account id.
From	The phone number of the originator of the call.
To	The phone number of the call recipient.
CallStatus	The status of the call. The possible values are queued, ringing, in-progress, completed, busy, failed, and no-answer.
ApiVersion	The version of the RestComm API used to handle this call.
Direction	The direction of the call. The possible values are inbound and outbound-dial.
CallerName	The caller ID for the caller in the case of inbound calls.

3.2. Your Response

In your response to the request from RestComm you want to provide RCML that will instruct RestComm on how to handle the current call.

MIME Types. RestComm supports the MIME types described in the table below.

Table 3.2. Supported MIME Types

Parameter	Description
text/xml, application/xml	RestComm interprets the returned document as an XML instruction set.

Note

When your application returns the RCML document the root element of the document must always be <Response> or the parser will complain.

3.3. Say

The <Say> verb is used to synthesize text to speech and play it to the remote party. The voices supported depends on the TTS Service provider plug-in. Below are the voices for our default TTS service provider plug-in which uses Acapela Voice and VoiceRSS (default) as a Service.

Table 3.3. Say Attributes

Name	Allowed Values	Default Value
voice	man, woman	man
language	bf, bp, en, en-gb,cf, cs, dan, fi es, fr, de, el, it, nl, no, pl, pt, ru, ar, ca, sv, tr	en
loop	integer > 1	1

voice. The 'voice' attribute allows you to select the gender of the voice used to synthesize the text to speech for playback.

language. The 'language' attribute allows you pick a specific language for speech synthesis. RestComm currently supports languages 'bf' (Belgium-French), 'bp' (Brazilian-Portugues), 'en' (English), 'en-gb' (British-English), 'cf' (Canadian-French), 'cs' (Czech), 'dan' (Dannish), 'fi' (Finnish), 'es' (Spanish), 'fr' (French), 'de' (German), 'el' (Greek), 'it' (Italian), 'nl' (Netherlands-Dutch), 'no' (Norwegian), 'pl' (Polish), 'pt' (Portuguese), 'ru' (Russian), 'ar' (Saudi-Arabia Arabic), 'ca' (Spain Catalan), 'sv' (Swedish), and 'tr' (Turkish).

loop. The 'loop' attribute specifies how many times you'd like the text repeated. Specifying '0' will cause the the <Say> verb to loop until the call is hung up.

Nesting. The <Say> verb can not have any other verbs or nouns nested. Only text.

Examples. For an example of how to use the <Say> verb see below.

		<Response>
			<Say>Hello World</Say>
		</Response>

The example below shows how you can set the language, voice and loop parameters of the Say Verb.

	
		<Response>
		<Say voice="woman" language="fr" loop="3">Bienvenue à RestComm un projet parrainé par TeleStax</Say>
		</Response>

Usefull Information

When translating text to speech, the Say verb will make assumptions about how to pronounce numbers, dates, times, amounts of money and other abbreviations.
When saying numbers, '12345' will be spoken as "twelve thousand three hundred forty-five." Whereas '1 2 3 4 5' will be spoken as "one two three four five."

3.4. Play

The <Play> verb is used to play an audio file to the remote party.

Table 3.4. Play Attributes

Name	Allowed Values	Default Value
loop	integer > 1	1

loop. The 'loop' attribute specifies how many times you'd like the audio file to be repeated. Specifying '0' will cause the the <Play> verb to loop until the call is hung up.

Table 3.5. Supported Audio Formats

MIME type	Description
audio/wav	wav format audio
audio/wave	wav format audio
audio/x-wav	wav format audio

Media Server Audio File Format

The recommended audio file format is linear( 8000,16 bit , Mono ).

Nesting. The <Play> verb can not have any other verbs or nouns nested. Only a URL.

Basic example. For an example of how to use the <Play> verb see below.

		<Response>
			<Play>http://foobar.com/demo.wav</Play>
		</Response>

3.5. Gather

The <Gather> verb "gathers" digits that a caller enters into his or her telephone keypad. When the caller is done entering digits, RestComm submits that digits to the provided 'action' URL in an HTTP GET or POST request. If no input is received before timeout, <Gather> falls through to the next verb in the RestComm document. You may optionally nest <Say>, <Play>, and <Pause> verbs within a <Gather> verb while waiting for input. This allows you to read menu options to the caller while letting her enter a menu selection at any time. After the first digit is received the audio will stop playing.

Table 3.6. Gather Attributes

Name	Allowed Values	Default Value
action	relative or absolute URL	current document URL
method	GET, POST	POST
timeout	positive integer	5 seconds
finishOnKey	any digit, #, *	#
numDigits	integer >= 1	unlimited

action. The 'action' attribute takes an absolute or relative URL as a value. When the caller has finished entering digits RestComm will make a GET or POST request to this URL including the parameters below. If no 'action' is provided, RestComm will by default make a POST request to the current document's URL.

Table 3.7. Request Parameters

Parameter	Description
Digits	The digits the caller pressed, excluding the finishOnKey digit.

method. The 'method' attribute takes the value 'GET' or 'POST'. This tells RestComm whether to request the 'action' URL via HTTP GET or POST.

timeout. The 'timeout' attribute sets the limit in seconds that RestComm will wait for the caller to press another digit before moving on and making a request to the 'action' URL. For example, if 'timeout' is '10', RestComm will wait ten seconds for the caller to press another key before submitting the previously entered digits to the 'action' URL. RestComm waits until completing the execution of all nested verbs before beginning the timeout period.

finishOnKey. The 'finishOnKey' attribute lets you choose one value that submits the received data when entered. For example, if you set 'finishOnKey' to '#' and the user enters '1234#', RestComm will immediately stop waiting for more input when the '#' is received and will submit "Digits=1234" to the 'action' URL. Note that the 'finishOnKey' value is not sent. The allowed values are the digits 0-9, '#' , '*' and the empty string (set 'finishOnKey' to ''). If the empty string is used, <Gather> captures all input and no key will end the <Gather> when pressed. In this case RestComm will submit the entered digits to the 'action' URL only after the timeout has been reached. The value can only be a single character.

numDigits. The 'numDigits' attribute lets you set the number of digits you are expecting, and submits the data to the 'action' URL once the caller enters that number of digits.

Nesting. You can nest the following verbs within <Gather>: <Say>, <Play>, <Pause>

Examples. For an example of how to use the <Gather> verb see below.

			<Response>
				<Gather action="handle-user-input.php" numDigits="1">
					<Say>Welcome to TPS.</Say>
					<Say>For store hours, press 1.</Say>
					<Say>To speak to an agent, press 2.</Say>
					<Say>To check your package status, press 3.</Say>
				</Gather>
				<!-- If customer doesn't input anything, prompt and try again. -->
				<Say>Sorry, I didn't get your response.</Say>
				<Redirect>handle-incoming-call.xml</Redirect>
			</Response>

3.6. Record

The <Record> verb records the caller's voice and returns to you the URL of a file containing the audio recording.

Table 3.8. Record Attributes

Name	Allowed Values	Default Value
action	relative or absolute URL	current document URL
method	GET, POST	POST
timeout	positive integer	5
finishOnKey	any digit, #, *	1234567890*#
maxLength	integer greater than 1 with the number of seconds to wait	3600 (1 hour)
transcribe	true, false	false
transcribeCallback	relative or absolute URL	none
playBeep	true, false	true

action. The 'action' attribute takes an absolute or relative URL as a value. When recording is finished RestComm will make a GET or POST request to this URL including the parameters below. If no 'action' is provided, <Record> will default to requesting the current document's URL. After making this request, RestComm will continue the current call using the RCML received in your response. Any RCML verbs occuring after a <Record> are unreachable. There is one exception: if RestComm receives an empty recording, it will not make a request to the 'action' URL. The current call flow will continue with the next verb in the current RCML document.

Table 3.9. Request Parameters

Parameter	Description
RecordingUrl	The URL of the recorded audio.
RecordingDuration	The time duration of the recorded audio.
Digits	The digits the caller pressed, excluding the finishOnKey digit.

method. The 'method' attribute takes the value 'GET' or 'POST'. This tells RestComm whether to request the URL via HTTP GET or POST.

timeout. The 'timeout' attribute tells RestComm to end the recording after a number of seconds of silence has passed.

finishOnKey. The 'finishOnKey' attribute lets you choose a set of digits that end the recording when entered. For example, if you set 'finishOnKey' to '#' and the caller presses '#', RestComm will immediately stop recording and submit 'RecordingUrl', 'RecordingDuration', and the '#' as parameters in a request to the 'action' URL. The allowed values are the digits 0-9, '#' and '*'. Unlike <Gather>, you may specify more than one character as a 'finishOnKey' value.

maxLength. The 'maxLength' attribute lets you set the maximum length for the recording in seconds.

transcribe. The 'transcribe' attribute tells RestComm that you would like a text representation of the audio of the recording.

transcribeCallback. The 'transcribeCallback' attribute is used in conjunction with the 'transcribe' attribute. It allows you to specify a URL to which RestComm will make an asynchronous POST request when the transcription is complete. This is not a request for RCML and the response will not change call flow, but the request will contain the standard RCML request parameters as well as 'TranscriptionStatus', 'TranscriptionText', 'TranscriptionUrl' and 'RecordingUrl'. If 'transcribeCallback' is specified, then there is no need to specify 'transcribe=true'. It is implied. If you specify 'transcribe=true' without a 'transcribeCallback', the completed transcription will be stored for you to retrieve later (see the REST API Transcriptions section), but RestComm will not asynchronously notify your application.

Table 3.10. Request Parameters

Parameter	Description
TranscriptionText	Contains the text of the transcription.
TranscriptionStatus	The status of the transcription attempt: either 'completed' or 'failed'.
TranscriptionUrl	The URL for the transcription's REST API resource.
RecordingUrl	The URL for the transcription's source recording resource.

playBeep. The 'playBeep' attribute allows you to toggle between playing a sound before the start of a recording.

Nesting. The <Record> verb can not have any other verbs or nouns nested.

Examples. For an example of how to use the <Record> verb see below.

		<Response>
			<Record maxLength="30"/>
		</Response>

3.7. Fax

The <Fax> verb sends a fax to some a fax machine.

Table 3.11. Fax Attributes

Name	Allowed Values	Default Value
to	phone number	see below
from	phone number	see below
action	relative or absolute URL	none
method	GET, POST	POST
statusCallback	relative or absolute URL	none

to. The 'to' attribute takes a valid E.164 phone number as a value. RestComm will send a fax to this number. When sending a fax during an incoming call, 'to' defaults to the caller. When sending an fax during an outgoing call, 'to' defaults to the called party. The value of 'to' must be a valid phone number.

from. The 'from' attribute takes a valid E.164 phone number as an argument. When sending a fax during an incoming call, 'from' defaults to the calling party. When sending a fax during an outgoing call, 'from' defaults to the called party. The value of 'from' must be a valid phone number.

action. The 'action' attribute takes a URL as an argument. After processing the <Fax> verb, RestComm will make a GET or POST request to this URL with the form parameters 'FaxStatus' and 'FaxSid'. Using an 'action' URL, your application can receive synchronous notification that the message was successfully enqueued. If you provide an 'action' URL, RestComm will use the RCML received in your response to the 'action' URL request to continue the current call. Any RCML verbs occuring after a <Fax> which specifies an 'action' attribute are unreachable. If no 'action' is provided, <Fax> will finish and RestComm will move on to the next RCML verb in the document. If there is no next verb, RestComm will end the phone call.

Table 3.12. Request Parameters

Parameter	Description
FaxSid	The Sid for the Sms message.
FaxStatus	The current status of the Sms message. Either 'sent' or 'failed'.

method. The 'method' attribute takes the value 'GET' or 'POST'. This tells RestComm whether to request the 'action' URL via HTTP GET or POST. This attribute is modeled after the HTML form 'method' attribute.

statusCallback. The 'statusCallback' attribute takes a URL as an argument. When the fax is actually sent, or if sending fails, RestComm will make an asynchronous POST request to this URL with the parameters 'FaxStatus' and 'FaxSid'. Note, 'statusCallback' always uses HTTP POST to request the given url.

Table 3.13. Request Parameters

Parameter	Description
FaxSid	The Sid for the fax message.
FaxStatus	The current status of the fax. Either 'sent' or 'failed'.

Nesting. The <Fax> verb can not have any other verbs or nouns nested.

Examples. For an example of how to use the <Fax> verb see below.

		<Response>
			<Fax>This is a test fax.</Fax>
		</Response>

3.8. Sms

The <Sms> verb sends an SMS message to a phone number during a phone call.

Table 3.14. Sms Attributes

Name	Allowed Values	Default Value
to	phone number	see below
from	phone number	see below
action	relative or absolute URL	none
method	GET, POST	POST
statusCallback	relative or absolute URL	none

to. The 'to' attribute takes a valid E.164 phone number as a value. RestComm will send an SMS message to this number. When sending an SMS during an incoming call, 'to' defaults to the caller. When sending an SMS during an outgoing call, 'to' defaults to the called party. The value of 'to' must be a valid phone number.

from. The 'from' attribute takes a valid E.164 phone number as an argument. When sending an SMS during an incoming call, 'from' defaults to the calling party. When sending an SMS during an outgoing call, 'from' defaults to the called party.

action. The 'action' attribute takes a URL as an argument. After processing the <Sms> verb, RestComm will make a GET or POST request to this URL with the form parameters 'SmsStatus' and 'SmsSid'. Using an 'action' URL, your application can receive synchronous notification that the message was successfully enqueued. If you provide an 'action' URL, RestComm will use the RCML received in your response to the 'action' URL request to continue the current call. Any RCML verbs occuring after an <Sms> which specifies an 'action' attribute are unreachable. If no 'action' is provided, <Sms> will finish and RestComm will move on to the next RCML verb in the document. If there is no next verb, RestComm will end the phone call.

statusCallback. The 'statusCallback' attribute takes a URL as an argument. When the SMS message is actually sent, or if sending fails, RestComm will make an asynchronous POST request to this URL with the parameters 'SmsStatus' and 'SmsSid'. Note, 'statusCallback' always uses HTTP POST to request the given url.

Table 3.15. Request Parameters

Parameter	Description
SmsSid	The Sid for the Sms message.
SmsStatus	The current status of the Sms message. Either 'sent' or 'failed'.

Nesting. The <Sms> verb can not have any other verbs or nouns nested.

Examples. For an example of how to use the <Sms> verb see below.

		<Response>
			<Sms>Hello World!</Sms>
		</Response>

Sms Custom headers

Restcomm will check for any custom headers and make use of them.

In case of an incoming SMS (incoming SIP MESSAGE) Restcomm will scan the message for any headers starting with X- and if any found will be send to the application server with the request (part of the query string in the case of HTTP GET or part of the message body in the case of HTTP POST)

The application server can also provide some custom http headers (again starting with X-) along with the RCML response, that Restcomm will store and use them when creating the outgoing SMS message (in the case of RCML response is Sms).

3.9. Dial

The <Dial> verb connects the current caller to another phone. If the called party picks up, the two parties are connected and can communicate until one hangs up. If the called party does not pick up, if a busy signal is received, or if the number doesn't exist, the dial verb will finish.

Table 3.16. Dial Attributes

Name	Allowed Values	Default Value
action	relative or absolute URL	no default for <Dial>
method	GET, POST	POST
timeout	positive integer in seconds	30 seconds
timeLimit	positive integer (seconds)	14400 seconds (4 hours)
callerId	a valid phone number, or client identifier if you are dialing a <Client>.	Caller's callerId
record	true, false	false

action. The 'action' attribute takes a URL as an argument. When the dialed call ends, RestComm will make a GET or POST request to this URL including the parameters below. If you provide an 'action' URL, RestComm will continue the current call after the dialed party has hung up, using the RCML received in your response to the 'action' URL request. Any RCML verbs occuring after a <Dial> which specifies an 'action' attribute are unreachable. If no 'action' is provided, <Dial> will finish and RestComm will move on to the next RCML verb in the document. If there is no next verb, RestComm will end the phone call.

Table 3.17. Request Parameters

Parameter	Description
DialCallStatus	The outcome of the <Dial> attempt. See the DialCallStatus section below for details.
DialCallSid	The call sid of the new call leg. This parameter is not sent after dialing a conference.
DialCallDuration	The duration in seconds of the dialed call. This parameter is not sent after dialing a conference.
RecordingUrl	The URL of the recorded audio. This parameter is only sent if record="true" is set on the `Dial` verb, and does not include recordings from the `Record` verb or Record=True on REST API calls..

Table 3.18. DialCallStatus Values

Parameter	Description
completed	The called party answered the call and was connected to the caller.
busy	RestComm received a busy signal when trying to connect to the called party.
no-answer	The called party did not pick up before the timeout period passed.
failed	RestComm was unable to route to the given phone number. This is frequently caused by dialing a properly formated but non-existent phone number.
canceled	The call was canceled via the REST API before it was answered.

timeout. The 'timeout' attribute sets the limit in seconds that <Dial> waits for the called party to answer the call.

timelimit. The 'timeLimit' attribute sets the maximum duration of the <Dial> in seconds.

callerId. The 'callerId' attribute lets you specify the caller ID that will appear to the called party when RestComm calls. By default, when you put a <Dial> in your RCML response to RestComm's inbound call request, the caller ID that the dialed party sees is the inbound caller's caller ID. If you are dialing to a <Client>, you can set a client identifier as the callerId attribute. For instance, if you've set up a client for incoming calls and you are dialing to it, you could set the callerId attribute to client:thomas.

record. The 'record' attribute lets you specify whether the call will be recorded or not. By default, the call is not recorded. If you set the attribute to 'true' Restcomm will start recording when the two calls are bridged

Record attribute for Dial Conference

The current release of Restcomm doesn't support recording for Dial Conference. This feature will be available in the next release

Nesting. You can nest the following nouns within <Dial>: <Number>, <Client>, <Conference>

Examples. For examples of how to use the <Dial> verb see below.

		<Response>
			<Dial>1-444-555-666</Dial>
		</Response>

		<Response>
			<Dial record="true">1-444-555-666</Dial>
		</Response>

		<Response>
			<Dial callerId="1555666777" record="true">1-444-555-666</Dial>
		</Response>

3.9.1. Number

The <Number> noun specifies a phone number to dial. You can use multiple <Number> nouns within a <Dial> verb to simultaneously call all of them at once. The first call to pick up is connected to the current call and the rest are hung up.

Table 3.19. Number Attributes

Name	Allowed Values	Default Value
sendDigits	any digits	none
url	any url	none

sendDigits. The 'sendDigits' attribute tells RestComm to play DTMF tones when the call is answered. This is useful when dialing a phone number and an extension. RestComm will dial the number, and when the automated system picks up, send the DTMF tones to connect to the extension.

url. The 'url' attribute allows you to specify a url for a RCML document that will run on the called party's end, after he/she answers, but before the parties are connected. You can use this RCML to privately play or say information to the called party, or provide a chance to decline the phone call using <Gather> and <Hangup>. The current caller will continue to hear ringing while the RCML document executes on the other end. RCML documents executed in this manner are not allowed to contain the <Dial> verb.

Examples. For an example of how to use the <Number> noun see below.

		<Response>
			<Dial>
				<Number sendDigits="wwww1234">1-444-555-6666</Number>
			</Dial>
		</Response>

3.9.2. Client

The <Client> noun specifies a client identifier to dial. You can use multiple <Client> nouns within a <Dial> verb to simultaneously attempt a connection with many clients at once. The first client to accept the incoming connection is connected to the call and the other connection attempts are canceled.

Examples. For an example of how to use the <Client> none see below.

			<Response>
				<Dial>
					<Client>thomas</Client>
				</Dial>
			</Response>

3.9.3. Conference

The <Conference> noun allows you to connect to a named conference room and talk with the other callers who have also connected to that room. The name of the room is up to you and is namespaced to your account.

Table 3.20. Conference Attributes

Name	Allowed Values	Default Value
muted	true, false	false
beep	true, false	true
startConferenceOnEnter	true, false	true
endConferenceOnExit	true, false	false
waitUrl	RCML url, empty string	default RestComm hold music
waitMethod	GET or POST	POST
maxParticipants	positive integer <= 40	40

muted. The 'muted' attribute lets you specify whether a participant can speak in the conference. If this attribute is set to 'true', the participant will only be able to listen to people in the conference.

beep. The 'beep' attribute lets you specify whether a notification beep is played to the conference when a participant joins or leaves the conference.

startConferenceOnEnter. This attribute tells a conference to start when this participant joins the conference, if it is not already started. If this is false and the participant joins a conference that has not started, they are muted and hear background music until a participant joins where startConferenceOnEnter is true. This is useful for implementing moderated conferences.

endConferenceOnExit. If a participant has this attribute set to 'true', then when that participant leaves, the conference ends and all other participants drop out. This is useful for implementing moderated conferences that bridge two calls and allow either call leg to continue executing RCML if the other hangs up.

waitUrl. The 'waitUrl' attribute lets you specify a URL for music that plays before the conference has started. The URL may be a WAV or a RCML document that uses <Play> or <Say> for content. This defaults to a selection of Creative Commons licensed background music, but you can replace it with your own music and messages. If the 'waitUrl' responds with RCML, RestComm will only process <Play>, <Say>, and <Redirect> verbs. If you do not wish anything to play while waiting for the conference to start, specify the empty string (set 'waitUrl' to '').

waitMethod. This attribute indicates which HTTP method to use when requesting 'waitUrl'. It defaults to 'POST'. Be sure to use 'GET' if you are directly requesting static audio files such as WAV files so that RestComm properly caches the files.

maxParticipants. This attribute indicates the maximum number of participants you want to allow within a named conference room. The default maximum number of participants is 40. The value must be a positive integer less than or equal to 100.

Examples. For an example of how to use the <Conference> noun see below.

			<Response>
				<Dial>
					<Conference>1234</Conference>
				</Dial>
			</Response>

Uri noun deprecated

The Uri noun has been deprecated and will no longer be available in future releases. Please use the SIP noun instead.

3.9.4. Sip

The <Sip> noun specifies a SIP URI to dial. You can use multiple <Sip> nouns within a <Dial> verb to simultaneously attempt a connection with many user agents at once. The first user agent to accept the incoming connection is connected to the call and the other connection attempts are canceled.

The Dial verb's Sip noun lets you set up VoIP sessions by using SIP -- Session Initiation Protocol. With this feature, you can send a call to any SIP endpoint. Set up your RCML to use the Sip noun within the Dial verb.

Currently, only one Sip noun may be specified per Dial, and the INVITE message may be sent to only one SIP endpoint. Also, you cannot add any other nouns (eg Number, Client) in the same Dial as the SIP. If you want to use another noun, set up a callback on the Dial to use alternate methods.

Examples. For an example of how to use the <Sip> noun see below.

			<Response>
				<Dial>
					<Sip>sip:alice@127.0.0.1:5080</Sip>
				</Dial>
			</Response>

Authentication .

Send username and password attributes for authentication to your SIP infrastructure as attributes on the Sip noun.

Table 3.21. Request Parameters

Attribute Name	Values
username	Username for SIP authentication.
password	Password for SIP authentication

Authentication Example .



<?xml version="1.0" encoding="UTF-8"?>
<Response>
	<Dial>
		<Sip username="alice" password="secret">sip:alice@example.com</Sip>
	</Dial>
</Response>

Custom headers.

Send custom headers by appending them to the SIP URI -- just as you'd pass headers in a URI over HTTP. For example:



<?xml version="1.0" encoding="UTF-8"?>
<Response>
	<Dial>
		<Sip>
		sip:alice@example.com?mycustomheader=tata&myotherheader=toto
		</Sip>
	</Dial>
</Response>

Character Limit

While the SIP URI itself must be under 255 chars, the headers must be under 1024 characters.

Transport.

Set a parameter on your SIP URI to specify what transport protocol you want to use. Currently, this is limited to TCP and UDP. By default, Restcomm sends your SIP INVITE over UDP. Change this by using the transport parameter:



<?xml version="1.0" encoding="UTF-8"?>
<Response>
	<Dial>
		<Sip>
		sip:alice@example.com;transport=tcp
		</Sip>
	</Dial>
</Response>

Attributes.

Table 3.22. Request Parameters

Attribute Name	Allowed Values	Default Value
url	call screening url.	none.
method	GET, POST	POST

The url attribute allows you to specify a url for a RCML document that runs on the called party's end, after they answer, but before the two parties are connected. You can use this RCML to privately Play or Say information to the called party, or provide a chance to decline the phone call using Gather and Hangup. The current caller continues to hear ringing while the RCML document executes on the other end. RCML documents executed in this manner cannot contain the Dial verb.

method.

The method attribute allows you to specify which HTTP method Restcomm should use when requesting the URL specified in the url attribute. The default is POST.

Call Screening HTTP parameters.

When a call is answered, Restcomm passes the following parameters with its request to your screening URL (in addition to the standard RCML Voice request parameters):

Table 3.23. Request Parameters

Attribute Name	Values
SipCallId	The SIP call ID header of the request made to the remote SIP infrastructure.
SipHeader	The name/value of any X-headers returned in the 200 response to the SIP INVITE request.

Dial Action HTTP parameters.

Use the action callback parameters to modify your application based on the results of the SIP dial attempt:

Table 3.24. Request Parameters

Attribute Name	Values
DialSipCallId	The SIP call ID header of the request made to the remote SIP infrastructure.
DialSipResponseCode	The SIP response code as a result of the INVITE attempt.
DialSipHeader_	The name/value of any X-headers returned in the final response to the SIP INVITE request.

Dial with Multiple Examples.

A more complex Dial, specifying custom settings as attributes on Dial, including call screening and setting the protocol to TCP.



<?xml version="1.0" encoding="UTF-8"?>
<Response>
	<Dial
		record="true"
		timeout="10"
		hangupOnStar="true"
		callerId="bob"
		method="POST"
		action="/handle_post_dial">
	<Sip
		method="POST"
		url="/handle_screening_on_answer">
		sip:alice@example.com?customheader=foo
	</Sip>
	</Dial>
</Response>

3.10. Hangup

The <Hangup> verb ends a call.

Nesting. The <Hangup> verb can not have any other verbs or nouns nested.

Examples. For an example of how to use the <Hangup> verb see below.

		<Response>
			<Hangup/>
		</Response>

3.11. Redirect

The <Redirect> verb transfers control of a call to the RCML at a different URL. All verbs after <Redirect> are unreachable and ignored.

Table 3.25. Redirect Attributes

Name	Allowed Values	Default Value
method	GET, POST	POST

method. The 'method' attribute takes the value 'GET' or 'POST'. This tells RestComm whether to request the URL via HTTP GET or POST.

Nesting. The <Redirect> verb can not have any other verbs or nouns nested.

Examples. For an example of how to use the <Redirect> verb see below.

		<Response>
			<Redirect>http://foobar.com/instructions</Redirect>
		</Response>

3.12. Reject

The <Reject> verb rejects an incoming call to your RestComm endpoint. This is useful for blocking unwanted calls. If the first verb in a RCML response is <Reject>, RestComm will not pick up the call. The call ends with a status of 'busy' or 'no-answer', depending on the verb's 'reason' attribute. Any verbs after <Reject> are unreachable and ignored.

Table 3.26. Reject Attributes

Name	Allowed Values	Default Value
reason	rejected, busy	rejected

reason. The reason attribute takes the values "rejected" and "busy." This tells RestComm what message to play when rejecting a call. Selecting "busy" will play a busy signal to the caller, while selecting "rejected" will play a standard not-in-service response.

Nesting. The <Reject> verb can not have any other verbs or nouns nested.

Examples. For an example of how to use the <Reject> verb see below.

		<Response>
			<Reject reason="busy"/>
		</Response>

3.13. Pause

The <Pause> verb waits silently for a specific number of seconds. If <Pause> is the first verb in a RCML response, RestComm will wait the specified number of seconds before picking up the call.

Table 3.27. Pause Attributes

Name	Allowed Values	Default Value
length	integer > 0	1 second

length. The 'length' attribute specifies how many seconds RestComm will wait silently before continuing on.

Nesting. The <Pause> verb can not have any other verbs or nouns nested.

Examples. For an example of how to use the <Pause> verb see below.

		<Response>
			<Pause length="5"/>
		</Response>

3.14. UssdCollect

The UssdCollect verb is a USSD integration with Restcomm resource. When fully configured with a USSD gateway, Restcomm will send all UssdMessage to the configured gateway

Example. For an example of how to use the USSDCollect verb see below.

	
	<Response>
		<UssdCollect action="http://my.controller.net">
			<UssdMessage> 1 for first option</UssdMessage>
			<UssdMessage> 2 for first option</UssdMessage>
			<UssdMessage> 3 for first option</UssdMessage>
		</UssdCollect>
	</Response>

3.14.1. UssdMessage

Note

Before you can send an USSD message you must first configure the restcomm.xml with the USSD gateway information. See Section 4.13, “UssdPush” for more information.

The UssdMessage verb contains the message that Restcomm will send to the USSD gateway

Nesting. The UssdMessage can be nested inside of the USSDCollect verb.

Examples. For an example of how to use the USSDCollect verb see below.

	
	<Response>
		<UssdMessage>Test USSD Message</UssdMessage></UssdCollect>
	</Response>

3.14.2. Language

The language noun let you specify the language of the USSD message that is sent to the USSD gateway

Table 3.28. Language Attributes

Name	Allowed Values	Default Value
Language	bf, bp, en, en-gb,cf, cs, dan, fi es, fr, de, el, it, nl, no, pl, pt, ru, ar, ca, sv, th, tr	en

Nesting. The Language noun cannot be nested. If not specified, English language is default

Example. For an example of how to use the USSD Language noun see below.

	
	<Response>
		<Language>fr</Language>
		<UssdMessage>Test USSD Message</UssdMessage></UssdCollect>
	</Response>