TelScale Restcomm Resource Security. The security model is based on role based access control. TelScale RestComm defines a set of permissions that can be defined for each role. There are two predefined roles Administrator and Developer. The Developer role can be configured or removed all together depending on your needs but the Administrator role can not be changed. The Administrator role can not be modified or removed and it has access to every resource.

First we will define the list of permissions and what they mean.

These permissions apply to every resource exposed by the Restful APIs. Once a role is defined it can be specified for new Account resources that are created.

Wildcard Permission. The asterisk '*' is a wildcard that means grant all permissions and can be used in place of typing out all the permissions.

To see how this all comes together please check out the restcomm.xml configuration file.

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>
		

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>
			

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>

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. 

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):

Dial Action HTTP parameters. 

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

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>

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>
	
		

Get information about the default account. 

curl -X GET  http://ACae6e420f425248d6a26948c17a9e2acf:77f8c12cc7b8f8423e5c38b035249166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf


			

Change default account password(AuthToken). 

curl -X PUT http://ACae6e420f425248d6a26948c17a9e2acf:77f8c12cc7b8f8423e5c38b035249166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf -d "Password=NewPassword"


			

curl -X GET  http://administrator%40company.com:77f8c12cc7b8f8423e5c38b035249166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf

			

The above commands will print an output similar to the one below:

<RestcommResponse>
  <Account>
    <Sid>ACae6e420f425248d6a26948c17a9e2acf</Sid>
    <FriendlyName>Default Administrator Account</FriendlyName>
    <Status>active</Status>
    <Type>Full</Type>
    <DateCreated>2012-04-24T00:00:00.000-06:00</DateCreated>
    <DateUpdated>2012-04-24T00:00:00.000-06:00</DateUpdated>
    <AuthToken>77f8c12cc7b8f8423e5c38b035249166</AuthToken>
    <Uri>/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf</Uri>
    <SubresourceUris>
      <AvailablePhoneNumbers>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/AvailablePhoneNumbers</AvailablePhoneNumbers>
      <Calls>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls</Calls>
      <Conferences>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Conferences</Conferences>
      <IncomingPhoneNumbers>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/IncomingPhoneNumbers</IncomingPhoneNumbers>
      <Notifications>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Notifications</Notifications>
      <OutgoingCallerIds>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/OutgoingCallerIds</OutgoingCallerIds>
      <Recordings>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Recordings</Recordings>
      <Sandbox>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Sandbox</Sandbox>
      <SMSMessages>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/SMS/Messages</SMSMessages>
      <Transcriptions>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Transcriptions</Transcriptions>
    </SubresourceUris>
  </Account>


			

HTTP DELETE. Deletes a Client from the user's Account.

HTTP DELETE. Releases an IncomingPhoneNumber from the user's Account.

Making a call to a SIP account. 

Restcomm will make a call to any SIP account that is reachable. It the example below, the SIP account is listening on port 5060. When you make the call, the SIP phone on which Alice is registered will ring and the hello-play.xml file will be played.

curl -X POST http://ACae6e420f425248d6a26948c17a9e2acf:77f8c12cc7b8f8423e5c38b035249166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls.json -d "From=+16175551212" -d "To=sip:alice@127.0.0.1:5060" -d "Url=http://127.0.0.1:8080/restcomm/demos/hello-play.xml"


			

Making a call to a Restcomm client. 

You must first create a RestComm client. In the example below, the Restcomm client created is called Alice. When you make the call, the SIP phone on which Alice is registered will ring and the hello-play.xml file will be played.

curl -X POST http://ACae6e420f425248d6a26948c17a9e2acf:77f8c12cc7b8f8423e5c38b035249166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls.json -d "From=+16175551212" -d "To=client:alice" -d "Url=http://127.0.0.1:8080/restcomm/demos/hello-play.xml"


			

Optional Parameters.  You may POST the following parameters:

Filter using the From parameter. The example below will only return Calls made from client Alice

 curl -X GET  http://administrator%40company.com:77f8c12cc7166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?From=alice

			

The result will be similar to the one below

<RestcommResponse>
  <Calls page="0" numpages="0" pagesize="50" total="0" start="0" end="1" uri="/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls" firstpageuri="/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?Page=0&amp;PageSize=50" previouspageuri="null" nextpageuri="null" lastpageuri=="/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?Page=0&amp;PageSize=50">
    <Call>
      <Sid>CAc0fb839632cf444f9066876d5de741e0</Sid>
      <DateCreated>2013-10-18T04:51:47.643-06:00</DateCreated>
      <DateUpdated>2013-10-18T04:51:49.174-06:00</DateUpdated>
      <ParentCallSid/>
      <AccountSid>ACae6e420f425248d6a26948c17a9e2acf</AccountSid>
      <To>1234</To>
      <From>alice</From>
      <PhoneNumberSid/>
      <Status>completed</Status>
      <StartTime>2013-10-18T04:51:47.671-06:00</StartTime>
      <EndTime>2013-10-18T04:51:49.174-06:00</EndTime>
      <Duration>1</Duration>
      <Price>0.00</Price>
      <Direction>inbound</Direction>
      <AnsweredBy/>
      <ApiVersion>2012-04-24</ApiVersion>
      <ForwardedFrom/>
      <CallerName/>
      <Uri>/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls/CAc0fb839632cf444f9066876d5de741e0</Uri>
      <SubresourceUris>
        <Notifications>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls/CAc0fb839632cf444f9066876d5de741e0/Notifications</Notifications>
        <Recordings>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls/CAc0fb839632cf444f9066876d5de741e0/Recordings</Recordings>
      </SubresourceUris>
    </Call>
  </Calls>


			

Example. The command below will return a single item from the list of calls using the PageSize parameter

curl -X GET  http://ACae6e420f425248d6a26948c17a9e2acf:77f8c12cc7b8f8423e5c38b035249166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?PageSize=1


			

The result of the PageSize parameter

<RestcommResponse>
  <Calls page="0" numpages="7" pagesize="1" total="7" start="0" end="0" uri="/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls" firstpageuri="/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?Page=0&amp;PageSize=1" previouspageuri="null" nextpageuri="/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?Page=1&amp;PageSize=1&amp;AfterSid=CA4049cf008d6b4277b92ab863fd4ec7c8" lastpageuri=="/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?Page=7&amp;PageSize=1">
    <Call>
      <Sid>CA4049cf008d6b4277b92ab863fd4ec7c8</Sid>
      <DateCreated>2013-10-18T04:49:45.942-06:00</DateCreated>
      <DateUpdated>2013-10-18T04:49:46.272-06:00</DateUpdated>
      <ParentCallSid/>
      <AccountSid>ACae6e420f425248d6a26948c17a9e2acf</AccountSid>
      <To>1235</To>
      <From>bob</From>
      <PhoneNumberSid/>
      <Status>completed</Status>
      <StartTime>2013-10-18T04:49:45.994-06:00</StartTime>
      <EndTime>2013-10-18T04:49:46.272-06:00</EndTime>
      <Duration>0</Duration>
      <Price>0.00</Price>
      <Direction>inbound</Direction>
      <AnsweredBy/>
      <ApiVersion>2012-04-24</ApiVersion>
      <ForwardedFrom/>
      <CallerName/>
      <Uri>/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls/CA4049cf008d6b4277b92ab863fd4ec7c8</Uri>
      <SubresourceUris>
        <Notifications>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls/CA4049cf008d6b4277b92ab863fd4ec7c8/Notifications</Notifications>
        <Recordings>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls/CA4049cf008d6b4277b92ab863fd4ec7c8/Recordings</Recordings>
      </SubresourceUris>
    </Call>
  </Calls>



			

Additional Paging Information. The API returns URIs to the next, previous, first and last pages of the returned list as shown in the table below: