Migrating from Flex UI 1.x.x to 2.x.x

This Flex UI 1.x.x to 2.x.x migration guide covers breaking changes in the Flex UI programming interfaces. It covers required changes you may need to make to custom code or plugins. The most notable changes are:

• Your dependencies may need to be upgraded
• Some aspects of Flex now use the Conversations SDK
• There is a new Theming interface
• State management has changed

Enable Flex UI 2.0 for your account

For your application on flex.twilio.com

You can install Flex UI 2.0 by accessing the versions page of your Flex application by logging in as a Flex Admin. The versions page will have a list of Flex versions available to install. Install 2.0 by clicking on the Select button next to the version that has "2.0" in its name. Since this is in public beta, the version name will contain the word "beta" in it. Your application will now be upgraded to Flex UI 2.0. The versions page on 2.0 will look like this

Using Configuration service API

To change ui_version and reset ui_dependencies, you can make a curl request as below. You can get your accountSid and auth token from https://twilio.com/console

curl --request POST \
 --url https://flex-api.twilio.com/v1/Configuration \
 -u ACxxxxxxxxxxxxxxxxxxxxx:auth_token \
 --header 'accountsid: ACxxxxxxxxxxxxxxxxxxxxx' \
 --header 'content-type: application/json' \
 --header 'i-twilio-auth-account: ACxxxxxxxxxxxxxxxxxxxxx' \
 --data '{
   "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
   "ui_version": "2.0.0-beta.1",
   "ui_dependencies": {}
}'

Self-hosted Flex

To install 2.0 alpha version, run the following command:

yarn add @twilio/flex-ui@alpha

または

npm install @twilio/flex-ui@alpha

Using flex-ui-sample package

If you want to use, or have used the flex-ui-sample package for bootstrapping your project, we have introduced a flex-v2 branch which requires @twilio/flex-ui@alpha package:

https://github.com/twilio/flex-ui-sample/

In case of an existing project, please merge the flex-v2 branch or rebase onto it.

We have also bumped the React to version 17 to satisfy the Flex 2.0 requirements. This means that on any existing project you have to resolve compatibility issues in your code, should they occur.

Build Plugins with Flex UI 2.0

Update Plugins for Flex 2.0

Based on the implementation of your plugin, you may need to update your plugin source code and its dependencies to be compatible with Flex UI 2.0. The changes are covered in this guide. Here are some guidelines to help you manage the migration of your plugins.

1. Once you have updated your plugin code and dependencies to be compatible with 2.0, test your plugin locally by using the twilio flex:plugins:start command of the Flex Plugins CLI.
2. Once you have tested your plugin to ensure that it works as expected, deploy your plugin to your dev or staging environment using twilio:flex:plugins:deploy command. We recommend following the Semantic Versioning format for managing your plugin version. Since this plugin is compatible with 2.0, we recommend registering this plugin version as a new major version. Use the --major argument and write a clear description for the Changelog of this version.
3. Enable the plugin deployed on your stage/dev account via the Plugins Dashboard or the Plugins CLI
4. Follow Steps 1 to 3 for migrating all your plugins to be compatible with Flex UI 2.0
5. Finally, create a release via the CLI or the Plugins Dashboard that contains all the plugins that you have migrated to 2.0. Leverage the description and the name fields to tag the release as being compatible with 2.0.

Building new plugins for Flex 2.0

When you leverage the create command of the Flex Plugins CLI to create a new plugin, you need to update the dependencies of the package.json of the plugin to make it compatible with 2.0.

An example of the devDependencies and dependencies are shown below:

"dependencies": {
   "flex-plugin-scripts": "4.1.3",
   "react": "^17.0.2",
   "react-dom": "^17.0.2"
 },
 "devDependencies": {
   "@twilio/flex-ui": "2.0.0-alpha.9",
   "react-test-renderer": "17.0.2"
 }

The devDependencies need to be updated in order to run your plugin locally via the twilio flex:plugins:start command of the CLI.

Rollback changes to use Flex UI 1.x

If you run into issues with your Flex application on 2.0 that require you to roll back your Flex UI version, here are the following steps

1. Change your Flex UI version of your Flex application to the minor version of Flex UI 1.x.
2. Log in as an admin on your Flex admin and access the releases tab of the Plugin Dashboard.
3. Choose and redeploy the release that does not contain any of the versions of the plugins migrated for 2.0. Since you had registered a major version for each of the plugin you migrated, it should now make it easier for you to determine the release that contains the plugins compatible with Flex UI 1.x version.

Upgraded dependencies

The Flex UI uses a variety of dependencies in order to provide the highest-quality user experience for your contact center users. Many of these dependencies have been updated as part of the new major version of Flex.

If you have deployed Plugins to modify your instance of the Flex UI, they may be using incompatible versions of many dependencies. Make sure to update your Plugins’ dependencies to be compatible with the Flex UI 2.0.

Node

Minimum required Node version was upgraded from 12 to 14.

React & React DOM

React & ReactDOM are now peer dependencies.

No changes are required, besides including React & ReactDOM as a dependency. The Flex UI 2.0 does not currently use any features that will introduce breaking changes.

Redux & React-redux

The Flex UI 2.0 does not currently use any features that will introduce breaking changes. If you have used these libraries directly, however, you could experience breaking changes.

React-router-redux

The Flex UI relies solely on the react-router-dom dependency. You can update the version and remove the react-router and react-router-redux dependencies.

Context consumers imports

React-router-dom is now based on React v17 Context. If you want to consume the router context from the Flex UI, you need to import withRouter directly from the Flex UI Package

import { withRouter } from "@twilio/flex-ui";

Emotion

Package versions and structure

Emotion has updated their own package structure, so you will need to update both the versions and the package names.

Context consumers imports

Emotion version 11 uses React v17 Context. If you want to consume styles coming from the Flex UI theme, you need to import withTheme and styled directly from the Flex UI Package

import { withTheme, styled } from "@twilio/flex-ui";

Material UI

Package versions

Nothing particular is required aside from bumping the version. Please note, you’ll need to address the changes related with the new major version of this library.

If you are overriding the Material theme with a Flex Theme, you will need to re-register the MuiThemeProvider in your plugin to use React v17 Context, and provide the Flex Theme overrides in the createMuiTheme arguments.

Main Update Script

The following script will update all Flex UI dependencies to use 2.0 dependencies, and remove any unneeded dependencies. It will save these changes in your package.json, and ignore legacy peer dependencies (which can cause issues for users who are currently using NPM v7.0.0 and higher.)

You will still need to update your Plugin code to use the new dependencies correctly.

npm install \
@emotion/css@^11.1.3 @emotion/react@^11.1.5 @emotion/styled@^11.1.5 \
@material-ui/core@^4.11.3 \
react@17.0.1 react-dom@17.0.1 \
react-redux@^7.2.2 redux@^4.0.5 \
react-router-dom@^5.2.0 \
--save --legacy-peer-deps && \
npm uninstall react-router react-router-redux --save

Conversation SDK

Currently, the Flex UI uses the Programmable Chat SDK to handle messaging channels. In 2.0, the Flex UI uses the Conversations SDK to replicate this functionality.

To ease migration of plugins from Flex UI 1.x to 2.x, we want to create a virtual bridge to also export Chat SDK-compatible constructs. Therefore you still be able to use their your Chat-based customisations without having to change anything. This bridge logic will however warn the user highlighting that the accessed methods and properties are actually deprecated.

Identified differences between libraries

Here are the properties and methods that have been changed or removed from Chat SDK to Conversation

Chat Client

Channel vs Conversations

ChannelDescriptor

There are no paralell in Conversations SDK, we fallback to Conversation.

UserDescriptor

There are no paralell in Conversations SDK, we fallback to User.

Chat User vs Conversation User

Chat Message vs Conversation Message

Chat Member vs Conversation Participant

Chat SDK methods and concepts dropped in Conversations SDK

1. There’s no concept of a public channel. All the conversations are private.
2. Descriptors have been removed. They used to be a “snapshot” of the described entity. This is easily replaceable by returning the actual entity and unsubscribing from its changes.
3. There is no invite method anymore on conversations. We fallback to the add method as their functionalities are very similar.

Flex UI changes

Deprecated reducers

• channels
• channelInput

Deprecated props

• チャンネル
• channelSid
• isMemberOfChannel
• メンバー
• autoInitChannel
• activeChatChannel
• chatChannel (on taskContext)

Deprecated Helpers

• ChatChannelHelper

廃止予定のメソッド

• TaskHelper.getTaskChannelSid

Deprecated notifications ID

• ChatOrchestrationAddToConversationFailed
• ChatOrchestrationDeactivateConversationFailed
• ChatOrchestrationLeaveConversationFailed

Voice SDK

Currently, the Flex UI uses the twilio-client SDK for voice communications. In 2.0, the Flex UI uses the twilio-voice SDK for this functionality since twilio-client is now deprecated. Functionality and usage of the new voice SDK remains largely the same with a few exceptions:

• The events ‘Connect’ , ‘Disconnect’ and ‘Cancel’ which used to apply to the Device instance, now apply to the Call instance instead.
• The Device ‘ready’ event has been replaced with a ‘registered’ event. Likewise for ‘online’ which is now ‘unregistered’
• The structure of Device state has changed to:

   namespace Device {
   isBusy: boolean;
   enum State {
     Unregistered = 'unregistered';
     Registering = 'registering';
     Registered = 'registered';
     Destroyed = 'destroyed';
   }
 }

For more detail on the changes from twilio-client to twilio-voice SDK, see this migration guide.

Theme and Branding

Flex UI 2.0 uses a new theming structure that more closely maps to the Twilio Paste design system. This new structure is based on the concept of design tokens, a set of variables that you can modify. This structure promotes both consistency, customization and web accessibility.

Theme configuration changes

config.colorTheme is deprecated. There is a new configuration key called config.theme with the following structure:

interface ThemeConfigProps {
   isLight?: boolean; // Represents if light or dark theme
   tokens?: Tokens; // Paste tokens
   componentThemeOverrides?: Object; // Object containing styles of the component which is to be overridden.
}

config.theme.componentThemeOverrides has the same structure as deprecated config.colorTheme.overrides.

Styled components theme props changes

Components which receive the theme as props have the following changes:

1. props.theme.calculated is deprecated.
   1. Use props.theme.isLight instead of props.theme.calculated.lightTheme
   2. Use props.theme.tokens.textColors.colorText instead of props.theme.calculated.textColor.
2. props.theme.colors is deprecated.
3. props.theme.tokens is introduced:.

interface Tokens {
   backgroundColors: BackgroundColors;
   textColors: TextColors;
   borderColors: BorderColors;
   borderWidths: typeof BorderWidth;
   radii: typeof BorderRadius;
   fontSizes: typeof FontSize;
   fontWeights: typeof FontWeight;
   lineHeights: typeof LineHeight;
   sizings: typeof Sizing;
   spacings: typeof Spacing;

}

For more on each token information, please refer to Twilio Paste.

Deprecated Predefined themes

Flex UI 2.0 deprecates all predefined themes like DarkTheme, MediumTheme, BlueDarkTheme, BlueMediumTheme. It will now have 2 modes of Flex: Light and Dark.

List of deprecated tokens

const deprecatedTokens = [
   "errorColor",
   "errorGlow",
   "buttonHoverColor",
   "tabSelectedColor",
   "connectingColor",
   "disconnectedColor",
   "notificationBackgroundColorInformation",
   "notificationBackgroundColorSuccess",
   "notificationBackgroundColorWarning",
   "notificationBackgroundColorError",
   "notificationIconColorError",
   "notificationIconColorWarning",
   "userAvailableColor",
   "userUnavailableColor",
   "defaultButtonColor",
   "lightTextColor",
   "darkTextColor",
   "disabledColor",
   "focusColor",
   "focusGlow",
   "holdColor",
   "declineColor",
   "acceptColor",
   "declineTextColor",
   "acceptTextColor",
   "completeTaskColor",
   "flexBlueColor",
   "agentBusyColor"
];

Deprecating Channel colors

const deprecatedChannelColors = [
   "inactive",
   "call",
   "video",
   "chat",
   "sms",
   "facebook",
   "line",
   "whatsapp",
   "custom"
];

ThemeProvider

Introducing a new API Flex.setProviders() which can be used to load providers on the root level once and don’t have to worry about wrapping again as the context will correctly set. Now to use Paste in Flex plugins, developers will not need to wrap Paste ThemeProvider over all its components.

When using Paste, developers need to pass the CustomizationProvider from Paste to Flex using Flex.setProviders api as below. By doing this, we’ll wrap Flex with the passed Provider and developers don’t have to worry about fetching the right theme and passing it on.

import { CustomizationProvider } from "@twilio-paste/core/customization";
 
Flex.setProviders({
   PasteThemeProvider: CustomizationProvider
});
 
Flex.AgentDesktopView.Panel1.Content.add(
   <PasteButton key="A" variant="primary">
       Paste Button
   </PasteButton>
);
 
Flex.AgentDesktopView.Panel1.Content.add(
   <PasteButton key="B" variant="primary">
       Paste Button
   </PasteButton>
);

Flex.setProviders() also allows developers to pass their own custom provider which is needed to be set on the root level. They can do it as below:

Flex.setProviders({
   CustomProvider: (RootComponent) => (props) => {
       return (
           <Context.Provider value={{ test: "123" }}>
               <RootComponent {...props} />
           </Context.Provider>
       );
   }
});
 
Flex.AgentDesktopView.Panel1.Content.add(
   <Context.Consumer>
       {(value) => {
           <div>{value.foo}</div> // Will print 123
       }}
   </Context.Consumer>
);

When using Material UI for styling it is important to wrap our plugins with a StylesProvider with a classNameGenerator that sets a productionPrefix so styles classes don't clash between plugins and Flex. The below example shows how to use a custom provider for styling Material UI components:

Flex.setProviders({
      CustomProvider: (RootComponent) => (props) => {
          return (
            <StylesProvider generateClassName={createGenerateClassName({
              productionPrefix: 'pluginXYZ',
            })}>
                  <RootComponent {...props} />
              </StylesProvider>
          );
      }
});

Flex.AgentDesktopView.Panel1.Content.add(<StyledSampleComponent  key="no1"  />);

Flex Messaging UI V2 changes

Moving to Flex Conversations with Flex 2.0 has enabled us to provide an even more customisable Messaging UI, and this comes with a few of changes which you may need to adjust to.

New Dynamic Component structure - MessageInputV2

The new default input component in the messaging canvas is the dynamic component MessageInputV2 . This includes the text area component and a new dynamic component, MessageInputActions , and is structured like so:

<MessageInputV2>
    <MessageInputArea key="textarea"/>
    <MessageInputActions key="actions"/>
</MessageInputV2>

MessageInputActions contains the message send button and the file attachment button (if file attachment is enabled).

New default props

MessageInputV2 has two new default props, hideSendButton and rows , these control the rendering of the send button and row height of the text area respectively.

Combined text and media messages

The SendMessage action is now capable of sending file attachments and text in the same message. Files can be passed to the SendMessage action on the attachedFiles field of its Action payload.The SendMedia action is deprecated but is still available.

User and Activity controls

• A new programmable component Activity is added to MainHeader.
• Changes made to the UserControls component. We have removed activity controls and change the layout. Activity can be changed in a new component Activity
• Theme deprecated for UserActivityControls
• Remove Activity controls from the NoTaskCanvas

Note, This is a potential breaking change if you have customized UserCard and its child components using CSS

State Management Changes

As part of the upgrades to our core APIs, Flex UI 2.0 includes the Redux Toolkit and some new APIs for managing your internal state. These tools provide some guardrails for your state management, helping you set up boilerplate code more easily and with better defaults.

We recommend using single Redux store, either let Flex UI create its own store or pass a custom store using Manager.create() API

useFlexSelector

A wrapper around Redux's useSelector method. It exposes the same API but adds some Flex validations to ensure Flex's internal state is usable. This selector is specific for working with Flex state itself. Outside of accessing Flex state, we recommend using the default useSelector.

const MyComponent = (props) => {
   const viewState = useFlexSelector(state => state.view);
   return (
       {viewState.isSideNavOpen &&
           <div>My Custom Code</div>
       }
   )
}

The selector takes the current view state for the custom component. The selector guarantees that the state being selected is safe to read and can be used in the application without side effects. This couldn’t be guaranteed with useSelector.

useFlexDispatch

A wrapper around Redux's useDispatch method. It prevents dispatches from causing side effects to Flex's state, ensuring your changes work as expected. Use this hook for interacting with Flex's state. You can use the native useDispatch method outside of Flex’s state.

const MyComponent = (props) => {
   const viewState = useFlexSelector(state => state.view);
   const dispatch = useFlexDispatch();
   return (
       {viewState.isSideNavOpen &&
               <button onClick={() => dispatch({type: 'close_side_bar'})}>My Custom Code</button>
       }
   )
}

MessageInput.defaultProps.useSeparateInputStore

The Flex UI 2.0 no longer uses the MessageInput.defaultProps.useSeparateInputStore flag and its behavior has been deprecated. All Flex UI development must now be done with a separate Store. You can remove the flag without any repercussions.

AppConfig changes

You need to update your AppConfig structure to utilize the new config structure’s names and capabilities.

Action changes

Download Media Attachment changes

DownloadMedia action no longer requires “message” as a part of the payload. Instead, a new property “media” of type “Media” from @twilio/conversations is required.

Renamed actions

These actions were renamed to follow the action naming convention:

Teams View changes

削除

• Removed FilterData (shouldn't be needed) and TeamFiltersPanelProps (use TeamFiltersPanelChildrenProps instead) interfaces from Flex.Supervisor.
• Removed uniqueName from TaskCanvasTabsChildrenProps.
• Removed the deprecated WorkerProfile.defaultProps.details prop. Use WorkerProfile.Content to add additional details to the worker profile panel.
• Removed insights.client and supervisor.listener from redux state.
• Legacy filtering in TeamsView was removed. Filters from WorkersDataTable.defaultProps.filters will still be added to the new filter panel, but the support for filter factories was dropped.
• WorkersDataTable.defaultProps.initialCompareFunction was removed. Support for sorting was added to the workers table and you can now use sortWorkers, sortCalls and sortTasks on WorkersDataTable.defaultProps to specify the compare functions used by the workers, calls and tasks columns.
• WorkersDataTable.defaultProps.tablePlaceholder was removed. The message displayed when the table is empty can be modified with the
• Cleaned up the WorkersDataTableChildrenProps. Only workers, selectedTask, selectedWorker, and monitoredTaskSid are now available.
• WorkersDataTable no longer forces updates every second. This could be considered breaking for customers who added columns, which contain some timers (eg. task age) and which will no longer tick every second. Ticker component, now exported via flex-ui-core, can be used when rendering a timer. The component will trigger a re-render every second in synchrony with other timers in Flex.
• TeamsViewResultsSummaryNoWorkersDisplayedTitle and TeamsViewResultsSummaryNoWorkersDisplayed templates.

Other changes

We have also cleaned up our api and renamed or remove objects and interfaces. Most of the changes should not have any impact on plugins.

Removed/renamed deprecated objects and interfaces

• UserControlsImplProps has been removed. Refer to UserControlsChildrenProps instead
• call.oldHold removed from TaskContext and state.phone.connection.onHold removed from state. Use TaskHelper.isCallOnHold(task) to get the status of the call.
• DeprecatedLoginView component removed
• DeprecatedRuntimeLoginView component removed
• state.flex.phone.connections property removed. Refer to state.flex.phone.connection instead.
• Event selectedViewChanged now only receives one argument (newViewName) and it’s not triggered on view resize anymore. To listen to view resize events, please subscribe to the viewResized event.
• ActionsImpl object has been removed. Please refer to Actions instead.
• registerGlobalStyles has been removed. Please refer to registerStyles instead
• AudioManager’s ErrorCode has been renamed to AudioErrorCode
• Actions.emit has been removed - use Actions.invokeActions instead.
• Actions.removeAllListeners has been removed - please use Actions.removeListener and provide the specific listeners you want to remove.
• Removed export of Flex.ErrorManager. This functionality has been replaced with Flex.Monitor.sendDebuggerEvent
• Removed selectionStart/selectionEnd from MessageState, MessageInputArea, MessageInput, ConversationState
• Removed show and hide methods from the ModalPopupWithEntryControl

Removed unused objects and interfaces

• ChatModule
• ChatStateCallback
• chatReducer
• registerGlobalStyles
• StateMachineCb
• StateMachine
• initWithStrings
• Version (not VERSION)
• Initialize (from flex-core)
• DeepPartial
• NotificationManager
• withDefaultPropsUpdate
• AggregatedDataTile
• ArrayInterpolation
• FunctionInterpolation
• Interpolation
• StyledOptions
• Themed
• CreateStyled
• CreateStyledOtherComponent
• CreateStyledStatelessComponent
• StyledComponent
• StyledComponentMethods
• StyledOtherComponent
• StyledStatelessComponent,
• getBackgroundWithHoverCSS
• ThemeSupport
• Utils
• CountryManager
• Animations
• SVGContainerProps
• FrameConstants
• StyledUl
• CSSProps

Component and config changes

• TaskInfoPanel inner html styles tweaked to accommodate new design
• TaskInfoPanelContent string inner html updated
• TaskCanvasTabs resets to default task when switching between tabs
• Flag file-attachments-in-chat is deprecated