Cisco Unity Connection Provisioning Interface (CUPI) API--Directory Handler APIs
Directory Handler APIs
Directory handlers provide access to a corporate directory that callers can use to reach Cisco Unity Connection users with mailboxes. When a caller searches for a username or part of a name, a directory handler looks up the extension and routes the call to the appropriate user. Administrator can use this API to create/update/delete/fetch the directory handler. You can update various attributes of directory handler using this API.
Listing the Directory Handlers
The following is an example of the GET request that fetch the list of directory handlers:
GET https://<connection-server>/vmrest/handlers/directoryhandlersThe following is the response from the above *GET* request and the actual response will depend upon the information given by you:
|
|
JSON Example
To list of directory handlers, do the following:
|
The following is the response from the above *GET* request and the actual response will depend upon the information given by you:
|
|
Listing Specific Tenant Related Directory Handlers by System Administrator
In Cisco Unity Connection 10.5(2) and later, the system administrator can use TenantObjectID to list the specific tenant related directory handlers using the following URI:
GET https://<connection-server>/vmrest/handlers/directoryhandlers?query=(TenantObjectId is <Tenant>To get the TenantObjectID, use the following URI:
GET https://<connection-server>/vmrest/tenantsViewing the Specific Directory Handler
The following is an example of the GET request that lists the details of specific directory handler represented by the provided value of directory handler ID:
GET https://<connection-server>/vmrest/handlers/directoryhandlers/<directoryHandlerObjectId>The following is the response from the above *GET* request and the actual response will depend upon the information given by you:
|
Response Code: 200JSON Example
To list details of a particular directory handler, do the following:
|
The following is the response from the above *GET* request and the actual response will depend upon the information given by you:
|
Response Code: 200Creating a Directory Handler
The following is an example of the POST request that creates a new directory handler:
POST https://<connection-server>/vmrest/handlers/directoryhandlersRequest Body:
|
The following is the response from the above *POST* request and the actual response will depend upon the information given by you:
|
JSON Example
To create a new directory handler, do the following:
|
Request Body:
|
The following is the response from the above *POST* request and the actual response will depend upon the information given by you:
|
Delete the Directory Handler
This request can be used to delete a directory handler.
|
The following is the response from the above *DELETE* request and the actual response will depend upon the information given by you:
|
JSON Example
To delete the directory handler, do the following:
|
The following is the response from the above *DELETE* request and the actual response will depend upon the information given by you:
|
Updating the Search Scope of the Directory Handler
The following is an example of the PUT request that can be used to modify the search scope of the directory handler. In the request body, the search scope value corresponds to the type of search scope and search scope object ID represents the objectid corresponding to the search scope value. For Example Value for COS as search scope is 5 and search scope object ID should be COS.
|
Request Body:
|
The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:
|
The table given below lists the possible values of the search scope:
|
Name |
Value |
Description |
|---|---|---|
|
VMS |
0 |
VMS - directory handler search restricted to the local VMS. |
|
DialingDomain |
1 |
Dialing domain - directory handler search restricted to a dialing domain. |
|
Global |
2 |
Global - directory handler search expanded to the entire Unity organization (global). |
|
Location |
3 |
Location - directory handler search restricted to a Unity location. |
|
DistributionList |
4 |
Distribution list - directory handler search is restricted to a distribution list. |
|
cos |
5 |
COS - directory handler search restricted to a class of service. |
|
SearchSpace |
6 |
SearchSpace - directory handler search restricted to a search space. |
|
Inherit |
7 |
Inherit - directory handler search is restricted to the search space of the call. |
|
Invalid |
8 |
Invalid - directory handler search scope is no longer valid; used by the replicator. |
You can set the search scope of a directory handler by defining only search scope and search scope object ID. The search scope object Id can have these references, COS object Id, location object Id, distribution list, and search space object ID.
Example 1: Update the Search Scope of a Directory Handler to a Class of Service
To update the search scope of a directory handler to a class of service, you must obtain the COS object ID.
GET https://<connection-server>/vmrest/cosesThe following is an example of the PUT request to update the directory handler to COS object ID:
Request URI
PUT https://<connection-server>/vmrest/handlers/directoryhandlers/<directoryHandlerObjectId>Request Body:
|
|
Example 2: Update the Search Scope of a Directory Handler to Entire Server
To update the search scope of a directory handler to entire server, you must obtain the location of the object id of the connection server:
|
The following is an example of the PUT request to update the directory handler to entire server:
Request URI:
PUT https://<connection-server>/vmrest/handlers/directoryhandlers/<directoryHandlerObjectId>Request Body:
|
|
Example 3: Update the Search Scope of a Directory Handler to Inherit Search Scope from Call
The following is an example of the PUT request to update the search scope of directory handler to inherit search scope from call:
Request URI:
|
Request Body:
|
|
Example 3: Update the Search Scope of a Directory Handler to Inherit Search Scope from Call
The following is an example of the PUT request to update the search scope of directory handler to inherit search scope from call:
Request URI:
|
Request Body:
|
|
Example 4: Update the Search Scope of a Directory Handler to a Distribution List
The following is an example of the PUT request to update the search scope of directory handler to a distribution list:
|
Request Body:
|
|
Example 5: Update the Search Scope of a Directory Handler to a Search Space
To update the search scope of a directory handler to a search space, you must obtain the object ID of the search scope using the following URL:
|
The following is an example of the PUT request to update the search scope of directory handler to a search space:
Request URI:
|
PUT https://<connection-server>/vmrest/handlers/directoryhandlers/<directoryHandlerObjectId> |
Request Body:
|
|
JSON Example
To update the search scope of a directory handler to a search space, do the following:
Request URI:
|
Request Body:
|
The following is an example of the PUT request to update the search scope of directory handler to a search space:
|
Updating the Exit Action on a directory handler
You can update the exit action, no input action, no selection action and action when caller presses zero on a directory handler. To specify the destination when a caller exits the directory handler using the * key/ or #key, the following fields are used to specify the destination:
-
ExitAction
-
ExitTargetConversation
-
ExitTargetHandlerObjectId
In a scenario where caller does not respond to the name entry prompt, the following fields are used to specify the destination the fields:
-
NoInputAction
-
NoInputTargetConversation
-
NoInputTargethandlerObjectId
In another scenario where caller does not respond to the name entry prompt the fields, the following fields are used to specify the destination the fields:
-
NoSelectionAction
-
NoSelectionTargetConversation
-
NoSelectionTargetHandlerObjectId
If callers press the zero key, the following fields are used to specify the destination the fields:
-
ZeroAction
-
ZeroTargetConversation
-
ZeroTargetHandlerObjectId
-
Call Handlers: /vmrest/handlers/callhandlers
-
Directory Handlers: /vmrest/handlers/directoryhandlers
-
InterviewHandler : /vmrest/handlers/interviewhandlers
The following sections give some examples of how to specify different types of destinations by using these fields when caller exits the directory handler.
Example 1: Call should hang up on exit action.
Request URI
|
Request Body
|
|
Example 2: Call should be sent to a call handler or a user greeting
Request URI
|
Request Body
|
|
JSON Example
To update the directory handler, do the following:
Request URI
|
Request Body
|
The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:
|
Example 3: Call should be transferred to a call handler or user
Request URI
|
Request Body
|
|
 Note |
The fields for that needs to be sent as input are Exit Action and ExitTargetConversation. |
Example 5: Call should be sent to an Interview Handler
Request URI
|
Request Body
|
|
Example 6: Call should be sent to a Directory Handler.
Request URI
|
Request Body
|
|
Setting Voice Enable to true for a Directory Handler
Voice enabled directory handlers cannot use a class of service or a distribution list as per their search scope.
Only entire server, a specific search space, or Inherit search space from call are allowed.
Request URI
|
Request Body
|
|
JSON Example
To update the voice enable, do the following:
Request URI
|
The following is an example of the PUT request to update the search scope of directory handler to a search space:
|
Note |
|
Updating the Language of Directory Handler
This request can be used to update a language for a directory handler. It can be used to set a particular language for a directory handler, set the system default language as the language of directory handler or set the language of directory handler as inherit from call.
|
The below table specify the details of value for each field:
|
UseCallLanguage |
UseDefaultLanguage |
Language |
Description |
|---|---|---|---|
|
false |
true |
Null/Language Code |
This will select the default language. |
|
true |
true/false |
Null/Language Code |
This will inherit the language from user. |
|
false |
false |
Language Code |
This will select the particular language as per the code. |
Request URI
|
Example 1: Updating the Inherit Language field and not the Language field
Request Body
|
|
The Inherit Language field from the call is selected but the UseDefaultLanguage field will not get updated in the database as the Language field is missing. If the Language field is NULL, the UseDefaultLanguage field is by default set to TRUE.
Example 2: Updating the Inherit Language field and the Language field
Request Body
|
|
The Inherit Language field from the call is selected but the UseDefaultLanguage field is updated in the database as the Language field is specified.
JSON Example
To change language, do the following:
Request URI
|
Request Body
|
|
Explanation of Data Fields
| Parameter | Operations | Data Type | Comments |
|---|---|---|---|
| Language | Read/Write | Integer | Specifies the language code.
All possible language code values can be fetched using <connection server>/vmrest/languagemap. |
| Display Name | Read/Write | String(64) | The display name of Directory Handler |
| Undeletable | Read/Write | Boolean | Shows whether the Directory Handler can be deleted or not.
Values:
Default value: false |
| VoiceName | Read/Write | String(40) | Specifies the .wav file which is the recorded name. |
| VoiceFileURI | Read Only | String | Specifies the URI of the voice file. |
| VoiceNameURI | Read Only | String | Specifies the URI of voice names. |
| LocationObjectId | Read Only | String(36) | The unique identifier of the location object to which this handler belongs. Location, e.g. "Seattle Office." |
| LocationURI | Read Only | String | Specifies the URI of location. |
| EndDialDelay | Read/Write | Integer | The amount of time (in seconds) that Cisco Unity Connection waits after caller input before performing the action indicated
by the input.
Value can be in the range 1-10. Default Value: 4. |
| MaxMatches | Read/Write | Integer | The number of matches that if exceeded, will result in Cisco Unity Connection prompting the caller to dial more letters.
Value can be in the range 1-30. Default value: 8. |
| MenuStyle | Read/Write | Boolean | A flag indicating how Cisco Unity Connection presents directory matches to callers - either in "menu choice" or "extension
list" format.
Note: MenuStyle cannot be set to false for the System Default Directory Handler. Possible values can be:
Default value: true. |
| SayExtension | Read/Write | Boolean | A flag indicating whether Cisco Unity Connection provides a menu of subscriber names including extensions, or just subscriber
names.
Possible values can be:
Default value : true |
| SearchByFirstName | Read/Write | Boolean | A flag indicating whether a directory handler searches for subscribers by using first name first, or last name first.
Values:
Default value: false. |
| StartDialDelay | Read/Write | Integer | The amount of time (in seconds) that Cisco Unity Connection waits for the caller to start dialing.
Default value: 5. Value can be in the range 1-10. |
| Tries | Read/Write | Integer | The number of times Cisco Unity Connection will reprompt the caller for input, e.g. dial name.
Default value : 1. Value can be in the range 0-10. |
| UseStarToExit | Read/Write | Boolean | A flag indicating the key on the phone to use for "exit the directory."
Values:
Default value: true. |
| SearchScope | Read/Write | Integer | The scope of the directory that Cisco Unity Connection will search.
Default value: 0( search scope set as entire server). Possible values : Refer to the SearchScope section under the Enumeration Type as given at the end of the document |
| SearchScopeObjectId | Read/Write | String(36) | ObjectId of the Search Scope type set. For example : For Class of Service it will be Class Of Service Object ID. |
| ScopeObjectCosObjectId | Read Only | String(36) | Represents a Class of Service(COS) .Only users with this COS will be included in the directory handler. |
| ScopeObjectDistributionListObjectId | Read Only | String(36) | Represents a Distribution List. Only users who are members of this distribution list will be included in the directory handler. |
| ScopeObjectLocationObjectId | Read Only | String(36) | Represents a Cisco Unity Connection Location .Only those users assigned to this location will be included in the directory handler. |
| ScopeObjectSearchSpaceObjectId | Read Only | String(36) | Represents a Search Space .The unique identifier of the search space which can act as filter for the directory handler. |
| PlayAllNames | Read/Write | Boolean | A flag indicating whether Cisco Unity Connection plays the names of subscribers in the directory for caller selection, rather
than requiring the caller to search by spelled name.
Default value: false. |
| ExitAction | Read/Write | Integer | Specifies the exit action. Default Value is 2.
Possible Values: Refer to the section Enumeration Type at the end of the document. |
| ExitTargetConversation | Read/Write | String(64) | Specifies the conversation to go to upon exit. Default value is "PHTransfer". Possible Values:
Refer to the section Enumeration Type at the end of the document. |
| ExitTargetHandlerObjectId | Read/Write | String(36) | The Unique Identifier of the call action object that Cisco Unity Connection performs if the caller exits the directory handler. |
| NoInputAction | Read/Write | Integer | Specifies the action to be performed if there is no caller Input.
Default Value: 2. Possible Values: Refer to the section Enumeration Type at the end of the document. |
| NoInputTargetConversation | Read/Write | String(64) | Specifies the conversation to go when caller gives no Input. Default value is "PHTransfer".
Refer to the section Enumeration Type at the end of the document. |
| NoInputTargetHandlerObjectId | Read/Write | String(36) | The unique identifier of the CallAction object that Cisco Unity Connection performs (or the destination to which calls are sent) if the caller does not enter a name or by not responding to prompts. |
| NoSelectionAction | Read/Write | Integer | Specifies the action to be performed when caller does not select anything. Default Value: 2.
Possible Values: Refer to the section Enumeration Type at the end of the document. |
| NoSelectionTargetConversation | Read/Write | String(64) | Specifies the conversation to go when caller does not select anything.Default value is "PHTransfer" .
Refer to the section Enumeration Type at the end of the document. |
| NoSelectionTargetHandlerObjectId | Read/Write | String(36) | The unique identifier of the CallAction object that Cisco Unity Connection performs (or the destination to which the caller is sent to) if the caller makes no selection from a list of matches. |
| ZeroAction | Read/Write | Integer | Specifies the action to be performed for caller input '0'.
Default Value: 2 Possible Values: Refer to the section Enumeration Type at the end of the document. |
| ZeroTargetConversation | Read/Write | String(64) | Specifies the conversation when caller presses 0. Default value is "PHTransfer".
Refer to the section Enumeration Type at the end of the document. |
| ZeroTargetHandlerObjectId | Read/Write | String(36) | The unique identifier of the CallAction object that Cisco Unity Connection performs if caller presses zero ("0") key during menu style list of names. |
| AutoRoute | Read/Write | Boolean | Represents how the call should be routed once the matches are found in the Directory.
Default value: false. Values:
|
| ObjectId | Read Only | String(36) | Object Id of the directory handler |
| TenantObjectId | Read Only | String(36) | The unique identifier of the tenant to which the directory handler belongs. This field is reflected in the response only if the directory handler belongs to a particular tenant. |
| DtmfAccessId | Read/Write | String(40) | Extension of the Directory handler |
| VoiceEnabled | Read/Write | Boolean | A flag indicating whether the directory handler will use voice based addressing rather than touchtones.
Default value: false. Values:
|
| UseCallLanguage | Read/Write | Boolean | Specifies if the language as inherited from the call is to be used. Default value is true. |
| UseDefaultLanguage | Read/Write | Boolean | Specifies if the system default language has to be used. Default value is true. |
| PartitionObjectId | Read/Write | String(36) | Object Id of the partition the directory handler belongs to |
| PartitionURI | Read Only | String | URI of partitions |
| SpeechConfidenceThreshold | Read/Write | Integer | When the engine matches a spoken phrase, it associates a confidence level with that conclusion. This parameter determines
what confidence level should be considered a successful match.
Default Value is 10. Range of Value is 0 -100 |
| SayCity | Read/Write | Boolean | A flag indicating if the user's city is voiced when a match is voiced.
Default value is false. |
| SayDepartment | Read/Write | Boolean | A flag indicating if the user's department is voiced when a match is voiced.
Default value is false. |
| UseCustomGreeting | Read/Write | Boolean | Indicates whether to use the directory handler's custom greeting or the system prompt.
Default value is false. |
| CreationTime | Read Only | DateTime | Specifies the creation time of the directory handlers. |
| ExitConversationURI | Read Only | String | Specifies the URI to fetch the conversation values which can be used as the ExitConversation |
| NoInputConversationURI | Read Only | String | Specifies the URI to fetch the conversation values which can be used as the NoInputConversation. |
| NoSelectionConversationURI | Read Only | String | Specifies the URI to fetch the conversation values which can be used as the NoSelectionConversation. |
| ZeroExitConversationURI | Read Only | String | Specifies the URI to fetch the conversation values which can be used as the ZeroExitConversation |
| DirectoryHandlerStreamFileURI | Read Only | String | Specifies the URI for the Directory Handler Stream files which are used as the greeting for the Directory Handler. |
Feedback