Skip to contentSkip to navigationSkip to topbar
On this page

Notifications Framework


(information)

This page applies to Flex UI 1.x.x.

For the Flex UI 2.x.x version of this content, see the Work with Notifications.

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


What is a notification in Flex?

what-is-a-notification-in-flex page anchor

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, browser notifications, or both.


What are notification framework capabilities?

what-are-notification-framework-capabilities page anchor
  • 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 is an in-app way to alert user. NotificationBar has a variety of options like icon, actions, and timeout. To learn more, see the Notification Object properties(link takes you to an external page) in the Flex UI API Reference.

NotificationBar.

Flex uses the standard Browser Notification API(link takes you to an external page) as the basis for its browser notifications implementation. You can turn on browser notifications in the Flex UI Admin Dashboard.

Browser notifications are shown if Flex is not in focus or is minimized.

(warning)

Notifications in iframes

Due to security constraints across browsers(link takes you to an external page), Browser Notifications are not supported when Flex is iframed within a cross-domain webpage. This includes the Salesforce and Zendesk integrations.

Request permissions

request-permissions page anchor

To start showing browser notifications, Flex first needs to get user permission. By default, Flex requests user permission if they haven't been granted or blocked.

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


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

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

Browser notifications handler

browser-notifications-handler page anchor

To display a browser notification, use the options key with a browser tag in it. The Flex UI 1.x.x API Reference contains an exhaustive list of available properties(link takes you to an external page). If no browser key is passed to options, Flex will not show any browser notifications.


Working with Notifications

working-with-notifications page anchor

Register a custom notification with Browser notification handler

register-a-custom-notification-with-browser-notification-handler page anchor
1
Flex.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"
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

override-standard-notifications-for-a-specific-task-type-using-task-channel-definitions-api page anchor

Use custom notification for new reservation of a call task

use-custom-notification-for-new-reservation-of-a-call-task page anchor
1
Flex.DefaultTaskChannels.Call.notifications.override.IncomingTask = () => {
2
Flex.Notifications.showNotification("customNotification");
3
}

Change content of a standard notification for incoming call task

change-content-of-a-standard-notification-for-incoming-call-task page anchor
1
Flex.DefaultTaskChannels.Call.notifications.override.IncomingTask = (notification) => {
2
notification.content: "Hello, world!";
3
};

Change content of a standard notification for new chat message

change-content-of-a-standard-notification-for-new-chat-message page anchor
1
Flex.DefaultTaskChannels.Call.notifications.override.NewChatMessage = (notification) => {
2
notification.content = "Hello, world!";
3
};

Turn off standard notifications

turn-off-standard-notifications page anchor

Do not show notificationBar notifications

do-not-show-notificationbar-notifications page anchor
MainContainer.defaultProps.showNotificationBar = false;

Disable notification by ID

disable-notification-by-id page anchor
Notifications.registeredNotifications.delete("notification_id");

Customize standard notifications

customize-standard-notifications page anchor

Change text of the notification

change-text-of-the-notification page anchor
1
const notification = Notifications.registeredNotifications.get("notificationId");
2
notification.content = "Display some text";

Change text of the notification with template

change-text-of-the-notification-with-template page anchor
1
manager.strings.myNotification = "Current time: {{time}}"
2
const notification = Notifications.registeredNotifications.get("notificationId");
3
notification.content = "myNotification";
4
Notifications.showNotification("notificationId", {time: Date.now()})

Read more about templates in Localization and UI templating.

Render a custom component in a notification

render-a-custom-component-in-a-notification page anchor
1
const notification = Notifications.registeredNotifications.get("notificationId");
2
notification.content = <MyAwesomePopup/>;

Change the properties of a notification

change-the-properties-of-a-notification page anchor
1
const notification = Notifications.registeredNotifications.get("PendingReservationsOnActivityStateChange");
2
notification.content = "Some text to display";
3
notification.backgroundColor = "blue";
4
notification.closeButton = false;

Register Custom Notifications

register-custom-notifications page anchor
1
Notifications.registerNotification({
2
id: "myNotificationId",
3
content: "Custom content", // string
4
type: NotificationType.error
5
});
1
Notifications.registerNotification({
2
id: "myNotificationId",
3
content: "NotificationMessage", // template
4
type: NotificationType.error
5
});

Read more about templates in Localization and UI templating.

Option 3: custom React component

option-3-custom-react-component page anchor
1
interface CustomNotificationProps extends NotificationContentProps {
2
customProp?: string;
3
notificationContext?: any;
4
}
5
6
export 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
20
Notifications.registerNotification({
21
id: "myNotificationId",
22
content: <CustomNotificationElement customProp="custom prop" />,
23
type: NotificationType.error
24
}
25
);

Dispatch Custom Notifications

dispatch-custom-notifications page anchor
Notifications.showNotification("myNotificationId", null);

Option 2 & 3: template & custom React component

option-2--3-template--custom-react-component page anchor
Notifications.showNotification("myNotificationId", { message: "custom context" } );

Add custom notification event listeners

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

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.