Contact usRequest a demo

Push notifications

This article describes the events that Unblu publishes push notifications for and the different channels you can use to send push notifications.

Introduction

Push notifications are a great way of maintaining engagement in long-running conversations.

For a person to receive push notifications, they must be a participant in a conversation. Unblu can send push notifications for:

  1. New messages

  2. Incoming audio and video calls

  3. Missed audio and video calls

Push notifications are available for four different channels:

  1. Email via standard SMTP

  2. Mobile devices via Firebase and the Apple Push Notification service (APNs)

  3. Other systems via webhooks

  4. Web push notifications via a third party push service (for agent notifications only)

Push notifications for new messages

Push notifications related to new messages are triggered by two events:

  1. New chat messages sent to a conversation.

  2. Messages in a conversation changing state to "read".

"New message" push notifications

Push notifications regarding new messages are sent to participants when a person or a bot sends a new message to a conversation (system messages are ignored). More specifically, a participant is sent a push notification if:

If a participant receives multiple messages in short succession, they won’t receive a notification for each new message. They’ll only be notified of the last message they received.

For secondary agents and visitors, you can specify when they should be informed of new messages in a conversation with the configuration properties com.unblu.conversation.notification.secondaryAgentNotificationRule and com.unblu.conversation.notification.secondaryVisitorNotificationRule, respectively.

If you want certain participants only to be notified of new messages sent by human participants in a conversation, remove their participation type from com.unblu.conversation.notification.enableNotificationForBotMessages.

"New message" push notifications are on a conversation level. If a person receives new messages in multiple conversations, a notification is sent for each conversation.

"Read message" push notifications

Unblu maintains a count of the "new message" notifications that a participant has received in each conversation they’re participating in. The count is reduced when the participant reads one of the new messages. Unblu sends a "read message" push notification once the notification count for a conversation reaches 0, that is, when the participant no longer has any unread new messages.

"Read message" push notifications aren’t meant to be displayed to the recipient. Rather, they’re intended to be used to invalidate the notification that the participant has new messages.

"Read message" notifications are on a conversation level. A new “read message” push notification only affects the notification count for that conversation.

Push notifications related to incoming audio and video calls are triggered by two events:

  1. New incoming audio and video calls

  2. Revoked audio and video calls, when a call is terminated

If auto join call mode is enabled for the conversation in question, participants don’t receive any push notifications.

"Incoming call" push notifications

"Incoming call" push notifications are sent to participants when another participant in a conversation starts an audio or video call. The other participants' call state changes to “RINGING”, which prompts the push notification.

If the setting com.unblu.conversation.call.forwardToHiddenAgents specifies that the call be forwarded to hidden agents, those agents don’t receive the "incoming call" push notification until the timeout specified in com.unblu.conversation.call.callNotAnsweredTimeoutSeconds has been reached.

"Revoked call" push notifications

"Revoked call" push notifications are sent to participants in an audio or video call when the call has ended and its status changes to "IDLE". Like "read message" push notifications, these notifications are intended to invalidate any "incoming call" notifications a participant received, not to be displayed to participants.

"Missed call" push notifications are sent to participants in a conversation when their call state changes from “RINGING” to “NONE”. This can occur in three situations:

  • The caller hung up before the call was answered.

  • The call wasn’t answered before it timed out.

  • The person called actively declined the call.

In the first two situations, the person or people being called receive a "missed call" push notification. In the last case, no "missed call" push notification is sent.

Notification channels

Before selecting the channels you wish to use for push notifications, you must activate push notifications. To do so set com.unblu.core.push_notification.enablePushNotification to true.

You can specify which participants in a conversation should receive push notification based on their participant type with the configuration property com.unblu.conversation.notification.enablePushNotificationsPerActor.

Email

To activate the email channel for push notifications, set com.unblu.core.push_notification.mail.enableEmailPushNotification to true.

Email push notifications are possible for "new message", "incoming call", and "missed call" events. "Read message" and "revoked call" events don’t result in email notifications.

Unblu must know a person’s email address before it can send them email push notifications. For agents, this information may come from ID propagation or the user database, for example via an LDAP sync. Authenticated visitors, too, may provide their email address by ID propagation. Other visitors may be asked for their email address as part of the concierge’s onboarding process, or they may have provided it as part of a call to the Unblu web API endpoint persons/createOrUpdateVirtual.

Mobile

Unblu uses Firebase for push notifications to devices running Android. For iOS, it uses APNs, although you can use Firebase for iOS push notifications if you prefer. To do so, set com.unblu.mobile.push_notification.enableFirebaseForNonPushKitNotifications to true. You must also set the configuration properties com.unblu.mobile.push_notification.firebaseDatabaseName--this is the firebase project ID and not related to the firebase database product—​and com.unblu.mobile.push_notification.firebaseServiceAccountKey.

For mobile push notifications to work, the following requirements must be fulfilled:

  • The Unblu mobile SDK is integrated into your Android/iOS app.

  • Unblu push notification must be enabled in the mobile SDK.

  • The person who should receive push notifications must have used your app at least once, and Unblu was initialized when they did so.

  • Unblu has received the Firebase device token for the person in question.

  • The Collaboration Server can access the Firebase Cloud Messaging API endpoint, https://https://fcm.googleapis.com.

  • The Collaboration Server can access the APNs endpoints:

    • \api.push.apple.com:443 for development environments

    • \api.sandbox.push.apple.com:443 for production environments

To activate mobile push notifications, set com.unblu.mobile.push_notification.enablePushNotification to true.

For further information on configuring mobile push notifications, refer to Mobile push notifications and the Android and iOS documentation on notifications.

If a person uses your app on multiple devices and the app has authenticated them, they receive push notifications on all their devices.

Webhooks

You can register webhooks to integrate Unblu push notifications into an existing push notification service. This expands the ways in which you can push notifications to your users. For example, you can notify users of events via SMS or by displaying a badge on an element of your website.

To trigger a webhook push notification, you must have an active webhook registration. There are five webhooks you can register for push notifications:

  • push_notification.new_message and push_notification.read_message for push notifications related to new messages

  • push_notification.incoming_call and push_notification.revoked_call for push notifications related to incoming audio and video calls

  • push_notification.missed_call for push notifications related to missed audio and video calls

If Unblu receives any device tokens via the mobile SDK, these are also passed on to the webhook endpoint. This lets you send push notifications to mobile devices using your current push notification infrastructure.

Web push notifications

For agents, Unblu provides an additional channel: web push notifications. Agents can receive web push notifications about certain events even when they aren’t logged in to the Agent Desk. They needn’t even have their browser open to receive notifications.

Web push notifications are available for the following events:

  • New message

  • Forwarded conversation and invitation to a conversation

  • Incoming call

  • Missed call

  • Delegation of a request to a deputy

They differ from other push notifications in some important respects:

  • Web push notifications are only sent if the event is related to a specific agent, not the queue.

  • Only agents can receive Web push notifications, not visitors.

  • Web push notifications only work with the Agent Desk, not the Single Conversation Desk.

Web notifications and web push notifications aren’t the same thing.

  • Web notifications are notifications from the browser that are rendered by the user’s operating system.

  • Web push notifications are web notifications that have been pushed from a server and are shown by a service worker.

Encryption

Because web push notifications are sent via a third party push service (Windows Push Notification Service for Microsoft Edge, Firebase Cloud Messaging for Google Chrome and Mozilla Firefox), push messages sent by Unblu are encrypted twofold:

  1. First, Unblu encrypts the payload of the push message using the shared secret that the Unblu server sent to the agent’s Unblu client during the subscription process. Thus ,the push service can’t read the payload of the notification.

  2. The encrypted payload is then encrypted with the public key of the push service. The Unblu server receives this key from the agent’s Unblu client during the subscription process.

When the service worker running on the agent’s computer receives the notification, it uses the shared secret to decrypt the payload of the notification. If it’s unable to do so, it displays the text defined in com.unblu.core.web_push_notification.unencryptedDefaultNotificationTitle. Clicking the notification opens the Agent Desk and renews the service worker registration.

Prerequisites

  • Web push notifications make use of the Notifications, Push, and Service Worker APIs. Your agents' browsers must support these APIs.

  • Agents mustn’t have disabled notifications for the domain your Unblu installation is running on.

  • Agents must allow notifications in a browser tab that isn’t running in private mode.

  • The push service (Windows Push Notification Service or Firebase Cloud Messaging) and the endpoint Unblu receives for the push service must be reachable from both the agents' browsers and the Unblu server.

  • If you have a firewall between the Unblu server and your agents, make sure it allows the Service-Worker-Allowed HTTP header to pass from the server to the agent’s browser.

Configuring web push notifications

Receiving web push notifications when the browser isn’t running

Once agents allow web push notifications, they can receive notifications even when their browser is closed.

  • With Microsoft Edge, you do so by turning on Startup boost:

    1. Click the menu button Microsoft Edge menu icon and select Settings.

    2. Click System in the left sidebar.

    3. Turn on Startup boost.

    4. Make sure the setting Continue running background apps when Microsoft Edge is closed is on.

  • Unblu provides a browser extension for Google Chrome that allows agents to receive web push notifications when their browser is closed. To use the extension:

    1. Install the extension in Google Chrome.

    2. Click the menu button Google Chrome menu icon and select Settings.

    3. In the left sidebar, click Advanced and select System.

    4. Make sure the setting Continue running background apps when Google Chrome is closed is on.

    If you’re interested in deploying the extension in your organization, contact your Unblu account manager.

Subscription health check

There’s no clear way to make sure that web push notifications the Unblu server sends out actually reach their destination. This isn’t satisfactory if agents rely on web push notifications to keep abreast of their conversations.

To mitigate this issue, Unblu carries out a periodic subscription health check:

  1. The Unblu server tells the service worker that it’s performing a health check.

  2. Next, the Unblu sends an event to the push service.

  3. The service worker on the agent’s computer waits until it receives the health check notification. If it doesn’t receive it within a certain (configurable) time frame, it launches a new subscription process.

You can configure the health check:

  • config.com.unblu.core.web_push_notification.healthCheckIntervalSeconds[] specifies the interval between health checks.

  • config.com.unblu.core.web_push_notification.healthCheckTimeoutMillis[] specifies how long the service worker should wait to receive the health check notification from the push service.

  • config.com.unblu.core.web_push_notification.subscriptionRetryIntervalMillis[] defines the time to wait after resubscribing before Unblu launches another health check.

Pausing push notifications

There may be situations where you don’t want to send agents mobile notifications or web push notifications. How to pause notifications is covered in a separate article.

See also