UI Migration Guide

This guide contains a list of the breaking changes introduced between version 0.13 and 1.0 of Flex UI. If you have done programmatic customizations to Flex UI or Flex WebChat UI, you will need to make sure that your custom code is updated to support these changes.

To use a custom redux store, use the Flex store enhancer with a store creation method:

1
const reducers = combineReducers({
2
    flex: Flex.FlexReducer,
3
    app: myReducer
4
});
5

6
const middleware = applyMiddleware();
7

8
const store = createStore(
9
    reducers,
10
    compose(
11
        middleware,
12
        Flex.applyFlexMiddleware()
13
    )
14
);
15

16
Flex
17
    .Manager.create(configuration, store)
18
    .then(manager => {
19
        ReactDOM.render(
20
            <Provider store={store}>
21
                <Flex.ContextProvider manager={manager}>
22
                    <Flex.RootContainer />
23
                </Flex.ContextProvider>
24
            </Provider>,
25
            container
26
        );
27
    })
28

After Flex GA, the preferred way of customizing Flex, both Twilio hosted and locally hosted deployment models, is plugins.

Flex plugins are essential to customizing Flex instances so your development team can share components with agents and supervisors across your organization. Read more about customizing Flex with plugins here

If you have styled you UI, using the theming object, then you will need to make sure you do the following changes:

The colorTheme object now has 4 parameters:

• baseName: string - to set a predefined theme
• colors: object - to define a set of base colors that are used throughout the UI to define your custom theme
• light: Boolean - controls whether UI will aim at choosing dark texts or light text colors to allow for readability. It also controls icon colors, hover colors and more
• overrides: object - a set of style overrides for each component

An example of setting the color configurations in appConfig:

1
config.colorTheme = {
2
    baseName: "DarkTheme",
3
    colors: {
4
        base1: "blue",
5
        base2: "orange",
6
        base3: "yellow",
7
        base4: "black",
8
        base5: "white",
9
        base6: "pink",
10
        base7: "red",
11
        base8: "blue",
12
        base9: "brown",
13
        base10: "black",
14
        base11: "white",
15
    },
16
    light: false,
17
    overrides: {
18
        MainHeader: {
19
            Container: {
20
                background: "#35372c"
21
            }
22
        },
23
        SideNav: {
24
            Container: {
25
                background: "#35372c"
26
            },
27
            Button: {
28
                background: "35372c"
29
            },
30
        },
31
    }
32
}

We have introduced React Router for routing in Flex UI

• New actions to navigate the browser to different locations in the way similar to HTML5
• History API:
  • HistoryPush
  • HistoryReplace
  • HistoryGo
  • HistoryGoBack
  • HistoryGoForward
• New property route for a View component to mount a view to a route different from its name

Support for browser and memory history that is configurable through the configuration file.

In case you are using routing libraries like react-router-redux or connected-react-router, you may wish to sync history between your application and Flex. To do so, provide the history object that you are using for your Router as a parameter to Flex store enhancer:

1
const reducers = combineReducers({
2
    flex: Flex.FlexReducer,
3
    app: myReducer
4
});
5

6
const history = createHistory();
7

8
const middleware = applyMiddleware();
9

10
const store = createStore(
11
    reducers,
12
    compose(
13
        middleware,
14
        Flex.applyFlexMiddleware(history)
15
    )
16
);
17

18
Flex
19
    .Manager.create(configuration, store)
20
    .then(manager => {
21
        ReactDOM.render(
22
            <Provider store={store}>
23
                <ConnectedRouter history={history}>
24
                    <Switch>
25
                        <Route path="/hi" component={() => {
26
                            setTimeout(() => { history.push("/"); }, 5000);
27
                            return (
28
                                <div>Hi! I will redirect to Flex in 5 seconds flat!</div>
29
                            );
30
                        }}></Route>
31
                        <Route component={() => {
32
                            return (<Flex.ContextProvider manager={manager}>
33
                                <Flex.RootContainer />
34
                            </Flex.ContextProvider>);
35
                        }}></Route>
36
                    </Switch>
37
                </ConnectedRouter>
38
            </Provider>,
39
            container
40
        );
41
    })
42

We have introduced Component.Content.remove to allow the removal of components from dynamic component children (both native and programmatically-added ones). See the specification here.

This feature now requires a key property for all custom components passed to Component.Content.register/add. E.g. <div key="custom-key"/>

If you have added custom components to Flex UI, make sure they have a key property defined.

• Property task type changed to ITask for task-based components. Previously, the TaskState interface, which had only source and reservation properties, was used. The source and reservation properties remain the same, but now attributes and other task properties can be accessed from the task object itself. For example, this.props.task.attributes can be used where applicable and there should be no further need to use the source sub-property (which refers to the Task Router SDK object).
• Tasks in store are referenced by reservation sid now. (Previously, they had been referenced by task sid.)
• Task objects in the Actions framework have a new field, sourceObject, which will point to the actual SDK object:
  • Reservation in case the data source for the task is TaskRouterSDK. Applies for components and actions in AgentDesktopView.
  • InsightsObject in case the data source for the task is InsightsSDK. Applies for components and actions in TeamsView
  • Source is still there, but is deprecated.

• All actions that had taskSid in the payload will now expect sid instead
• Payloads have changed for some Actions:
  • SetActivity action now has a payload in the form of {activitySid: string; activityName?: string; activityAvailable?: boolean}. Only activitySid is used in the default implementation, and is required when invoking the action by the user, but the other two parameters are filled for better context for users who override the action and need more information on what the new activity will be. Additionally, SetActivity can now be called with just activityName in the payload.
  • SelectTaskInSupervisor now expects/provides an object as its payload in the form of {task?: ITask, sid?: string}. Providing either will autofill the other, so both will be available for whoever taps into the action via the Actions framework.
  • SelectWorkerInSupervisor now expects/provides an object as its payload in the form of {worker?: ITask, workerSid?: string}. Providing either will autofill the other, so both will be available for whoever taps into the action via the Actions framework.
  • MonitorCall now expects/provides an object as its payload in the form of {task?: ITask, sid?: string}. Providing either will autofill the other, so both will be available for whoever taps into the action via the Actions framework.
  • HoldCall will no longer toggle the hold state, but will instead be meant only for call holding. A separate UnholdCall action was added.

The HangupCall and HoldCall actions will now accept optional parameters sid:string or task:ITask in the payload object. Actions will work without them if just one call is available, but it is advised to use those parameters to be more specific for future multi-call scenarios. Even if the task/taskSid are not specified, when adding listeners or overriding these actions, those parameters are filled out automatically.

Call recording can be enabled from the configuration service. This option sets the following parameters in the conference payload when a conference is created:

• "conferenceRecord": true,
• "conferenceRecordingStatusCallback": "https://webhooks.twilio.com/v1/Accounts/{accountSid}/Workspaces/{workspaceSid}/Tasks/{taskSid}/FlexRecordingWebhook",
• "conferenceRecordingStatusCallbackMethod": "POST"

You can retrieve the accountSid and workspaceSid via the configuration services, i.e.

manager.serviceConfiguration.account_sid

manager.serviceConfiguration.taskrouter_workspace_sid

To enable call transfers, calls will be currently accepted with endConferenceOnExit set to false, meaning that the call will not stop for the customer when an agent hangs up, and to end the call, the customer will need to hang up themselves (otherwise, they will stay in the call alone).

If the above behavior is not acceptable for your use case and you will not be using transfer functionality, you may opt out of transfers by setting the disableTransfers config option to true. If this option is set to true, the endConferenceOnExit option will be set to true, but transfers to other agents will not be available.

All of the functions to orchestrate different channels and tokens have been removed. Now, a combination of backend services and Studio flows is used instead.

• Theming - the same changes that have been implemented for Flex UI have been implemented here as well.
• Pre-engagement data - when a chat session is created, pre-engagement data is saved to chat channel attributes (channel.attributes.pre_engagement_data), that can be accessed in the Studio Flow or directly from Programmable Chat via the SDK or REST API.
• Configuration options startEngagementUrl and serviceBaseUrl have been removed and new configuration options are required in the application configuration:
  • accountSid - Account SID where Flex is running
  • flexFlowSid - Flex Flow SID created at onboarding for chat

The accountSid and flexFlowSid can be found on the admin dashboard development configuration page: https://flex.twilio.com/admin/developers

• ContactCenterManager was renamed to Manager
• Changed Manager.create method signature - first accountSid parameter was dropped

We have started using a Twilio configuration service for project-level remote configuration that can be shared between different instances of Flex UI.

• A new method for Manager's instances fetchConfiguration asynchronously retrieves a configuration from the Flex Configuration service
• A new method for Manager's instance updateConfig merges provided configurations on top of any existing configuration
• Manager's instance configuration behavior:
  • Whenever a new instance of Manager is created, it will fetch the remote configuration from Flex Configuration service. Local configuration will be applied on top of remote configuration
  • Manager's instance configuration setter is deprecated

The Task Channel Definition API has been introduced. This is how all of the native channels are defined in Flex UI, and is the advised way of registering your own custom channels or customizing existing ones. The specification can be found here.

• Only JWE tokens are now supported
• The SupervisorDesktopView component was renamed to TeamsView
• The template SideNavSupervisorView was renamed to SideNavTeamsView
• Templates and channel definitions use the channelType attribute from a task to detect the chat channel type. Previously, the endpoint parameter was used.

A new Flex API method, progress, renders a fancy loading indicator to a provided selector: Flex.progress("#container")

• Upgrade packages in package.json "@twilio/flex-ui": "^1.0.0",
"react": "^16.5.2",
"react-dom": "^16.5.2"

• ADD:"eslintConfig": {
"extends": "react-app"
},

• REMOVE: react-app-rewired": "1.5.2”

• UPDATE: scripts: {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test"
"eject": "react-scripts eject
}

• Update index.js

  Copy code block

  1
  import React from "react";
  2
  import ReactDOM from "react-dom";
  3
  import "regenerator-runtime/runtime";
  4
  import * as Flex from "@twilio/flex-ui";
  5
  import "./index.css";
  6
  import App from "./App";
  7
  import registerServiceWorker from "./registerServiceWorker";
  8
   const configStorageKey = "FLEX_CONFIG";
  9
  const mountNode = document.getElementById("root");
  10
   window.onload = () => {
  11
    const predefinedConfig = window.appConfig || {};
  12
    const runtimeConfig = getRuntimeConfig();
  13
     const configuration = {
  14
      ...predefinedConfig,
  15
      ...runtimeConfig
  16
    };
  17
     Flex
  18
      .progress(mountNode)
  19
      .Manager.create(configuration)
  20
      .then(manager => renderApp(manager))
  21
      .catch(error => handleError(error));
  22
  };
  23
   function renderApp(manager) {
  24
    ReactDOM.render(
  25
      <App manager={manager} />,
  26
      mountNode
  27
    );
  28
  }
  29
   function handleError(error) {
  30
    console.error("Failed to initialize Flex", error);
  31
     const missingAccountSid = error instanceof Flex.ConfigError && error.key === "accountSid";
  32
     if (!missingAccountSid) {
  33
      throw error;
  34
    }
  35
     ReactDOM.render(
  36
      <Flex.RuntimeLoginView
  37
        onSuccess={(loginData, runtimeDomain) => {
  38
          setRuntimeConfig(loginData, runtimeDomain);
  39
          window.location.reload();
  40
        }}
  41
      />,
  42
      mountNode
  43
    );
  44
  }
  45
   function setRuntimeConfig(loginData, runtimeDomain) {
  46
      const config = {
  47
          serviceBaseUrl: runtimeDomain,
  48
          sso: {
  49
              accountSid: loginData.accountSid
  50
          }
  51
      };
  52
      const serializedConfig = JSON.stringify(config);
  53
      localStorage.setItem(configStorageKey, serializedConfig);
  54
  }
  55
   function getRuntimeConfig() {
  56
      const serializedConfig = localStorage.getItem(configStorageKey);
  57
      localStorage.removeItem(configStorageKey);
  58
      const config = JSON.parse(serializedConfig || "{}");
  59
      return config;
  60
  }
  61
   registerServiceWorker();
  62
  

• Update App.js
  Move customization to manager into the render method below:****

  Copy code block

  1
  import React from "react";
  2
  import * as Flex from "@twilio/flex-ui";
  3
  
  4
  class App extends React.Component {
  5
    render() {
  6
      const { manager } = this.props;
  7
  
  8
      if (!manager) {
  9
        return null;
  10
      }
  11
  
  12
      return (
  13
        <Flex.ContextProvider manager={manager}>
  14
          <Flex.RootContainer />
  15
        </Flex.ContextProvider>
  16
      );
  17
    }
  18
  }
  19
  
  20
  export default App;
  21
  

• Refactor Checklist:

  • Any components accessing task status like this: this.props.task.reservationnow can access status like this: this.props.task.status
  • If getting reservation like this: const reservation = StateHelper.getReservation(task.sid);now can use this: const reservation = payload.task.sourceObject;
  • Be sure to update any Actions you are using to reference reservation sid, not taskSid