Cisco Unity Connection Provisioning Interface (CUPI) API -- Private Lists
Revision as of 22:37, 13 December 2010
Links to Other API pages: Cisco_Unity_Connection_APIs
|CUPI Guide Contents|
|API Overview |
Index of All CUPI Documentation
Every user with a mailbox can have private lists. To see the private lists belonging to a user, do the following GET request:
GET /vmrest/users/<user object id>/privatelists/
Here is an example of the response you might receive to such a request:
<?xml version="1.0" encoding="UTF-8"?> <PrivateLists total="1"> <PrivateList> <URI>/vmrest/users/f90d26fc-0e4a-405a-8c42-189a93129bdc/ privatelists/1f443e29-1d6b-4ef8-89a6-2767549e3577</URI> <ObjectId>1f443e29-1d6b-4ef8-89a6-2767549e3577</ObjectId> <DisplayName>1</DisplayName> <UserObjectId>f90d26fc-0e4a-405a-8c42-189a93129bdc</UserObjectId> <UserURI>/vmrest/users/f90d26fc-0e4a-405a-8c42-189a93129bdc</UserURI> <DtmfName>1</DtmfName> <Alias>UserA_1f443e29-1d6b-4ef8-89a6-2767549e3577</Alias> <VoiceName>6ce746b7-d775-4bc4-9d19-8b6a55b9461d.wav</VoiceName> <VoiceFileURI>/vmrest/voicefiles/ 6ce746b7-d775-4bc4-9d19-8b6a55b9461d.wav</VoiceFileURI> <NumericId>1</NumericId> <IsAddressable>true</IsAddressable> </PrivateList> </PrivateLists>
Many of these fields are consistent with what you see on other objects. Specific fields that are unique to private lists and require explanation are described below.
Private lists belong to specific users. The UserObjectId and UserURI field show that relationship.
DtmfName is a field with a value that is automatically generated every time the display name changes on the private list. DtmfName holds the digits that would need to be dialed to address a message by name to this group by phone.
Alias is a unique text name for the private list. The alias is automatically generated, and to ensure it is unique, it is constructed by concatenating the user alias, an underscore and the private list's object id. The user's alias is truncated to 28 characters to avoid overflow.
NumericId is the number of the private list. Private lists are numbered 1 through 99, and when addressing a message by extension over the phone, the number can be used to choose the group.
IsAddressable is an odd flag. It flags whether or not the private list is addressable. By default, all private lists are addressable.
The following POST creates a private list. In this example, it would be private list 2.
POST /vmrest/users/<user object id>/privatelists <?xml version="1.0" encoding="UTF-8"?> <PrivateList> <DisplayName>2</DisplayName> <VoiceName>6ce746b7-d775-4bc4-9d19-8b6a55b9461d.wav</VoiceName> <NumericId>2</NumericId> </PrivateList>
These are the only three parameters that can be explicitly set on a new private list. The other parameters are not allowed on a POST, either defaulting to a certain value or being auto-generated as discussed above. The ObjectId can be explicitly set if desired, but that is optional.
Only the following fields can be updated in a PUT request:
The following example shows a PUT request that modifies some fields, changing a private list to private list 6.
PUT /vmrest/users/<user object id>/privatelists/<private list object id> <?xml version="1.0" encoding="UTF-8"?> <PrivateList> <DisplayName>6</DisplayName> <NumericId>6</NumericId> </PrivateList>
A private list can be deleted by a DELETE request:
DELETE /vmrest/users/<user object id>/privatelists/<private list object id>
Creating a voice name for a private list (or for any object exposed in CUPI) is a multi-step process.
Step 1: Create a place-holder for the WAV file by doing a POST:
The name of the WAV file will be included in the response.
201 Created 6f9c6d05-42e5-48e3-8d07-204250af320d.wav
Step 2: Take the name returned in Step 1, and do a PUT where the HTTP content type is "audio/wav" and the payload content is the audio data:
Step 3: Take the name of the WAV file and do a PUT request on the private list whose voice name you want to set:
PUT /vmrest/users/<user object id>/privatelists/<private list object id> <?xml version="1.0" encoding="UTF-8"?> <PrivateList> <VoiceName>6ce746b7-d775-4bc4-9d19-8b6a55b9461d.wav</VoiceName> </PrivateList>
The voice name can always be retrieved through the voice name URI, it will return the audio of the greeting as an "audio/wav" media type: