Work with Notifications

Flex UI provides a client-side API to manage notifications in Flex UI.

What is a notification in Flex?

A notification is an alert that tells the user what state change or error has occurred to a component or page when they are no longer viewing that component or page

Users can be notified in Flex using a Notification Bar or Browser notifications or both.

With notifications framework, you can:

Register custom notifications including browser notifications
Customize standard notifications
Turn off standard UI notifications
Override standard notifications per Task Channel Definition
Customize how standard UI notifications are displayed
Register your custom UI notifications and specify how to render them

NotificationBar

NotificationBar is an in-app way to alert user. NotificationBar has a variety of options like icon, actions, timeout.

Browser Notifications

Flex uses the standard Browser Notification API as the basis for its browser notifications implementation. Browser notifications can be enabled in the Admin Dashboard of the Flex UI.

Browser notifications are shown if Flex is minimized.

Note, due to security constraints across browsers, Browser Notifications are not supported when Flex is iframed within a cross-domain webpage. This includes the Salesforce and Zendesk integrations.

Requesting permissions

To start showing browser notifications, the user needs to first grant permissions. By default, Flex will request user for permissions if they are not granted or blocked.

If you want to add custom logic around requesting permissions, like request it based on some user action in the UI, then you can dispatch Notification.requestPermission() from your custom code.

Browser notifications handler

To display a browser notification, use the options key with a browser tag in it. Flex API docs contain an exhaustive list of available properties. If no browser key is passed to options, Flex will not show any browser notifications.

NotificationBar actions

A helper component NotificationBar.Action, that can be used for providing clickable action to notification definition.

1interface NotificationBarActionProps {
2    label: React.ReactText; // Can be simple text string or a template string
3    onClick: NotificationBarActionCallback;
4    icon?: string;
5}

The full reference for the Notification Manager and a list of standard notifications are available in Flex API docs.

Register a custom notification with Browser notification handler

1Flex.Notifications.registerNotification({
2    id: "customNotification",
3    closeButton: true,
4    content: "Custom Notification",
5    timeout: 0,
6    type: NotificationType.warning,
7    actions: [
8        <NotificationBar.Action
9            onClick={(_, notification) => {
10                Flex.Notifications.dismissNotification(notification);
11            }}
12            label="Hello World"
13            icon="Bell"
14        />
15    ],
16    options: {
17      browser: {
18          title: "Custom Notification",
19          body: "Hello World!"
20      }
21  }
22});

Override standard notifications for a specific task type using Task Channel Definitions API

Use custom notification for new reservation of a Call task

1Flex.DefaultTaskChannels.Call.notifications.override.IncomingTask = () => {
2  Flex.Notifications.showNotification("customNotification");
3}

Change content of a standard notification for incoming call task

1const originalIncomingTaskNotification = Flex.DefaultTaskChannels.Call.notifications.override.IncomingTask;
2Flex.DefaultTaskChannels.Call.notifications.override.IncomingTask = (notification, cancel) => {
3  originalIncomingTaskNotification(notification, cancel);
4  notification.content = "Some text";
5};

Change content of a standard notification for new chat message

1const originalIncomingTaskNotification = Flex.DefaultTaskChannels.Chat.notifications.override.IncomingTask;
2Flex.DefaultTaskChannels.Chat.notifications.override.IncomingTask = (notification, cancel) => {
3  Object.assign(notification, {
4    ...originalIncomingTaskNotification,
5    content: "some text"
6  });
7};

Turn off Standard Notifications

Do not show notificationBar notifications

Flex.MainContainer.defaultProps.showNotificationBar = false;

Disable notification by ID

Flex.Notifications.registeredNotifications.delete("notification_id");

Customize Standard Notifications

Change text of the notification

1const notification = Flex.Notifications.registeredNotifications.get("notificationId");
2if (notification) {
3   notification.content = "Display some text";
4}

Change text of the notification with template

1flex.manager.getInstance().strings.myNotification = "Current time: {{time}}"
2const notification = Flex.Notifications.registeredNotifications.get("notificationId");
3if (notification) {
4  notification.content = "myNotification";
5}
6Flex.Notifications.showNotification("notificationId", {time: Date.now()})

Read more about overriding strings in Overview of Flex UI programmability.

Render custom component in a notification

1const notification = Flex.Notifications.registeredNotifications.get("notificationId");
2if (notification) {
3   notification.content = <MyAwesomePopup/>;
4}

Change props of the notification

1const notification = Flex.Notifications.registeredNotifications.get("PendingReservationsOnActivityStateChange");
2if (notification) {
3   notification.content = "Some text to display";
4   notification.backgroundColor = "blue";
5   notification.closeButton = false;
6}

Register Custom Notifications

Option 1: string

1Flex.Notifications.registerNotification({
2  id: "myNotificationId",
3  content: "Custom content", // string
4  type: NotificationType.error
5});

Option 2: template

1Flex.Notifications.registerNotification({
2  id: "myNotificationId",
3  content: "NotificationMessage", // template
4  type: NotificationType.error
5});

Read more about overriding strings in Overview of Flex UI programmability.

Option 3: custom React component

1interface CustomNotificationProps extends NotificationContentProps {
2   customProp?: string;
3   notificationContext?: any;
4}
5
6export class CustomNotificationElement extends React.Component<CustomNotificationProps, undefined> {
7   render() {
8       const { customProp, notificationContext } = this.props;
9       return(
10           <div>
11               {notificationContext.message}
12               <div />
13               {customProp}
14           </div>
15       );
16   }
17}
18
19
20Flex.Notifications.registerNotification({
21    id: "myNotificationId",
22    content: <CustomNotificationElement customProp="custom prop" />,
23    type: NotificationType.error
24    }
25);

Dispatch Custom Notifications

Option 1: string

Flex.Notifications.showNotification("myNotificationId", undefined);

Option 2 & 3: template & custom React component

Flex.Notifications.showNotification("myNotificationId", { message: "custom context" } );

Add Custom Notification Event Listeners

1import * as Flex from "@twilio/flex-ui";
2
3Flex.Notifications.addListener("beforeAddNotification", (payload) => {
4  console.log("<---beforeTransferTask Listener--->", payload);
5});