Push Notifications

Introduction

Avaya Experience Platform™ allows you to integrate with Push Notification services of your choice or Push Notification services that your client application might be already using. This will enable your customers to receive notification related to an on-going conversation on their devices and allow them to re-engage if they had terminated the app or put it in background.

📘

Info

Custom Push Notification is not supported with Web (JavaScript) SDK. It is currently only supported with Android SDK.

Overview

To integrate Avaya Experience Platform™ with a Push Notification service of your choice, a Custom Push Notification Connector, also known as a Push Proxy needs to be built that can receive Push Notifications sent by Avaya Experience Platform™ and send them to the actual Push Notification Service. The Connector can be a separate service or a piece of code running on any of your existing backend services.

The below diagrams gives an overview of how the Push Notification works. The following sections describe the steps in detail. Note that the steps related to Push Notification Service have been shown based on how Push Notification Providers work in general. The steps may vary based on the Push Notification Provider you are integrating with.

Configuring Push Notification

1. For your client application to use push notifications, you might need to register your app on the Push Notification Provider Service
2. You might need to configure your client application with details of the Push Notification Service so that it can connect and register to the the Push Notification Provider Service.
3. You might need to also configure the Custom Push Notification Connector (Custom Push Proxy) so that it too can connect to your Push Notification Provider Service.
4. The Account Administrator must create a Push Notification Configuration on the Avaya Experience Platform™ Administration application. The following fields are need to be provided to create a configuration:
   • Name : A user friendly name that to recognize the configuration
   • Callback URL :The URL hosted by your Custom Push Notification Connector on which Avaya Experience Platform™ will send Notification events.
   • Secret: A shared secret key between Avaya Experience Platform™ and your Custom Push Notification Connector so that the Connector can validate that the request containing Push Notification Event was sent by Avaya Experience Platform™. Details on how to perform the validation is covered in this section

Here are the steps to create the Push Notification Configuration:

1. Go to your Avaya Experience Platform™ Administration application
2. Sign in as an Account (Tenant) Administrator
3. Navigate to Contact Center > Push Notifications
4. Click on “Add New Configuration” button.
5. Provide the “Name”, “Callback URL” and the “Secret” and save the Configuration.
6. Once the integration is saved successfully, a “Configuration Id” field will appear.

The Configuration Id needs to be passed to the Avaya Omni SDK as a configuration parameter.

Registering Device Session

Avaya Experience Platform™ sends Push Notifications only when it detects that the Avaya Omni SDK session got disconnected. The situation could be for various reasons like user’s device getting disconnected from network, or user terminating the client application, etc.

1. When Avaya Experience Platform™ sends a Push Notification to your Push Notification Connector, it will contain the Avaya Experience Platform™ Session Id as part of the notification data.
   The notification data sent by Avaya Experience Platform™ will only contain metadata and never contain the actual content of the event like messages.
   Here is an example of the payload of the request Avaya Experience Platform™ sends to the Callback URL of the Connector.

{
    "eventId": "778af6a9-41f8-4153-a3a1-d913b2911b3b",
    "conversationId": "1570b603-502e-3dcc-888f-09dda5bd0ea6",
    "customerId": "customer-id-12345",
    "sessionId": "bf813a5d-2e06-4047-bae2-e01da2f69f7c",
    "eventDate": "2024-03-18T11:00:24.481Z"
}

2. The Connector should be able to derive the corresponding Device Token and send the request to your Push Notification Provider.
3. The Push Notification Provider will forward the notification to the user’s device.
4. On receiving the notification, the device will execute your client application logic to provide the content of the notification to be displayed to the user.
5. As part of this logic, your client application must invoke the method provided by the Avaya Omni SDK to retrieve the notification contents from Avaya Experience Platform™.

Avaya Experience Platform™ does not retry to send back the Push Notification if it fails to send the callback request to the Custom Push Notification Connector or the Connector responds with an error.

Avaya Experience Platform™ will back-off from sending requests to the Connector if it continuously receives error responses from the Connector over a specific period of time and again attempt sending new push notification after a cool down period. The only exception is when the Connector returns a 400 (Bad Request) or 500 (Internal Server Error) response.

Your may want to show push notifications when the customer has moved away from the Messaging screen or the customer has moved to a different application but your client application is still running in the background (with Omni SDK still connected to Avaya Experience Platform™). In these circumstances, Avaya Experience Platform™ will not send push notifications. Your client application needs to continue listening to events from Omni SDK and appropriately show them as push notifications if the customer has moved away from the Messaging screen.

Validating Push Notification Callback Request (Optional)

When your Custom Push Notification Connector receives Push Notification Events on the Callback URL, it can validate if the request really came from Avaya Experience Platform™. For this, your Account Administrator must provide the ‘Secret’ while creating and updating the Push Notification Configuration in the Avaya Experience Platform™ Administration application and share the ‘Secret’ with Connector. For every request sent to the Callback URL, Avaya Experience Platform™ calculates HMAC-SHA256 of eventId concatenated with sessionId of the Notification Event data and ‘Secret’ as the key. The result is sent as the value of header X-hmac in every request. As the ‘Secret’ is shared with the Connector, it can also calculate the HMAC-SHA256 and validate if the result is same as the X-hmac value received in the request to make sure the source of the request is Avaya Experience Platform™.

Here is an example on the validation can be performed on the Custom Push Notification Connector:

var crypto = require('crypto');

/*
* Create the hmac object. 
* Set the hash function as SHA 256. 
* Set the key as the secret shared by Account Administrator
*/
var hmac = crpto.createHmac('sha256','<Secret>');

/* 
* Concatenate eventId and sessionId in the data 
* received in the callback request sent by
* Avaya Experience Platform™ as the data to be hashed
*/
data = hmac.update(req.body.eventId + req.body.sessionId)

//Generate the hmac
gen_hmac= data.digest('hex');

/*
* Validate generated HMAC-SHA256 against x-hamc 
* header received in the request
*/
if (req.headers['X-hmac'] === gen_hmac) {
    // Valid source, process the request
} else {
    // Not a valid source. Return 401 Unauthorized as the response
}

Sample Firebase Cloud Messaging (FCM) based Push Notification Connector

To help you build your Custom Push Notification Connector, a sample Connector that is capable of connecting to FCM is available for reference here. You can refer the code to built your own Connector or run the Node.js application (after providing some basic configuration) to quickly test Push Notification for your Client Application. Note that this is just a sample application and not meant to be directly used in production.