Menu

Notifications Framework

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

The full reference for the Notification Manager and a list of standard notifications are available in the Autogenerated Flex UI Documentation.

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

What are notification framework capabilities?

  • 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. Learn more in Notification Object properties.

Screenshot 2019-10-07 at 20.17.12.png

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 not in focus or is minimized.

Notifications in iframes

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.

NotificationBar actions

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

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

Browser notifications handler

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

Working with Notifications

Register a custom notification with Browser notification handler

Flex.Notifications.registerNotification({
    id: "customNotification",
    closeButton: true,
    content: "Custom Notification",
    timeout: 0,
    type: NotificationType.warning,
    actions: [
        <NotificationBar.Action
            onClick={(_, notification) => {
                Flex.Notifications.dismissNotification(notification);
            }}
            label="Hello"
            icon="Bell"
        />
    ],
    options: {
      browser: {
          title: "Custom Notification",
          body: "Hello World!"
      }
  }
});

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

Use custom notification for new reservation of a Call task

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

Change content of a standard notification for incoming call task

Flex.DefaultTaskChannels.Call.notifications.override.IncomingTask = (notification) => {
  notification.content: "Hello, world!";
};

Change content of a standard notification for new chat message

Flex.DefaultTaskChannels.Call.notifications.override.NewChatMessage = (notification) => {
  notification.content = "Hello, world!";
};

Turn off Standard Notifications

Do not show notificationBar notifications

MainContainer.defaultProps.showNotificationBar = false;

Disable notification by ID

Notifications.registeredNotifications.delete("notification_id");

Customize Standard Notifications

Change text of the notification

const notification = Notifications.registeredNotifications.get("notificationId");
notification.content = "Display some text";

Change text of the notification with template

manager.strings.myNotification = "Current time: {{time}}"
const notification = Notifications.registeredNotifications.get("notificationId");
notification.content = "myNotification";
Notifications.showNotification("notificationId", {time: Date.now()})

Read more about templates in Localization and UI templating

Render custom component in a notification

const notification = Notifications.registeredNotifications.get("notificationId");
notification.content = <MyAwesomePopup/>;

Change props of the notification

const notification = Notifications.registeredNotifications.get("PendingReservationsOnActivityStateChange");
notification.content = "Some text to display";
notification.backgroundColor = "blue";
notification.closeButton = false;

Register Custom Notifications

Option 1: string

Notifications.registerNotification({
id: "myNotificationId",
content: "Custom content", // string
type: NotificationType.error
});

Option 2: template

Notifications.registerNotification({
id: "myNotificationId",
content: "NotificationMessage", // template
type: NotificationType.error
});

Read more about templates in Localization and UI templating

Option 3: custom React component

interface CustomNotificationProps extends NotificationContentProps {
   customProp?: string;
   notificationContext?: any;
}

export class CustomNotificationElement extends React.Component<CustomNotificationProps, undefined> {
   render() {
       const { customProp, notificationContext } = this.props;
       return(
           <div>
               {notificationContext.message}
               <div />
               {customProp}
           </div>
       );
   }
}


Notifications.registerNotification({
    id: "myNotificationId",
    content: <CustomNotificationElement customProp="custom prop" />,
    type: NotificationType.error
    } 
);

Dispatch Custom Notifications

Option 1: string

Notifications.showNotification("myNotificationId", null);

Option 2 & 3: template & custom React component

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

Add Custom Notification Event Listeners

import * as Flex from "@twilio/flex-ui";

Flex.Notifications.addListener("beforeAddNotification", (payload) => {
  console.log("<---beforeTransferTask Listener--->", payload);
});
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif