Cisco Unity Connection Provisioning Interface (CUPI) API -- Directory Handler Greeting APIs

From DocWiki

(Difference between revisions)
Jump to: navigation, search
(Listing Directory Handler Greeting)
m (1 revision)
 

Latest revision as of 09:54, 1 November 2013

Links to Other API pages: Cisco_Unity_Connection_APIs

CUPI Guide Contents
API Overview
Index of All CUPI Documentation


Contents


Directory Handler Greeting APIs

Administrator can use this API to create/update/fetch the Directory Handler Greeting.

There are three ways to upload the Custom Greeting for the Directory Handler :

1) Upload a .wav file from the desktop.

2) Record a recording using CUTI(Cisco Unity Telephony Interface) and upload to the Directory Handler.

3) Pass the .wav as an inputStream to the Directory Handler.Administrator can use this API to create/update/fetch the directory handler greeting. You can update various attributes of directory handler greeting using this API.


Enable Use of Custom Recordings on a Directory Handler

Custom Greetings can be enabled on a directory handler using the directory handler API. A PUT operation has to be performed to set the UseCustomGreetings field to True:

  PUT https://<connection-server>/vmrest/directoryhandlers/<DirectoryhandlerObjectId>
<DirectoryHandler>
    <UseCustomGreeting>true<UseCustomGreeting>
</DirectoryHandler>

The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:

Response Code: 204

JSON Example

To enable use of custom recordings on a directory handler, do the following:


PUT https://<connection-server>/vmrest/handlers/directoryhandlers/<DirectoryhandlerObjectId>
Accept: application /json
Content-Type: application/json
Connection: keep-alive
{
    "UseCustomGreeting": "true"
}

The following is an example of the *PUT* request and the actual response will depend upon the information given by you:

Response Code: 204

Listing Directory Handler Greeting

The following is an example of the GET request that lists all the custom recordings for a directory handler represented by the provided value of directory handler ID:

  GET https://<connection-
  server>/vmrest/handlers/directoryhandlers/<DirectoryHandlerObjectId>/directoryhandlerstreamfiles

The following is the response from the above *GET* request and the actual response will depend upon the information given by you:

<DirectoryHandlerStreamFiles>
  <DirectoryHandlerStreamFile>
    <DirectoryHandlerObjectId>3a0043ab-933b-45f6-852d-e0a261554da2</DirectoryHandlerObjectId>
    <LanguageCode>1033</LanguageCode>
    <StreamFile>5a0c7347-4064-4e94-a9c8-b12426d38f8a.wav</StreamFile>
  </DirectoryHandlerStreamFile>
</DirectoryHandlerStreamFiles>
Response Code: 200

JSON Example

To list directory handler greeting, do the following:

Request URI:
GET https://<connection-
server>/vmrest/handlers/directoryhandlers/<DirectoryHandlerObjectId>/directoryhandlerstreamfiles
Accept: application /json
Connection: keep-alive

The following is the response from the above *GET* request and the actual response will depend upon the information given by you:

{
  "DirectoryHandlerStreamFile": 
  {
    "DirectoryHandlerObjectId": "06628a5c-b755-466d-9e39-66e1956c2242",
    "LanguageCode": "1033",
    "StreamFile": "050590b8-fb8f-4e8d-ab17-4e29eab7d412.wav"
  }
}
Response Code: 200

Viewing Custom Recording for a Particular Language

The following is an example of the GET request that list the custom recording for a particular language from a directory handler:

  GET https://<connection-
  server>/vmrest/handlers/directoryhandlers/<DirectoryHandlerObjectId>/directoryhandlerstreamfiles
  /1033


Playing an Existing Greeting

The following is an example that will play an existing greeting in the browser:

  https://<connection-
  server>/vmrest/handlers/directoryhandlers/<DirectoryHandlerObjectId>/directoryhandlerstreamfiles
  /1033/audio


Add or Update Greeting by Uploading File from the Desktop

It is a 3 step process

Step 1: A place-holder for the WAV file must be created with a POST. This is a temporary file place-holder that can be used for up to 30 minutes. If it is not assigned to a resource within 30 minutes, the file is assumed to be abandoned and is automatically cleaned.

    POST https://<connection-server>/vmrest/voicefiles
    Response Code: 201

The content is the name of the newly created temporary .wav file.

JSON Example

To create a place-holder for the WAV file, do the following:

Request URI:
POST https://<connection-server>/vmrest/voicefiles
Accept: application/json
Content-Type: application/json
Connection: keep-alive
Response Code: 201
Sample Response: 6d9f3b85-c1df-4af8-89f3-6a975ebfb24c.wav

Step 2: Use the temporary file name to PUT the new audio data. The HTTP content type is "audio/wav" and the payload content is the audio data.

NOTE:*Rename the .wav file which is to be uploaded as the greeting to the temporary file name generated as part of the response from step1. For eg : If the file on desktop has name "greeting.wav" and the temporary file name is 6d9f3b85-c1df-4af8-89f3-6a975ebfb24c.wav(got as part of the response of step1), then the file should be renamed to 6d9f3b85-c1df-4af8-89f3-6a975ebfb24c.wav before step 2 is performed.

  • The length of the greeting can be set under the System Settings > General Configuration settings. Here you can enter the maximum length for system call handler greetings. The range is 1 to 1,200 seconds.

Default setting: 90 seconds. PUT /vmrest/voicefiles/<temporary file name> </pre>

Response Code: 204 

The content gets accepted and copied into the temporary file.

JSON Example To use the temporary file name, do the following:

Request URI:
PUT https://<connection server>/vmrest/voicefiles/<temporary file name>
Content-Type: audio/wav
Connection: keep-alive
Response Code: 204

Step 3: Set the Greeting field of the target resource. Both POST/ PUT can be used for adding a greeting. The PUT request should be used for updating the greeting with a new stream file.

  POST https://<connection-
  server>/vmrest/handlers/directoryhandlers/<directoryhandlerObjectId>/directoryhandlerstreamfiles
  /1033
Request Body:
<DirectoryHandlerStreamFile>
    <StreamFile>7acbfec8-25a3-4b02-bd23-2b61acc175c9.wav</StreamFile>
</DirectoryHandlerStreamFile >
Response Code: 201

JSON Example

To set the greeting field of the target resource, do the following:

Request URI: 
POST https://<connection-server>/vmrest/handlers/directoryhandlers/<directoryhandlerObjectId>/directoryhandlerstreamfiles/1033
Accept: application/json
Content-Type: application/json
Connection: keep-alive
Request Body:
{
    "StreamFile":"050590b8-fb8f-4e8d-ab17-4e29eab7d412.wav"
}

The following is the response from the above *POST* request and the actual response will depend upon the information given by you:

Response Code: 201

Use the following URL in a browser to play the stream file: https://<connection-server>/vmrest/handlers/directoryhandlers/<DirectoryHandlerObjectId>/directoryhandlerstreamfiles/1033/audio


Add/Update Greeting Recording Used in Telephony Interface

It is a three step process to record a new file then modify the current stream with this new stream.

Step 1: Call Connection In the first step integration between Unity Connection and Call Manager must be setup so that a call can be setup. Refer to the document at the below link to check how to make the call. http://docwiki.cisco.com/wiki/Cisco_Unity_Connection_Telephony_Interface_(CUTI)_API_--_Using_CUTI_for_Basic_Call_Operations

Step 2: Recording Once the phone is answered, the second step is to record the greeting. Refer to the document below to check how to record a greeting. http://docwiki.cisco.com/wiki/Cisco_Unity_Connection_Telephony_Interface_(CUTI)_API_--_Using_CUTI_for_Basic_Call_Operations

Step 3: Upload Greeting The response for the step 2 is a Call Control object xml. That xml is to be passed in as the request body for this request.

PUT https://<Connection Server>/vmrest/handlers/directoryhandlers/<DirectoryHandlerObjectId>/directoryhandlerstreamfiles/1033/audio
Request Body:
<CallControl>
    <op>RECORD</op>
    <resourceType>STREAM</resourceType>
    <resourceId>67ed783c-203f-454b-a0e6-57b77820c831.wav</resourceId>
    <lastResult>0</lastResult>
    <speed>100</speed>
    <volume>100</volume>
    <startPosition>0</startPosition>
</CallControl> 
Response Code: 204

JSON Example

To upload greeting, do the following:

PUT https://<connection-server>/vmrest/handlers/directoryhandlers/<DirectoryHandlerObjectId>/directoryhandlerstreamfiles/1033/audio
Accept: application/json
Content-Type: application/json
Connection: keep-alive
Request Body:
{
    "op":"RECORD",
    "resourceType":"STREAM",
    "resourceId":"67ed783c-203f-454b-a0e6-57b77820c831.wav",
    "lastResult":"0",
    "speed":"100",
    "volume":"100",
    "startPosition":"0"
}

The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:

Response Code: 204

Use the following URL in browser to play the stream file: https://<connection- server>/vmrest/handlers/directoryhandlers/<DirectoryHandlerObjectId>/directoryhandlerstreamfiles/10 33/audio Update the Greeting using the Input Stream The Directory Handler greeting can also be updated using the Input Stream. An input stream can be created from the wav file and passed as the request body. The URL for this should be :

RequestURI :
https://<connectionserver>/vmrest/handlers/directoryhandlers/<directoryhandlerobjectid>/directoryhan
dlerstreamfiles/1033/audio.

The request body should be like this: put.setRequestBody(new FileInputStream(file3)); Here put is the PUT request created, file3 is the wav file which user want to upload. Also the content type for the request should be passed as "audio/wav". Following URL can be used to listen to the greeting associated with the directory handler. Paste the URL in the browser and listen to the uploaded greeting: https://<connectionserver>/vmrest/handlers/directoryhandlers/<directoryhandlerobjectid>/directoryhan dlerstreamfiles/1033/audio


Explanation of Data Fields

Parameter Operations Data Type Comments
DirectoryHandlerObjectId Read Only String (36) Object ID of the custom recording.
LanguageCode Read/Write Integer Specifies the enumeration type.
StreamFile Read/Write String (40) Contains the .wav file that has been sent.

NOTE: To fetch the languages installed on a Unity Connection server, use the following URL:

GET https://<connection-server>/vmrest/installedlanguages

For more information on the Language Map API, please refer to the following document: http://docwiki.cisco.com/wiki/Cisco_Unity_Connection_Provisioning_Interface_%28CUPI%29_API_--_Language_Map

Rating: 0.0/5 (0 votes cast)

Personal tools