sendNotification

Sends (or schedules) a push notification to a groups of users. Initially (29/8/2016) it only supports Events (all Accepted attendees) but future versions will support many other push notification types. User must be SUPER_USER, COMPANY_ADMIN (connected to NI company), or EVENT_PUSH_NOTIFICATION_ROLE (connected to MI company).

As of SAM-20190903 this API supports:

• Scheduling notifications for sending at future date/times via attributes scheduleTimezoneId, scheduleLocalDateTime, and scheduleJobName -Sending of a URL (either deeplink or normal)

As of SAM-20200319 this API supports the optional sending of emails to usere via a pre-configured email template (which must be setup prior to usage obviously). The request object has thus been updated to pass: emailTemplate, emailSubject, and emailParams

As of SAM-20200508 this API now supports type="GA" for "Generic Asset Notifications". This works the same as "Send Push Notification" from the Add/Edit Asset dialog in SAM. The request object has been updated to pass: campaignTagId, updateEntityLastModified. NOTE: under the covers we now send all adhoc notifications via the scheduled mechanism so it returns faster to the caller and runs as a background task on the BATCH server, sending an email to SAM admins when complete (success or failure).

As of SAM-20201117 we can now support large HTML bodies if the following email template is used Client.Generic.HTMLBody.Mandrill.html.

As of SAM-20211014 the Client.Generic.HTMLBody.Mandrill.html remail template supports an additional (yet optional) parameter unsubcribeURL

As of SAM-20230112 added support for type="UN" for User Notification intended for an individual end user but could be up to 10 users.

Request

POST /rest/notification/send

Headers

Header	Required	Description
x-nextinteract-authtoken	Yes	Auth token returned from loginUser
x-nextinteract-company-api-key	Yes	Admin-specific API key UUID provided to company

Parameters

A JSON request in format below. All fields mandatory. version Version 3 (current) adds ability to schedule notifications and also added url field. Also supports non-schedulable V2 functionality. You can continue to use V2 if you do not need scheduling or url. Version version 2 (non-schedulable) supported as of 21-DEC-2016 and NOT backwardly-compatible Version 1 deprecated as of 21-DEC-2016. Supported type values as of 2018-09-25 are: GE - Generic Events notification. GT - Generic Team Push Notification SN - Smart Library Push Notification JN - Job Notification (added 2019-10-02) GA - Generic Asset Notification (added 2020-05-08) - This works the same as "Send Push Notification" from the Add/Edit Asset dialog in SAM. UN - User Notification (intended for use with order updates to a single user as part of Pfizer Hospital supply chain project)

Parameter	Type	Required	Description
key	String(100)	Yes	The unique id of the group message. For Events (GE) this is the Event "QR Code" UUID. For normal Teams (GT), Job Notification (JN), and Assets (GA) this is the companyId (or cId). For SmartLibrary (SN) this is the smartlibId.
values	Array of Strings	No	A list of one or more team ids as strings. For Events (GE) this is the EventTeamId - teamId from getPublicEventTeams(). For normal Teams (GT) this is the TeamId - teamId from getPublicTeams(). For SmartLibraries (SN) this is one or more smartEntryIds. For Asset Notifications (GA) is not used at all.
message	String(2048)	Yes	The text message to be sent limited to a total of 2048 characters (including URL).
url	String(1024)	No	The optional URL to be sent in the notification (deeplink or normal).
scheduleTimezoneId	String(40)	No	The timezone id of the scheduled notification. Required if scheduling. See RefData APIs - getAllTimezones.
scheduleLocalDateTime	datetime	No	The local date/time in the timezone this notification will be sent. Required if scheduling.
scheduleJobName	String(100)	No	The name of a previously configured job to run on the SAM server. Only used with scheduling.
brochureId	Number	No	Used when the API caller wants to honour User unsubscribes via the ALP (Asset Level Preferences) ALP-NUN (Notification Unsubscribe) and ALP-EUN (Email Unsubscribe). Also used for type=GA to indicate which asset should be used for notifications, in which case it is mandatory.
emailTemplate	String(100)	No	Only used when an email is required to be sent along with the notification.
emailSubject	String(256)	No	Only used when an email is required to be sent along with the notification. MUST be present if emailTemplate is present.
emailBody	String(10000000)	No	Used for certain email templates where a large HTML body will be passed. NOTE: you also need to pass emailBody as a emailParam (with any old value that will not be used) to trigger emailBody to be injected into the template. Please use template Client.Generic.HTMLBody.Mandrill.html for now.
emailParams	Array of Param objects	No	An array of objects representing both "generic (common)" and "personalised (user-specific)" params. NOTE: for "personalised" values such as userFirstName, userLastName, unsubcribeURL the API caller is to pass emailParams with key and value to be the name of the "agreed params". Only userFirstName, desktopURL, interactURL, and unsubcribeURL will be supported so far. In all cases, just set the value to anything and SAM will fill in the real value at runtime. Each param object contains key [String(100), required] and value [String(2000), required].
campaignTagId	Number	No	The PK Id of an existing Tag in SAM which is associated with a given campaign. If passed, the campaign id will be passed into deep links etc.
updateEntityLastModified	Boolean	No	Flag to indicate that the entity (only Brochure, SmartEntry) should have its Last Modified field updated. For type=GA, this will update the Asset's Last Modified date/time. Defaults to false.
userNotificationTypeId	Number	No	Only used for type=UN. Number to indicate the type of message being sent e.g. 7=Order update.
userNotificationTypeStatusId	Number	No	Only used for type=UN. Number to indicate the type order update status to display in the Notification Centre (Red, Amber, Green etc). Values are: 1=Available, 2=Shortage, 3=Depleted, 4=Short Dated.

EXAMPLES:

{ "version": 2, "type": "GE", "key": "ed90fcd2-cbb4-49b8-9be4-a14ccbc2d1e8", "values": ["456", "459"], "message": "This is test message for event team ids 456 and 459" } { "version": 2, "type": "GT", "key": "3", "values": ["23", "27"], "message": "This is test message for team ids 23 and 27" }

{
"version": 4,
"type": "UN",
"key": "3",
"values": [
"aaron.mcmullen@hypermedia.com.au"
],
"message": "PFIZER ORDER UPDATE - Order 123456 hs SHIPPED",
"emailParams": [],
"brochureId": 4,
"updateEntityLastModified": false,
"userNotificationTypeId": 7,
"userNotificationTypeStatusId": 1
}

Response

200 OK

Version 2 and below HTTP response contains the total number of messages sent as an integer inside the HTTP BODY. Unsure why we did it this way but hey.

Version 3 Returns same JSON payloads for both "adhoc" and "scheduled" notifications.

{
  "notificationScheduleId": 123
}

Where notificationScheduleId is the PK of created scheduled notification.

Errors

Exception	Description
WSInvalidParameterException	See Error Definitions
WSInvalidAuthTokenException	See Error Definitions
WSCacheServiceException	See Error Definitions
WSInsufficientPermissionsException	See Error Definitions
WSEventServiceException	See Error Definitions
WSInternalException	See Error Definitions
WSSmartLibNotFoundException	See Error Definitions
WSSmartLibraryServiceException	See Error Definitions