Overview #

CUTI is a telephony interface that allows a client to manage calls using a Connection server. A second part of the CUTI interface allows an established call to play and record audio content over the phone.

Basic call operations #

The basic call operations are: Make a call, check call connected status and hangup. The Call object is used to convey information about a call (see API XSD's). When making a call, the fields used are:

• number - the only field that does not have a default value. User's with the system administrator role can call any number, but end users can only call numbers that don't violate their associated call restriction table based on their class of service
• maximumRings - defaults to 4.
• mediaSwitchObjectId - for end users defaults to the phone system associated with the user. For users that do not have an associated phone system (e.g. administrators), the phone system marked as the default TRAP phone system is used.

Once a call has been placed, a client can get server information about the call, most importantly the connected status.

HTTP commands for basic call operations #

POST http://<server>/calls: Create a call (i.e. make a phone call) using the information in a Call object, returns a URI for the new call

GET http://<server>/calls/<call id>: Get basic call information, returns a Call object

DELETE http://<server>/calls/<call id>: Hang up a call

Play and Record using a Call: #

Files on the server can be played and recorded over the phone using the call control operations using the CallControl object (see API XSD's). The fields of the CallControl object are described below:

• opType: PLAY, RECORD or STOP
• resourceType - MESSAGE, BROADCASTMESSAGE or STREAM. STREAM is generally a temporary resource created by a record operation.
• resourceID - can be a message identifier, a broadcast message identifier or a stream identifier depending on the resource type.
• Speed, volume and startPosition are all optional parameters. Speed and Volume are a percentage and default to 100. The start position indicates a time in milliseconds and defaults to 0.
• lastResult - the result of the last call control operation
• folderType - reserved, right now only messages in the inbox can be played.

A call control object is passed to a call using a POST to the call's resource URI:

POST http://<server>/vmrest/calls/<call id>

Example #

This example shows how to: Call a phone, check call status, record over the phone, play back the recording, hangup and send the recording as a message. Each step is shown as the HTTP request and response.

Make the call #

POST /vmrest/calls HTTP/1.1 Content-Type: application/json Accept: application/json User-Agent: Java/1.6.0_17 Host: cuc-install-67.cisco.com Connection: keep-alive Authorization: Basic Y2NtYWRtaW5pc3RyYXRvcjplY3NidWxhYg== Content-Length: 36

{"number":"2119","maximumRings":"4"}

Response

HTTP/1.1 201 Created
Set-Cookie: JSESSIONIDSSO=CB2BE1D9771621DBEA24B479C1A9C10A; Path=/
Set-Cookie: JSESSIONID=EB7C33B4DC0AAE91CB002D799C8734BA; Path=/vmrest
Location: [http://cuc-install-67.cisco.com/vmrest/calls/vmrest/calls/1]
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 15 Jan 2010 15:14:11 GMT
Server:

Get the call information #

GET /vmrest/calls/1 HTTP/1.1 Accept: application/json User-Agent: Java/1.6.0_17 Host: cuc-install-67.cisco.com Connection: keep-alive Authorization: Basic Y2NtYWRtaW5pc3RyYXRvcjplY3NidWxhYg==

Response

HTTP/1.1 200 OK
Pragma: No-cache
Cache-Control: no-cache
Expires: Wed, 31 Dec 1969 16:00:00 PST
Set-Cookie: JSESSIONIDSSO=849167D3D61D2F30BA278BBF949FDF0F; Path=/
Set-Cookie: JSESSIONID=28A69142E490EC63A56690F9811BDDF9; Path=/vmrest
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 15 Jan 2010 15:14:11 GMT
Server: 

{"id":"1","connected":"true","nativeConnectionId":"2"}

Start a recording #

POST /vmrest/calls/1 HTTP/1.1
Content-Type: application/json
Accept: application/json
User-Agent: Java/1.6.0_17
Host: cuc-install-67.cisco.com
Connection: keep-alive
Authorization: Basic Y2NtYWRtaW5pc3RyYXRvcjplY3NidWxhYg==
Content-Length: 15

{"op":"RECORD"}

Response

HTTP/1.1 200 OK
Set-Cookie: JSESSIONIDSSO=8279B639488165EFFAC8D330FD2A1281; Path=/
Set-Cookie: JSESSIONID=AA008CFCC9B329EA961CD1E660384785; Path=/vmrest
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 15 Jan 2010 15:14:13 GMT
Server: 

{"op":"RECORD","resourceType":"STREAM","resourceId":"cf1cb014-6394-4279-ab5a-74a6d680e440.wav","lastResult":"0","speed":"100","volume":"100","startPosition":"0"}

Play the recording back#

POST /vmrest/calls/1 HTTP/1.1
Content-Type: application/json
Accept: application/json
User-Agent: Java/1.6.0_17
Host: cuc-install-67.cisco.com
Connection: keep-alive
Authorization: Basic Y2NtYWRtaW5pc3RyYXRvcjplY3NidWxhYg==
Content-Length: 159

{"op":"PLAY","resourceType":"STREAM","resourceId":"cf1cb014-6394-4279-ab5a-74a6d680e440.wav","lastResult":"0","speed":"100","volume":"100","startPosition":"0"}

Response

HTTP/1.1 200 OK
Set-Cookie: JSESSIONIDSSO=CD7B1064CEB9385B6FE9279ECBDB40E3; Path=/
Set-Cookie: JSESSIONID=201BD26E840AA2CEEC242A9CCD0FE8F6; Path=/vmrest
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 15 Jan 2010 15:14:15 GMT
Server: 

{"op":"PLAY","resourceType":"STREAM","resourceId":"cf1cb014-6394-4279-ab5a-74a6d680e440.wav","lastResult":"0","speed":"100","volume":"100","startPosition":"0"}

Hangup #

DELETE /vmrest/calls/1 HTTP/1.1
Content-Type: application/json
User-Agent: Java/1.6.0_17
Host: cuc-install-67.cisco.com
Accept: text/html, image/gif, image/jpeg, \*; q=.2, \*/*; q=.2
Connection: keep-alive
Authorization: Basic Y2NtYWRtaW5pc3RyYXRvcjplY3NidWxhYg==

Response

HTTP/1.1 204 No Content
Pragma: No-cache
Cache-Control: no-cache
Expires: Wed, 31 Dec 1969 16:00:00 PST
Set-Cookie: JSESSIONIDSSO=93B286C6584533F9EE793A01E5804465; Path=/
Set-Cookie: JSESSIONID=0CCFFFCAD1C11A45EAD1E8F04B22D28D; Path=/vmrest
Date: Fri, 15 Jan 2010 15:14:15 GMT
Server:

Send a message using the recording #

POST /vmrest/messages?userobjectid=84c14db9-7439-4326-a2e2-e516aa192dff HTTP/1.1
Content-Type: multipart/form-data;boundary=Boundary_1_16617866_1263568442453
Accept: application/json
User-Agent: Java/1.6.0_17
Host: cuc-install-67.cisco.com
Connection: keep-alive
Authorization: Basic Y2NtYWRtaW5pc3RyYXRvcjplY3NidWxhYg==
Content-Length: 731

\--Boundary_1_16617866_1263568442453
Content-Type: application/json
{"Subject":"send message test","ArrivalTime":"0","FromSub":"false"}
\--Boundary_1_16617866_1263568442453
Content-Type: application/json

{"Recipient":{"Type":"TO","Address":
{"UserGuid":"84c14db9-7439-4326-a2e2-e516aa192dff","DisplayName":"Operator"}--Boundary_1_16617866_1263568442453
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><CallControl><op>PLAY</op><resourceType>STREAM</resourceType><resourceId>cf1cb014-6394-4279-ab5a-74a6d680e440.wav</resourceId><lastResult>0</lastResult><speed>100</speed><volume>100</volume><startPosition>0</startPosition></CallControl>
\--Boundary_1_16617866_1263568442453-\-

Response

HTTP/1.1 202 Accepted
Set-Cookie: JSESSIONIDSSO=3D875CAE50B6B4947DEDCF5EDA119922; Path=/
Set-Cookie: JSESSIONID=842B1A6E53DAE329F6DA7525951668B4; Path=/vmrest
Content-Type: application/json
Content-Length: 0
Date: Fri, 15 Jan 2010 15:14:16 GMT
Server: