Cisco Unity Connection Provisioning Interface (CUPI) API -- Notification Devices

From DocWiki

Revision as of 22:34, 13 December 2010 by Juliew (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Links to Other API pages: Cisco_Unity_Connection_APIs

CUPI Guide Contents
API Overview
Index of All CUPI Documentation

Contents


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:

GET https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices
{noformat}
The following is the response from the above *GET* request.  Notice that this list contains a mix of different types of specialized Devices, since the request was for a list of all Notification Devices.  The Type field indicates the specialized Device type for each Notification Device (1 = Phone, 2 = Pager, 4 = SMTP, 5 = SMS).
{noformat}
200
OK

<?xml version="1.0" encoding="UTF-8"?>
<NotificationDevices total="5">
  <NotificationDevice>
    <URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/2b13dda8-6249-45b2-9a87-aba1b27a1f95</URI>
    <SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
    <UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
    <ObjectId>2b13dda8-6249-45b2-9a87-aba1b27a1f95</ObjectId>
    <DisplayName>Pager</DisplayName>
    <Active>false</Active>
    <BusyRetryInterval>5</BusyRetryInterval>
    <Type>2</Type>
    <DialDelay>1</DialDelay>
    <MaxBody>512</MaxBody>
    <MaxSubject>64</MaxSubject>
    <RetriesOnBusy>4</RetriesOnBusy>
    <RetriesOnRna>4</RetriesOnRna>
    <RingsToWait>4</RingsToWait>
    <RnaRetryInterval>15</RnaRetryInterval>
    <SendCount>true</SendCount>
    <WaitConnect>true</WaitConnect>
    <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
    <PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
    <TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
    <DeviceName>Pager</DeviceName>
    <PromptForId>false</PromptForId>
    <SendCallerId>true</SendCallerId>
    <SendPcaLink>false</SendPcaLink>
    <Undeletable>true</Undeletable>
    <MediaSwitchDisplayName>PhoneSystem</MediaSwitchDisplayName>
    <DetectTransferLoop>false</DetectTransferLoop>
    <SuccessRetryInterval>1</SuccessRetryInterval>
    <RetriesOnSuccess>0</RetriesOnSuccess>
    <EventList>NewVoiceMail</EventList>
    <ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
    <InitialDelay>0</InitialDelay>
    <RepeatInterval>0</RepeatInterval>
    <RepeatNotify>false</RepeatNotify>
  </NotificationDevice>
  <NotificationDevice>
    <URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/0f4ce029-1939-4ae0-9dee-9d84c77fadae</URI>
    <SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
    <UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
    <ObjectId>0f4ce029-1939-4ae0-9dee-9d84c77fadae</ObjectId>
    <DisplayName>Home Phone</DisplayName>
    <Active>false</Active>
    <BusyRetryInterval>5</BusyRetryInterval>
    <Conversation>SubNotify</Conversation>
    <Type>1</Type>
    <DialDelay>1</DialDelay>
    <MaxBody>512</MaxBody>
    <MaxSubject>64</MaxSubject>
    <RetriesOnBusy>4</RetriesOnBusy>
    <RetriesOnRna>4</RetriesOnRna>
    <RingsToWait>4</RingsToWait>
    <RnaRetryInterval>15</RnaRetryInterval>
    <SendCount>false</SendCount>
    <WaitConnect>true</WaitConnect>
    <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
    <PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
    <TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
    <DeviceName>Home Phone</DeviceName>
    <PromptForId>false</PromptForId>
    <SendCallerId>false</SendCallerId>
    <SendPcaLink>false</SendPcaLink>
    <Undeletable>true</Undeletable>
    <MediaSwitchDisplayName>PhoneSystem</MediaSwitchDisplayName>
    <DetectTransferLoop>false</DetectTransferLoop>
    <SuccessRetryInterval>0</SuccessRetryInterval>
    <RetriesOnSuccess>0</RetriesOnSuccess>
    <EventList>NewVoiceMail</EventList>
    <ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
    <InitialDelay>0</InitialDelay>
    <RepeatInterval>0</RepeatInterval>
    <RepeatNotify>false</RepeatNotify>
  </NotificationDevice>
  <NotificationDevice>
    <URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/878de0bf-9169-4ef7-afe4-ec82998c2322</URI>
    <SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
    <UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
    <ObjectId>878de0bf-9169-4ef7-afe4-ec82998c2322</ObjectId>
    <DisplayName>Mobile Phone</DisplayName>
    <Active>false</Active>
    <BusyRetryInterval>5</BusyRetryInterval>
    <Conversation>SubNotify</Conversation>
    <Type>1</Type>
    <DialDelay>1</DialDelay>
    <MaxBody>512</MaxBody>
    <MaxSubject>64</MaxSubject>
    <RetriesOnBusy>4</RetriesOnBusy>
    <RetriesOnRna>4</RetriesOnRna>
    <RingsToWait>4</RingsToWait>
    <RnaRetryInterval>15</RnaRetryInterval>
    <SendCount>false</SendCount>
    <WaitConnect>true</WaitConnect>
    <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
    <PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
    <TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
    <DeviceName>Mobile Phone</DeviceName>
    <PromptForId>false</PromptForId>
    <SendCallerId>false</SendCallerId>
    <SendPcaLink>false</SendPcaLink>
    <Undeletable>true</Undeletable>
    <MediaSwitchDisplayName>PhoneSystem</MediaSwitchDisplayName>
    <DetectTransferLoop>false</DetectTransferLoop>
    <SuccessRetryInterval>0</SuccessRetryInterval>
    <RetriesOnSuccess>0</RetriesOnSuccess>
    <EventList>NewVoiceMail</EventList>
    <ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
    <InitialDelay>0</InitialDelay>
    <RepeatInterval>0</RepeatInterval>
    <RepeatNotify>false</RepeatNotify>
  </NotificationDevice>
  <NotificationDevice>
    <URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/3a314c33-a69f-4179-a260-0c84a4520b3b</URI>
    <SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
    <UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
    <ObjectId>3a314c33-a69f-4179-a260-0c84a4520b3b</ObjectId>
    <DisplayName>Work Phone</DisplayName>
    <Active>true</Active>
    <AfterDialDigits>1701</AfterDialDigits>
    <BusyRetryInterval>5</BusyRetryInterval>
    <Conversation>SubNotify</Conversation>
    <Type>1</Type>
    <DialDelay>1</DialDelay>
    <MaxBody>512</MaxBody>
    <MaxSubject>64</MaxSubject>
    <PhoneNumber>3475</PhoneNumber>
    <RetriesOnBusy>4</RetriesOnBusy>
    <RetriesOnRna>4</RetriesOnRna>
    <RingsToWait>4</RingsToWait>
    <RnaRetryInterval>15</RnaRetryInterval>
    <SendCount>false</SendCount>
    <WaitConnect>false</WaitConnect>
    <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
    <PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
    <TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
    <DeviceName>Work Phone</DeviceName>
    <PromptForId>true</PromptForId>
    <SendCallerId>false</SendCallerId>
    <SendPcaLink>false</SendPcaLink>
    <Undeletable>true</Undeletable>
    <MediaSwitchDisplayName>PhoneSystem</MediaSwitchDisplayName>
    <DetectTransferLoop>false</DetectTransferLoop>
    <SuccessRetryInterval>0</SuccessRetryInterval>
    <RetriesOnSuccess>0</RetriesOnSuccess>
    <EventList>AllMessage</EventList>
    <ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
    <InitialDelay>5</InitialDelay>
    <RepeatInterval>15</RepeatInterval>
    <RepeatNotify>true</RepeatNotify>
    <FailDeviceObjectId>0f4ce029-1939-4ae0-9dee-9d84c77fadae</FailDeviceObjectId>
  </NotificationDevice>
  <NotificationDevice>
    <URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/3e7f802b-d707-489f-b241-399ab67a0dc3</URI>
    <SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
    <UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
    <ObjectId>3e7f802b-d707-489f-b241-399ab67a0dc3</ObjectId>
    <DisplayName>SMTP</DisplayName>
    <Active>false</Active>
    <BusyRetryInterval>0</BusyRetryInterval>
    <Type>4</Type>
    <DialDelay>0</DialDelay>
    <MaxBody>512</MaxBody>
    <MaxSubject>64</MaxSubject>
    <RetriesOnBusy>0</RetriesOnBusy>
    <RetriesOnRna>0</RetriesOnRna>
    <RingsToWait>0</RingsToWait>
    <RnaRetryInterval>0</RnaRetryInterval>
    <SendCount>true</SendCount>
    <WaitConnect>false</WaitConnect>
    <TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
    <DeviceName>SMTP</DeviceName>
    <PromptForId>false</PromptForId>
    <SendCallerId>true</SendCallerId>
    <SendPcaLink>false</SendPcaLink>
    <Undeletable>true</Undeletable>
    <DetectTransferLoop>false</DetectTransferLoop>
    <SuccessRetryInterval>0</SuccessRetryInterval>
    <RetriesOnSuccess>0</RetriesOnSuccess>
    <EventList>NewVoiceMail</EventList>
    <ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
    <InitialDelay>0</InitialDelay>
    <RepeatInterval>0</RepeatInterval>
    <RepeatNotify>false</RepeatNotify>
  </NotificationDevice>
</NotificationDevices>


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.

200
OK

<?xml version="1.0" encoding="UTF-8"?>
<PhoneDevices total="3">
  <PhoneDevice>
    <URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/phonedevices/3a314c33-a69f-4179-a260-0c84a4520b3b</URI>
    <TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
    <AfterDialDigits>1701</AfterDialDigits>
    <BusyRetryInterval>5</BusyRetryInterval>
    <Conversation>SubNotify</Conversation>
    <DialDelay>1</DialDelay>
    <PhoneNumber>3475</PhoneNumber>
    <RetriesOnBusy>4</RetriesOnBusy>
    <RetriesOnRna>4</RetriesOnRna>
    <RingsToWait>4</RingsToWait>
    <RnaRetryInterval>15</RnaRetryInterval>
    <WaitConnect>false</WaitConnect>
    <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
    <PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
    <ObjectId>3a314c33-a69f-4179-a260-0c84a4520b3b</ObjectId>
    <Active>true</Active>
    <DeviceName>Work Phone</DeviceName>
    <DisplayName>Work Phone</DisplayName>
    <MaxBody>512</MaxBody>
    <MaxSubject>64</MaxSubject>
    <SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
    <UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
    <PromptForId>true</PromptForId>
    <Undeletable>true</Undeletable>
    <DetectTransferLoop>false</DetectTransferLoop>
    <EventList>AllMessage</EventList>
    <ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
    <InitialDelay>5</InitialDelay>
    <RepeatInterval>15</RepeatInterval>
    <RepeatNotify>true</RepeatNotify>
    <FailDeviceObjectId>0f4ce029-1939-4ae0-9dee-9d84c77fadae</FailDeviceObjectId>
  </PhoneDevice>
  <PhoneDevice>
    <URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/phonedevices/0f4ce029-1939-4ae0-9dee-9d84c77fadae</URI>
    <TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
    <BusyRetryInterval>5</BusyRetryInterval>
    <Conversation>SubNotify</Conversation>
    <DialDelay>1</DialDelay>
    <RetriesOnBusy>4</RetriesOnBusy>
    <RetriesOnRna>4</RetriesOnRna>
    <RingsToWait>4</RingsToWait>
    <RnaRetryInterval>15</RnaRetryInterval>
    <WaitConnect>true</WaitConnect>
    <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
    <PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
    <ObjectId>0f4ce029-1939-4ae0-9dee-9d84c77fadae</ObjectId>
    <Active>false</Active>
    <DeviceName>Home Phone</DeviceName>
    <DisplayName>Home Phone</DisplayName>
    <MaxBody>512</MaxBody>
    <MaxSubject>64</MaxSubject>
    <SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
    <UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
    <PromptForId>false</PromptForId>
    <Undeletable>true</Undeletable>
    <DetectTransferLoop>false</DetectTransferLoop>
    <EventList>NewVoiceMail</EventList>
    <ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
    <InitialDelay>0</InitialDelay>
    <RepeatInterval>0</RepeatInterval>
    <RepeatNotify>false</RepeatNotify>
  </PhoneDevice>
  <PhoneDevice>
    <URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/phonedevices/878de0bf-9169-4ef7-afe4-ec82998c2322</URI>
    <TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
    <BusyRetryInterval>5</BusyRetryInterval>
    <Conversation>SubNotify</Conversation>
    <DialDelay>1</DialDelay>
    <RetriesOnBusy>4</RetriesOnBusy>
    <RetriesOnRna>4</RetriesOnRna>
    <RingsToWait>4</RingsToWait>
    <RnaRetryInterval>15</RnaRetryInterval>
    <WaitConnect>true</WaitConnect>
    <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
    <PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
    <ObjectId>878de0bf-9169-4ef7-afe4-ec82998c2322</ObjectId>
    <Active>false</Active>
    <DeviceName>Mobile Phone</DeviceName>
    <DisplayName>Mobile Phone</DisplayName>
    <MaxBody>512</MaxBody>
    <MaxSubject>64</MaxSubject>
    <SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
    <UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
    <PromptForId>false</PromptForId>
    <Undeletable>true</Undeletable>
    <DetectTransferLoop>false</DetectTransferLoop>
    <EventList>NewVoiceMail</EventList>
    <ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
    <InitialDelay>0</InitialDelay>
    <RepeatInterval>0</RepeatInterval>
    <RepeatNotify>false</RepeatNotify>
  </PhoneDevice>
/PhoneDevices>


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:

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

<PhoneDevice>
  <DisplayName>My New Phone</DisplayName>
  <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
  <PhoneNumber>5551212</PhoneNumber>
  <InitialDelay>10</InitialDelay>
</PhoneDevice>

The following is the response from the above POST request:

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.

POST https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/pagerdevices

<PagerDevice>
  <DisplayName>My New Pager</DisplayName>
  <MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
  <PhoneNumber>8675309</PhoneNumber>
  <Active>false</Active>
</PagerDevice>

The following is the response from the above POST request:

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".

POST https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/smsdevices

<SmsDevice>
  <DisplayName>My New SMS Device</DisplayName>
  <SmppProviderObjectId>60cd37e8-499c-43a3-b733-30f2640e5003</SmppProviderObjectId>
  <RecipientAddress>bob@xyz.com</RecipientAddress>
  <SenderAddress>voicemail@xyz.com</SenderAddress>
</SmsDevice>

The following is the response from the above POST request:

201
Created
/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/smsdevices/ac200457-284c-4951-b04a-4d76bd03235e


Creating SMTP Devices

The required fields for creating an SMTP Device are DisplayName and SmtpAddress. All other SMTP Device fields are optional.

The following is an example of a POST that creates an SMTP Device with DisplayName="My New SMTP Device", SmtpAddress="sylvia@email.com", and optional parameter EventList="AllMessages".

POST https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/smtpdevices

<SmtpDevice>
  <DisplayName>My New SMTP Device</DisplayName>
  <SmtpAddress>sylvia@email.com</SmtpAddress>
  <EventList>AllMessage</EventList>
</SmtpDevice>

The following is the response from the above POST request:

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.

PUT https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/phonedevices/2e377eba-a924-434b-b967-bac3815551d3

<PhoneDevice>
  <FailDeviceObjectId>ac200457-284c-4951-b04a-4d76bd03235e</FailDeviceObjectId>
</PhoneDevice>

The following is the response from the above PUT request:

204
No Content

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:

DELETE https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/phonedevices/2e377eba-a924-434b-b967-bac3815551d3

The following is the response from the above DELETE request:

204
No Content


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
DisplayName All Read/Write Friendly name for the Device like "Mobile Phone"
EventList All Read/Write Comma-delimited list of Events that trigger Notification (see below). Default=NewVoiceMail
FailDeviceObjectid All Read/Write 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.

Event Name Description
None No messages of any type or urgency
AllMessage All messages of all types and urgencies
AllUrgentMessage All urgent messages of all types
CalendarAppointment Calender appointments
CalendarMeeting Calendar meetings
DispatchMessage All dispatch messages
UrgentDispatchMessage All urgent dispatch messages
NewFax All fax messages
NewUrgentFax All urgent fax messages
NewVoiceMail All voicemail messages
NewUrgentVoiceMail All urgent voicemail messages

Rating: 0.0/5 (0 votes cast)

Personal tools