Flex WebChat UI Release Notes

This page includes the release notes related directly to Flex WebChat UI. Visit the Twilio Changelog and select "Flex" to see the Flex Backend Changelog.

v 2.9.3

release date September 15, 2023


  • Fixed support for .me links in markdown in CDN version

v 2.9.2

release date September 15, 2023


  • Fixed support for .me links in markdown in NPM version

v 2.9.1

release date June 15, 2021

Dependencies updated

  • Upgraded Handlebars version to 4.7.7

v 2.9.0

release date May 11, 2021


  • A fix to allow markdown links to be rendered correctly even if there is a space between the link text and the url it's linking to

v 2.8.1

release date FEB 26, 2021


  • Characters being dropped intermittently when typing in the input field

v 2.8.0

release date FEB 24, 2021


  • Added .app domain to the allow list


  • Fixed the issue with WebChat not loading in mobile Safari
  • Fixed the markdown code element overflow bug

v 2.7.1

release date JAN 13, 2021

Dependencies updated

  • [axios] To version 0.21.1

v 2.7.0

release date DEC 9, 2020

Added / Changed

  • Markdown feature improvements including support for new elements (headings, ordered lists, code snippets, block quotes) and several bugfixes. Note, implementation now relies more on semantic HTML, so if you have styled generic html elements, keep an eye on how they look in chat.

Dependencies updated

New versions of dependencies can contain changes in internal APIs that we do not document in release notes. If you’re using any undocumented apis of upgraded dependencies, please review your code and update your customizations as needed. Any changes in undocumented api's are not considered breaking changes, however, if you are using them, this might break your customizations.

Example: This version of chat-sdk contains changes in internal API. To access channel attributes, channel.attributes is supported as per and not channel.state.attributes.

v 2.6.1

release date OCT 27, 2020

  • Upgraded lodash transient dependency in CDN bundle to remove a security vulnerability
  • Fixed a bug with drag and drop into chat input field

Dependencies updated

  • [handlebars] upgraded to version 4.7.6

v 2.6.0

release date SEP 16, 2020


  • You can now set character limit of a message programmatically. Default limit is 32768 characters

MessagingCanvas.defaultProps.charLimit = 1000


  • Size of CDN bundle has been reduced from 550kb to 390kb


  • Domain links with parameters, not separated by a slash, are now recognised as links. For instance:

v 2.5.1

release date SEP 01, 2020

Web Chat UI API Reference for this version of Web Chat UI is available here


v 2.5.0

release date JUN 23, 2020


  • Image and file sharing for Web Chat channel in Pilot - Agents and Customers can now share images, documents and other files during a chat conversation. You can learn more about Chat attachments here.
  • A new boolean property in the MainContainer component called showNotificationBar which by default is `true`. It's used to render the notification bar below the main header. You can find out more about the Notifications Framework here


  • CSS font style fix for title child (key=text) in MessageCanvasTray

v 2.4.0

release date APR 27, 2020

Dependencies updated

  • [handlebars] to version 4.7.3

Handlebars Dependency Upgrade: Handlebars provides templating for the strings exposed by Flex UI and Flex WebChat UI. In this release we are upgrading Handlebars to 4.7.3 to fix critical security vulnerabilities exposed in previous versions of Handlebars. This may be a breaking change if you use certain undocumented Handlebars features. You can find more information about this change at the following link.


  • We restructured our internal dependencies and stopped using a bundled dependency for our internal libraries. Developers can now manage their project dependencies using yarn.


  • Improved chat message input rendering performance by debouncing store update on keypress.
  • Fixed illegal unquoted character error when submitting WebChat messages via Enter button.

v 2.3.1

release date MAR 04, 2020


  • Highlight URLs in chat messages only if they are not part of another string

v 2.3.0

release date JAN 16, 2020


  • Issue with WebChat messages being marked as read
  • Attempt to create a manager instance using incompatible redux store will now throw an error instead of string


  • MainContainer max-height set to 80vh to make webchat accessible from smaller screens.

v 2.2.1

release date OCT 30, 2019


  • Numbered List support for Markdown has been temporarily suspended due to some side effects found with the implementation. All other markdown options are still available as part of the released feature. Find out more about Markdown support here

v 2.2.0

release date OCT 07, 2019



  • WebChat now has basic markdown support. A user can use Flex standard markdown syntax when typing a WebChat message and it will be displayed to agent and WebChat user as formatted text

Screenshot 2019-10-07 at 23.56.38.png

  • Messages with markdown syntax can also be sent with Programmable Chat REST API into the chat channel using the same Flex markdown syntax and they will displayed for Flex and WebChat users as formatted text.
  • Flex user must be using Flex UI V1.4.0 or later
  • Flex standard markdown syntax:









Bullet list

* List

* List

* List

Numbered list

1. One

2. Two

3. Three


  • The Message Input component’s useLocalState flag is obsolete
  • Typing indicator in chat canvas now shows count of people typing if that number is above 1.

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

v 1.0.0

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