Cisco Unity Connection Telephony Interface (CUTI) API -- Using CUTI for Basic Call Operations

From DocWiki

Revision as of 19:08, 14 December 2010

Links to Other API pages: Cisco_Unity_Connection_APIs

About Basic Call Operations

The basic call operations are making a call, checking call-connected status, and hanging up. The call object is used to convey information about a call (see API XSD's).

When making a call, the following fields are used:

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

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

The following are HTTP commands for basic call operations:

POST http://<server>/calls:
Create a call (make a phone call) by 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>: Hangs up a call.

Playing and Recording by Using a Call

Files on the server can be played and recorded by phone (using the call control operations) by 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. Only messages in the inbox can be played.

A call control object is passed to a call by using a POST to the resource URI of the call:

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

Examples

The examples below show how to: make a call, check call status, record by phone, play the recording, hang up, 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:

Check call status

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"}

Record by phone

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

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"}

Hang up

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 the recording as a message

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: