Cisco Unity Connection Provisioning Interface (CUPI) API -- Call Handler APIs
Call Handler APIs
Call handlers answer calls, greet callers with recorded prompts, provide callers with information and options, route calls, and take messages. They are a basic component of Cisco Unity Connection. Your plan for call handlers can be simple, using only the predefined call handlers, or you can create up to 40,000 new call handlers. You may want to use call handlers in the following ways:
As an automated attendant---A call handler can be used in place of a human operator to answer and direct calls by playing greetings and responding to key presses. The automated attendant can provide a menu of options. For example, "For Sales, press 1; for Service, press 2; for our business hours, press 3".
To offer prerecorded audio text---A call handler can be used to provide information that customers request frequently. For example, "Our normal business hours are Monday through Friday, 8 a.m. to 5 p.m.", or to play a pre-recorded message that all callers hear before they can interact with the system.
As a message recipient---A call handler can be used to take messages for the organization. For example, "All of our customer service representatives are busy. Please state your name, phone number, and account number, and we will return your call as soon as possible.".
To transfer calls---A call handler can be used to route callers to a user. For example, after hours, you could transfer calls that come to a technical support call handler directly to the mobile phone of the person who is on call, or to another call handler.
Administrator can use this API to create/update/delete/fetch the call handler. You can update various attributes of call handler using this API.
Listing the Call Handlers
The following is an example of the GET request that fetch the list of call handlers:
GET https://<connection-server>/vmrest/handlers/callhandlers
The 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 the call 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 Call 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 call handlers using the following URI:
|
To get the TenantObjectID, use the following URI:
|
Viewing the Specific Call Handler
The following is an example of the GET request that lists the details of specific call handler represented by the provided value of call handler ID:
|
The following is the response from the above *GET* request and the actual response will depend upon the information given by you:
|
|
JSON Example
To view a specific call 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:
|
|
Creating a Call Handler
The following is an example of the POST request that creates a new call handler:
|
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 call handler, do the following:
|
The following is the response from the above *POST* request and the actual response will depend upon the information given by you:
|
Note |
Make sure that while creating a Call Handler, do not provide the recipient object Id in the request body. By default, Call handler is created with undeliverable messages distribution list as the recipient. You can update the recipient object id using PUT API. |
Delete the Call Handler
The following is an example of the DELETE request that can be used to delete a call 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 a call 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:
|
Assigning a Schedule Set to a Call Handler
The following is an example of the PUT request that can be used to assign a schedule set to a call handler:
|
|
JSON Example
To assign a schedule to a call handler, do the following:
|
The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:
|
Specify Message Recipient for a Call Handler
The following is an example of the PUT request that can be used to specify message recipient for a call handler:
|
The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:
|
JSON Example
To specify message recipient for a call handler, do the following:
|
The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:
|
Caller Input Keys
http://docwiki.cisco.com/wiki/Cisco_Unity_Connection_Provisioning_Interface_%28CUPI%29_API_--_Caller_Input_Keys
Updating Caller Input Keys
http://docwiki.cisco.com/wiki/Cisco_Unity_Connection_Provisioning_Interface_%28CUPI%29_API_--_Updating_Caller_Input_Keys
Update the Language of Call Handler
To fetch the language code, use the following URI:
|
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. |
Updating Time Zone of Call Handler
This PUT request can be used to update time zone for a call handler template. It can be set to default or particular time zone. To know time zones installed on the server, you can use the following URI:
|
For updating time zone of a call handler, the mandatory fields are:
UseDefaultTimeZone
TimeZone
|
The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:
|
Explanation of Data Fields
Parameter |
Operations |
Data Type |
Comments |
URI |
Read Only |
String |
Call Handler URI |
AfterMessageAction |
Read/Write |
Integer |
Specifies the after message action. Refer to the section Enumeration Type. |
AfterMessageTargetConversation |
Read/Write |
String |
The name of the conversation to which the caller is routed. Refer to the section Enumeration Type |
AfterMessageTargetHandlerObjectId |
Read/Write |
String |
The Unique Identifier of the call action object that Cisco Unity Connection performs after taking a message. |
CallSearchSpaceObjectId |
Read/Write |
String |
The unique identifier of the SearchSpace that is used limit visibility to dialable objects when searching by extension (dial string). |
CallSearchSpaceURI |
Read Only |
String |
URL for search spaces. |
CreationTime |
Read Only |
datetime |
Specifies the creation date and time of the call handler. Format: YYYY-MM-DDThh:mm:ssZ . The default value is the current system date and time. |
DispatchDelivery |
Read/Write |
Boolean |
A flag indicating that all messages left for the call handler is for dispatch delivery. Possible values: false: specifies no dispatch delivery. true: specifies dispatch delivery. Default value: false |
DisplayName |
Read/Write |
String |
Name of the call handler. |
DtmfAccessId |
Read/Write |
String |
Extension of the call handler. |
EditMsg |
Read/Write |
Boolean |
A flag that determines whether the caller can edit messages. Possible values: false : Callers cannot edit messages true : Callers can edit messages Default value: true. |
EnablePrependDigits |
Read/Write |
Boolean |
Specifies if Prepend Digits to Dialed Extensions is enabled. Possible values: false:- System will not prepend digits when dialing the transfer extension true:- System will prepend digits when dialing the transfer extension Default value: false |
InheritSearchSpaceFromCall |
Read/Write |
Boolean |
Specifies if the search space is to be inherited from the call. Possible values: true – Inherit from call. false – Do not inherit from call Default value: true |
IsPrimary |
Read Only |
Boolean |
A flag indicating whether this is a "primary" call handler for a subscriber, or an "application" call handler. Note:- Each subscriber is associated with a call handler, which is referred to as the "primary call handler" for that subscriber. An "application call handler" is just a normal call handler. Possible values: false: Not a primary call handler true: Primary call handler Default value: false. |
IsTemplate |
Read Only |
Boolean |
A flag indicating whether this CallHandler is a "template" for creating new call handlers. It is used to provide default values for selected columns when creating new call handlers. Possible values: false: Not a template true: Is a template Default value: false |
Language |
Read/Write |
Integer |
The Windows Locale ID (LCID) which identifies the language that Cisco Unity Connection plays the handler system prompts. |
LocationObjectId |
Read Only |
String |
The unique identifier of the Location object to which this handler belongs |
LocationURI |
Read Only |
String |
Specifies the URI of locations The maximum recording length (in seconds) for messages left by unidentified callers. This value is used when the call handler is set to an action of "Take Message" (either by an after greeting action in the messagingrule table or via a user input action in the menuentry table. This value only gets applied to unidentified callers leaving a message. This value is not used for subscriber-subscriber messaging. Instead the COS for the calling subscriber determines the maximum recorded message length. The range of this field can vary from 1-3600. Default value: 300 |
MaxMsgLen |
Read/Write |
Integer |
Specifies the object Id of the Phone System the call handler belongs to. |
MediaSwitchObjectId |
Read/Write |
String |
Specifies the URI of Phone Systems. |
PhoneSystemURI |
Read Only |
String |
Specifies an object ID of the call handler. |
ObjectId |
Read Only |
String |
The unique identifier of the tenant to which the call handler belongs. This field is reflected in the response only if the call handler belongs to a particular tenant. |
TenantOjectId |
Read Only |
String |
The amount of time (in milliseconds) that Cisco Unity Connection waits for additional input after callers press a single key that is not locked. If there is no input within this time, Cisco Unity Connection performs the action assigned to the single key. When a caller interrupts a greeting with a digit, Cisco Unity Connection will wait this number of milliseconds to see if they are going to enter more digits. Once this timeout is reached (or the caller terminates the input with a #), Cisco Unity Connection will do a look-up of the resulting string of numbers for a match with a DTMFAccessID value in the dialing domain. If a match is found, the call is sent to the matching object. If no match is found, the "Error greeting" for the call handler is invoked. If a key is "locked" then this value does not apply. Instead action is taken immediately on that key instead of allowing more digits. A value of 0 disables one key input .The range of this field can vary from 1 to 10000. Default value: 1500 |
OneKeyDelay |
Read/Write |
Integer |
Specifies the object Id of the partition the Call Handler belongs to. |
PartitionObjectId |
Read/Write |
String |
Specifies the URI of partitions. |
PartitionURI |
Read Only |
String |
Specifies what should be played after the message. Refer to the section Enumeration Type. |
PlayAfterMessage |
Read/Write |
Integer |
Specifies an object ID of the recoding. |
PlayAfterMessageRecordingObjectId |
Read/Write |
String |
Indicates whether the recording referenced by PostGreetingRecordingObjectId should be played. Possible values: 0 : No 1 : Always 2 : External Default value: 0 |
PlayPostGreetingRecording |
Read/Write |
Integer |
Specifies the object Id of the Post Greeting recording. |
PostGreetingRecordingObjectId |
Read/Write |
String |
URI of the Post Greeting Recording |
PostGreetingURI |
Read Only |
String |
Specifies the touchtone digits to be prepended to extension when dialing transfer number ( #, 0,1...9,*). Digits, plus, hash and asterisk only are allowed |
PrependDigits |
Read/Write |
String |
Specifies an object ID of the distribution list that is the message recipient. |
RecipientDistributionListObjectId |
Read/Write |
String |
Object ID of a User with a mailbox that is the message recipient. |
RecipientDistributaionListURI |
Read Only |
String |
Object ID of the schedule set assigned to the Call Handler. |
ScheduleSetObjectId |
Read/Write |
String |
Specifies the URI of schedule sets. |
ScheduleSetURI |
Read/Write |
String |
Determines if an outside caller can mark their message as private. Possible values: 0 : Never 1 : Always 2 : Ask Default value: 0 |
SendPrivateMsg |
Read/Write |
Integer |
A flag indicating whether an unidentified caller can mark a message as "secure." Default value: false |
SendSecureMsg |
Read/Write |
Boolean |
A flag indicating whether an unidentified caller can mark a message as "urgent." Possible values: 0 : Never 1 : Always 2 : Ask Default value: 0(Never) |
SendUrgentMsg |
Read/Write |
Integer |
Used when the UseDefaultTimezone is set to false. To know the Integer Time Zone codes for the Time Zones installed on the server following URI can be used: https://<connection-server>/vmrest/timezones. Example: 190 is the code for (GMT+05:30) Asia/Kolkata |
TimeZone |
Read/Write |
Integer |
A flag indicating whether Cisco Unity Connection will use the language assigned to the call. Possible Values: true false Default value: true |
UseCallLanguage |
Read/Write |
Boolean |
A flag that is dependent on the value of the Language field. If Language is set to Null, UseDefaultLanguage is set to true. If any language is specified, UseDefaultLanguage is set to false. Possible Values: true false |
UseDefaultLanguage |
Read/Write |
Boolean |
A flag indicating whether Cisco Unity Connection will use the system default Time Zone. Possible Values: true false Default value: false |
UseDefaultTimeZone |
Read/Write |
Boolean |
URI of the call handler owner API. |
CallHandlerOwnerURI |
Read Only |
String |
The name of the WAV file containing the recorded audio (voice name, greeting, etc.) for the parent object. It is displayed once a voice-name is recorded. |
VoiceName |
Read Only |
String |
It is displayed once a voice-name is recorded. |
VoiceFileURI |
Read Only |
String |
Specifies the URI of greetings |
GreetingsURI |
Read Only |
String |
Specifies the URI of transfer options. |
TransferOptionsURI |
Read Only |
String |
Specifies the URI of menu entries |
MenuEntriesURI |
Read Only |
String |
Specifies the URI of menu entries |
ViceNameURI |
Read Only |
String |
URI for voice name once it is recorded. |