Notifications Framework

Notifications Framework 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.

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 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

We are using the standard Browser Notification API for Flex Notifications Framework browser notifications implementation.

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

Requesting permissions

To start showing browser notifications user needs to first grand 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.

Available methods of Notification Framework

Method Description
registerNotification(notification: Notification) Register a custom notification
showNotification(id: string, context?: Object): Notification Dispatch a notification
addListener(event: string, handler: Function) Listen for a Notification event
dismissNotification(notification: Notification) Dismiss a notification
dismissNotificationById(id: string) Dismiss a notification by Id
dismissAll() Dismiss all notifications

Register notification handler. Use to expose your notification handler.


Returns whether the notification handler for the given id is enabled or not

toggleNotificationHandler(id, enabled)

Enable or disable notification handler

Available handlers:

  • browser
  • inapp

Available Properties for Notifications

Property Type Description
id string

notification Id

Must be unique. An error will be thrown if another notification is already registered with the same id.

content string | React.ReactChild | React.ReactElement<NotificationContentProps> content of the notification. Can be a text, a template or custom React component
type string

notification type. Possible values:

information = "information",
success = "success",
warning = "warning",
error = "error"

backgroundColor? string background color for notification bar
icon? string notification icon for notification bar
timeout? number

time in milliseconds that notification bar is visible before automatically dismissed; default is 3000 milliseconds; if set to 0, the notification bar will not be automatically dismissed

closeButton? boolean if set to false, the notification bar will not have a close button to be dismissed manually
context? object context variables that can be used in content templates.
isApplicable callback function callback determining whether particular notification instance should be shown
options object

Options for the notification handlers

Available options - browser notifications handler (add link)


List of custom clickable elements on the notification

onClick callback function

If set and the internal notification bar shows hyperlinks then this callback is called when any of the links are clicked.

Available Events for Notifications

Event Description

Event fired before notification is added


Event fired when notification is added

notificationDismissed Event fired when notification is dismissed

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

if you want to display a browser notification, you shall use options key with a browser tag in it. Here is the exhaustive list of properties that forms the browser object:

BrowserNotificationOptions {
    title?: string;
    body?: string;
    onClick?: (notification: Notification, event: Event) => void;
    onClose?: (notification: Notification, event: Event) => void;
    onShow?: (notification: Notification, event: Event) => void;
    onError?: (notification: Notification, event: Event) => void;
    options?: NotificationOptions;

If no browser key is passed to options, Flex will not show any browser notifications.

Default standard notifications

NotificationId Notification type Description Default text of the notification UI template code
PendingReservationsOnLogout error A logout is forbidden while a worker has pending reservations You cannot logout while you have a pending task/reservation


PendingReservationsOnActivityStateChange error Actitivity state cannot be changed while a worker has pending reservations You cannot update your activity while you have a pending task/reservation



error Task transfer failed due to recipient worker being unavailable Agent unavailable



error Voice task accept failed due to Voice SDK being disabled Call cannot be accepted. Twilio Voice SDK has been disabled.



error Accessing the microphone has failed Unable to access microphone, please check browser settings.



error Changing a worker's activity by the supervisor has failed due to the worker having pending reservations You cannot change an agent’s activity while they have a pending task/reservation.


MonitoringFailed error Initiating call monitoring has failed Monitoring attempt has failed


MessageSizeExceeded error Sending chat message has failed due to an exceeded character limit The entered character number exceeds the limit - {{currentCharCount}}/{{maxCharCount}}


ChatOrchestrationAddToChatChannelFailed error The worker could not be added to the chat channel after accepting chat based task Failed to add worker to the chat channel.


ChatOrchestrationDeactivateChatChannelFailed error Chat channel could not be deactivated during wrapping up of chat based task Failed to deactivate the chat channel.


ChatOrchestrationLeaveChatChannelFailed error Could not remove worker from chat channel during wrapping up of chat based task Failed to remove worker from the chat channel.


IncomingTask info Notification for incoming task, with most properties dependent on task channel in question Content depends on the type of task

Various templates depending on type of task



Notification for asking for browser notification rights

We need your permission to <a href='#'>enable browser notifications</a>


NewChatMessage only browser

Notification shown when new chat message is received

Content depends on the type of task



Working with Notifications

Register a custom notification with Browser notification handler

    id: "customNotification",
    closeButton: true,
    content: "Custom Notification",
    timeout: 0,
    type: NotificationType.warning,
    actions: [
            onClick={(_, notification) => {
    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 = () => {

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


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:})

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

id: "myNotificationId",
content: "Custom content", // string
type: NotificationType.error

Option 2: template

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;
               <div />

    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 browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more