Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now


Rate this page:

Thanks for rating this page!

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

Flex WebChat UI Release Notes

This page includes the release notes related directly to Flex WebChat UI. For the list of all Flex-related release notes, including backend updates and Flex UI release notes, please see this page.

v 2.1.2

release date AUG 29, 2019

  • DynamicForm email validation now correctly supports 2-chars domains, subdomains.

v 2.1.1

release date AUG 12, 2019


  • Bundled code now transpiles to IE11-compatible version. If you're integrating Flex NPM package into your application, you also have to include polyfills for required features at the top of your application's entry point. For instance, in case of create-react-app:
import 'react-app-polyfill/ie11';
import 'react-app-polyfill/stable';

v 2.1.0

release date JUL 17, 2019

Dependencies updated

  • twilio-chat from version 3.0.2 to version 3.2.3
  • @material-ui/core from version 1.3.1 to version 3.9.3


  • Aria props properties to the following components to support accessibility:
    • MessageInput:
      • sendButtonAriaProps • AriaProps • Send button aria props ({ ariaLabel: "Send Message" } by default).
      • textAreaAriaProps • AriaProps • Text area aria props ({ ariaLabel: "Enter your message here to get help" } by default)
    • MessageList:
      • listContainerAriaProps • AriaProps • List container aria props ({ ariaLive: AriaLive.Off } by default).
    • EntryPoint:
      • collapsedIconAriaProps • AriaProps • Collapsed icon aria props ({ariaLabel: "Click here to open Web Chat and get help."} by default).
      • openedIconAriaProps • AriaProps • Opened icon aria props ({ariaLabel: "Hide Chat"} by default).

Example on how to set aria attributes:

FlexWebChat.MessageInput.defaultProps.sendButtonAriaProps = {
    ariaLabel: "Send Message",
    ariaLive: FlexWebChat.AriaLive.Polite

FlexWebChat.MessageInput.defaultProps.textAreaAriaProps = {
    ariaLabel: "Enter your message here to get help",
    ariaLive: FlexWebChat.AriaLive.Assertive
  • Chat "Send message" button can now be themed with theme.Chat.MessageInput.Button.

Example on how to change the icon for a text:

appConfig = {
    Chat: {
        MessageInput: {
            Button: {
                borderRadius: "5px",
                width: "100px",
                fontSize: "18px",
                svg: {
                    display: "none"
                ":after": {
                    content: '"Send Button text"'


  • General Flex UI styles (like headers, paragraphs or links) are now applied only to HTML elements that have a class starting with Twilio or their direct descendants without any class
  • CSS reset is no longer applied automatically.



  • Unused AppState.tryGet method

v 2.0.0


release date APR 1, 2019

This major version contains breaking changes

This WebChat version works with any Flex UI version starting from version 1.0.0


  • We have added a character limit of 32kB to MessagingCanvas. Users will see a character limit notification and message submit will be disabled if the limit is reached. The SendMessage action will validate the character limit and fail the action if the limit is reached.
  • Required validation in the pre-engagement form was fixed. Users will not be able to submit the form if all required fields are not filled.
  • We have fixed several issues causing chat messages to be sent or rendered twice.


  • Breaking change: Set predefinedMessage defaultProp to Messaging to display and customise a predefined initial message to the user. It is set to be displayed by default, but can be customized or turned off completely. Read more about how predefined message is used in Installing and using Flex WebChat
  • Added sdkOptions.chat key to configuration object that can be used to pass options to chat SDK during initialization.
  • Breaking change: New function Twilio.FlexWebChat.renderWebChat added to initialize and render WebChat automatically. To create and render WebChat automatically (without configuring anything). Read more about ways to initializing and configure WebChat in Installing and using Flex WebChat.
  • We have added an email type field to the pre-engagement form. Data entered in that filed by the user will need to pass email validation to be submitted.


  • Breaking change: Global Twilio.Flex renamed to Twilio.FlexWebChat.
  • Breaking change: Twilio.FlexWebChat.createWebChat now only creates an instance of WebChat, but does not render it automatically. Use Twilio.FlexWebChat.renderWebChat to render automatically (instead of createWebChat). Read more about ways to initializing and configure WebChat in Installing and using Flex WebChat.
  • Breaking change: We have removed configure() method from returned Twilio.Flex.createWebChat object. Use manager.configuration member to set the configuration.
  • Breaking change: We have removed a default pre-engagement form from the out-of-the-box WebChat experience. Now startEngagementOnInit by default is true, and the default preEngagementConfig is removed. Read about how to add a pre-engagement form in Pre-engagement and context
  • Breaking change: We have changed the following component props of the EntryPoint component:
    • hideTaglineWhenExpanded - choose whether to hide the tagline when chat box is expanded.
    • iconClosed - name of the icon to be shown when chat box is closed.
    • iconExpanded - name of the icon to be shown when chat box is expanded.
    • tagline - tagline content.
  • We have also removed the following EntryPoint props in favour EntryPoint.Container defined in the colorTheme object:
    • entryPointStyle
    • entryPointBorderStyle
    • entryPointClassName
    • widgetClassName
    • entryPointSize
    • entryPointLocation
    • bottom
    • right
    • background
    • color
  • Breaking change: Added footer text as an attribute to pre-engagement config. Now use preEngagementConfig.footerLabel to set it. To style pre-engagement form footer text, use PreEngagementCanvas.Footer in colorTheme object.
  • logLevel by default is set to error.
  • Breaking change: Chat's MessageInput now uses localState by default. This will allow the developer to store the message input value in the component state instead of the Redux state. Please note: MessageInput.defaultProps.useLocalState should be set to false if there's the intention of changing the input value using the SetInputText action.
  • Group engagement stage constants in an Enum EngagementStage
  • Breaking change: setEngagementStage() method has been removed from returned Twilio.Flex.createWebChat object. Engagement stage is determined by configuration and chat state.
  • We have removed the following unused config options:
    • Config.canvasBottom prop
    • Config.postEngagementConfig prop
    • Config.timeoutEngagementConfig prop
    • SessionState.sessionData prop
    • SessionState.waitingTimeoutSeconds prop
    • SessionState.preEngagementReady prop
    • Engagement stages
    • Session Actions

v 1.2.0


release date JAN 11, 2019


  • Values for multiple fields in the pre-engagement form cannot be set

  • Name of the agent was not shown as message sender after the chat was completed

  • TypeScript definitions for TS based projects are broken

  • WebChat fails to load if the chat channel has been deleted


  • You can now use a custom redux store with WebChat

const reducers = combineReducers({
    flex: WebchatReducer,
    app: appReducer

const store = createStore(

FlexWebChat.Manager.create(config, store)
    .then(manager => {
            <Provider store={store}>
                <FlexWebChat.ContextProvider manager={manager}>
                    <FlexWebChat.RootContainer />

v 1.1.0


release date DEC 19, 2018


  • Fixed selectItem type in pre-engagement form by passing the missing value prop to Select and fixed the styles for the same.
  • Fixed the container width of DynamicFrom for webchat forms.


  • The startEngagementOnInit option now disables pre-engagement form


  • User's friendly name default to Anonymous and can be defined through context argument as friendlyName field

New GA version of the Flex WebChat UI has been released and is now available on NPM

  • @twilio/flex-webchat-ui@1.0



  • New configuration options required in the application configuration:
    • accountSid - Account SID where Flex is running
    • flexFlowSid - Flex Flow SID created at onboarding for chat


  • Configuration options startEngagementUrl and serviceBaseUrl



  • Individual module files in the NPM module removed. All sources bundled into a single module bundle file referenced by the main field in package.json.


  • Themeing was reworked and config parameters changed. User now has 4 distinct levels available to theme their application.

    • Not specifying a predefined theme, in that case BlueMediumTheme is chosen automatically.
    • Specifying predefined theme - either colorTheme:"DarkTheme" or colorTheme: {name: "DarkTheme"}. Available themes are MediumTheme, DarkTheme, BlueMediumTheme and BlueDarkTheme. A predefined theme specifies base colors used and also whether the theme is considered light or dark, which influences text and hover colors unless they are specifically changed.
    • Overriding all or a selection of colors and/or the lightness of the theme that was set by the predefined theme (note, specifying predefined theme was not compulsory, but in BllueMediumTheme was then used as default).
      • colors - variables base1..base11 are colors provided by the predefined theme that set the tone of the theme. User can override all (preferred) or some of those colors. User can also override any of the theme independent hardcoded colors like for example the red color of hangup button.
        • Available colors to override are:
          base1, base2, base3, base4, base5, base6, base7, base8, base9, base10, base11, defaultButtonColor, lightTextColor, darkTextColor, buttonHoverColor, tabSelectedColor, connectingColor, disconnectedColor, notificationBackgroundColorInformation, notificationBackgroundColorSuccess, notificationBackgroundColorError, notificationBackgroundColorWarning, notificationIconColorError, notificationIconColorWarning, userAvailableColor, userUnavailableColor, errorColor,​
      • light - Default text color, hover colors and rule of which base color is chosen for SideNav and MainHeader depend on this boolean.
    • The above mentioned parameters together with the built in color -> component css props mapping result in final theme where each component has a set of color specific css props. Should this not suffice there is a final step of providing overrides property that allows for overriding any parts of this result. Documenting that object is beyond the scope of this changelog, it is easiest to just monitor that object in debugger and decide on what params to change.


// Picks the default blue dark theme
config.colorTheme = "BlueDarkTheme";
// Picks dark theme, changes all of its base colors to new ones and tells the system that we still expect it to take the theme as dark (light parameter)
config.colorTheme = {
     name: "DarkTheme",
     colors: {
         base1: "blue",
         base2: "orange",
         base3: "yellow",
         base4: "black",
         base5: "white",
         base6: "pink",
         base7: "red",
         base8: "blue",
         base9: "brown",
         base10: "black",
         base11: "white"
     light: false;
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.