About Notification Devices

This page contains information on how to use the API to create, list, update, and delete Notification Devices.

Cisco Unity Connection supports four different types of Notification Devices:

Phone Devices

Pager Devices

SMS Devices

SMTP Devices

The generic Notification Device resource contains the data fields that are common to most or all of the specialized Device resources, which in turn may contain additional data fields that are specific to certain Device resources. A listing of all data fields, including a description of what they mean and which specialized Device types support them, can be found later in this document.

An API user can retrieve a complete list of all Notification Devices or a specific Notification Device, but this is a read-only resource. In order to create, update, or delete a Notification Device, an API user must use the appropriate specialized Device resource. In other words, an API user can retrieve all of a user's Notification Devices, but if they then want to update a particular Phone Device, they must do the update operation on the Phone Device resource, not the Notification Device resource. This will be explained in more detail below.

The Notification Device resource and the four specialized Device resources contain data fields from the Device objects in the database, plus some data fields from the Notification Rule object. From an API user's perspective, this detail may not usually be important, but it is worth mentioning that the Device resources collapse two database objects into a single resource. This can be safely done because there is always a one-to-one mapping in the database of Notification Devices and Notification Rules.

The factory default User Template for Voicemail Users contains five Notification Devices: three Phone Devices (Home, Work, and Mobile), one Pager Device, and one SMTP Device. Any of these default Notification Devices can be modified, and new Devices of any of four specialized types can be created or deleted. Note that Notification Devices for User Templates are not currently exposed via the API, only Notification Devices for Users are exposed.

Listing and Viewing

An API user can list all generic Notification Device resources or all Device resources of a specified type (Phone, Pager, SMS, or SMTP).

Listing and Viewing Notification Devices

The following is an example of a GET that lists all Notification Devices of all types for the specified User:

Listing and Viewing Specialized Devices

The following is an example of a GET that lists all Phone Devices for the specified User. Listing all specialized devices of other types is very similar; simply do a GET to the pagerdevices, smsdevices, or smtpdevices resource, rather than to the phonedevices resource.

GET https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/phonedevices

The following is the response from the above GET request. Note that each returned resource is a Phone Device rather than a Notification Device since the request was for Phone Devices only.

Searching

To retrieve a list of Notification Devices that meet a specified search criteria, add the following query parameter to a GET: query=(column [is | startswith] value)

For example, to find all Notification Devices with a DisplayName that starts with "Phone":

GET https://<connection-server>/vmrest/users/<UserObjectId/notificationdevices?query=(DisplayName%20startswith%20Home)

Search criteria can also be used when doing a GET to the specialized Device resources.

Creating

A generic Notification Device resource is read-only, so new ones cannot be created. However, the four specialized Device resources are not read-only, so new ones can be created. Each of the four specialized Device resources has different required parameters during creation.

Creating Phone Devices

The required fields for creating a Phone Device are DisplayName, MediaSwitchObjectId, and PhoneNumber. All other Phone Device fields are optional.

The following is an example of a POST that creates a Phone Device with a DisplayName="My New Phone", MediaSwitchObjectId="6ecaa89b-2d29-4a21-8013-75c154ee58f5", PhoneNumber="5551212", and optional parameter InitialDelay=10:

201
Created
/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/phonedevices/2e377eba-a924-434b-b967-bac3815551d3

Creating Pager Devices

The required fields for creating a Pager Device are DisplayName, MediaSwitchObjectId, and PhoneNumber. All other Pager Device fields are optional.

The following is an example of a POST that creates a Pager Device with DisplayName="My New Pager", MediaSwitchObjectId="6ecaa89b-2d29-4a21-8013-75c154ee58f5", PhoneNumber="8675309", and optional parameter Active=false.

201
Created
/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/pagerdevices/13cbf32e-dc58-4695-aaf0-9f3a027cdab7

Creating SMS Devices

The required fields for creating an SMS Device are DisplayName, SmppProviderObjectId, and RecipientAddress. All other SMS Device fields are optional. Note that there must be an SMPP Provider configured on the system before you can create an SMS Device for Notification. If the SmppProviderObjectId field is not supplied or does not correspond to an SMPP Provider configured on the system, then an HTTP 400 error will be returned, with text explaining that the parameter is missing or cannot be found in the SmppProvider table.

The following is an example of a POST that creates an SMS Device with DisplayName="My New SMS Device", SmppProviderObjectId="60cd37e8-499c-43a3-b733-30f2640e5003", RecipientAdress="bob@xyz.com", and optional parameter SenderAddress="voicemail@xyz.com".

201
Created
/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/smtpdevices/233e4e41-4743-41e2-a2c1-4f6691a21599

Updating

A generic Notification Device resource is read-only, so Notification Devices cannot be updated. However, the four specialized Device resources are not read-only, so an API user can update the appropriate specialized Device resource.

The following is an example of a PUT request that modifies the FailDeviceObjectId of an existing Phone Device. The FailDeviceObjectId indicates which Notification Device to try if notification fails to the current device, which allows you to setup a chain of Notification Devices.

Updating other types of specialized Device resources is very similar; simply do a PUT to the appropriate pagerdevice, smsdevice, or smtpdevice resource instead of a phonedevice resource.

Deleting

A generic Notification Device resource is read-only, so Notification Devices cannot be deleted. However, the four specialized Device resources are not read-only, so an API user can delete the appropriate specialized Device resource, assuming its not one of the factory default Device resources (which are flagged as Undeletable).

The following is an example of a DELETE request that deletes an existing Phone Device:

Explanation of Data Fields

The following chart lists all of the data fields available on Notification Devices, Phone Devices, Pager Devices, SMS Devices, and SMTP Devices. In the Device Types column, "Base" means the generic Notification Device resource. Note that on a GET to the generic Notification Device resource, you may receive data fields that are meaningless for a particular type of device, so these fields can be safely ignored.

Field Name

Device Type

Writable?

Explanation / Comments

ObjectId

All

Read-only

ObjectId of the Device

Type

Base

Read-only

Auto-set during Create. 1=Phone, 2=Pager, 4=SMTP, 5=SMS

Active

All

Read/Write

Factory default=false. For newly-created, default=true

AfterDialDigits

Base, Phone, Pager

Read/Write

Extra-digits to dial after the Phone Number. Default=null

BusyRetryInterval

Base, Phone, Pager

Read/Write

Time in minutes to wait between retries if Busy. Default=5

Conversation

Base, Phone

Read-only

Auto-set during Create.

DetectTransferLoop

Base, Phone

Read/Write

Flags if Transfer Loop Detection is Enabled. Default=false

DeviceName

All

Read/Write

Friendly name for the Device type (not shown in CUCA or CPCA). Default="Other"

DialDelay

Base, Phone, Pager

Read/Write

Time in seconds to wait after Connect before dialing AfterDialDigits (ignored if no AfterDialDigits). Default=1

ObjectId of next Notification Device to use if this one fails (to chain Notifications). Default=null

InitialDelay

All

Read/Write

Time in minutes to wait after a Message is received before Notification is triggered. Default=0

MaxBody

All

Read/Write

Maximum number of characters in the Body of a Notification message. Default=512

MaxSubject

All

Read/Write

Maximum number of characters in the Subject of a Notification message. Default=64

MediaSwitchObjectId

Base, Phone, Pager

Read/Write

ObjectId of the Phone System to use for the Dial-out.

PhoneNumber

Base, Phone, Pager

Read/Write

Phone Number to dial to reach the Device.

PromptForId

Base, Phone

Read/Write

Flags if the User must enter their ID to get the Notification message. Default=false

RecipientAddress

SMS

Read/Write

Address of Message recipient

RepeatInterval

All

Read/Write

Time in minutes to wait before re-notifying of messages. Default=0

RepeatNotify

All

Read/Write

Flags if Notification process should begin for each newly arrived message. Default=false

RetriesOnBusy

Base, Phone, Pager

Read/Write

Number of retry attempts if Busy. Default=4

RetriesOnRna

Base, Phone, Pager

Read/Write

Number of retry attempts if RNA. Default=4

RetriesOnSuccess

Base, Pager

Read/Write

Number of retry attempts if successful. Default=0

RingsToWait

Base, Phone, Pager

Read/Write

Number of rings to wait for Connect before RNA. Default=4

RnaRetryInterval

Base, Phone, Pager

Read/Write

Time in minutes to wait between retries if RNA. Default=5

ScheduleSetObjectId

All

Read/Write

ObjectId of the ScheduleSet during which Notification may trigger. Default=AllHours

SendCallerId

Base, Pager, SMS, SMTP

Read/Write

Flag to include CallerId in the Notification message. Default=true

SendCount

Base, Pager, SMS, SMTP

Read/Write

Flag to include the message counts in the Notification message. Default=true

SenderAddress

SMS

Read/Write

Address of Message sender. Default=null

SendPcaLink

Base, SMTP

Read/Write

Flag to include a link to CPCA in the Notification message. Default=false

SmppProviderObjectId

Base, SMS

Read/Write

ObjectId of the SMPP Provider

SmtpAddress

Base, SMTP

Read/Write

SMTP address to send the Notification message to

StaticText

Base, SMS, SMTP

Read/Write

Static text to include in the Notification Message. Default=null

SubscriberObjectId

All

Read-only

ObjectId of the User

SuccessRetryInterval

Base, Pager

Read/Write

Time in minutes to wait between retries if successful. Default=0

TransmitForcedAuthorizationCode

Base, Phone, Pager

Read/Write

Flags if an authorization code should be sent to CUCM after the PhoneNumber is dialed. Default=false

Undeletable

All

Read-only

Factory default=true. For newly-created, default=false

WaitConnect

Base, Phone, Pager

Read/Write

Flags if need to wait for Connect before dialing AfterDialDigits. Default=true

The EventList field is a comma-delimited list of Message types which could trigger Notification. It can contain any of the following values. Note that Calendar Appointments and Meetings are not included in the AllMessage or AllUrgentMessage categories, which just include voicemail, fax, and dispatch messages.