Migrate 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 to 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
  • Flex Conversations replaces Programmable Chat
  • Flex WebChat is not supported with Flex UI 2.x.x. If you are using WebChat, we recommend that you build with Flex Conversations once you migrate to Flex UI 2.x.x. You also have the option to switch to the Twilio Webchat React App.
  • There is a new Theming interface
  • State management has changed
  • Sync usage has changed

For details on each Flex UI interface mentioned in this migration guide, their description and usage code examples, check out the Flex UI API docs.

If your migration doesn't go as planned, you can roll back your changes to use Flex UI 1.x.x if necessary.

Before you begin

Review these resources to learn more about Flex UI 2.x.x:

Migration process overview

Try the migration in a test environment first. Starting with a test environment enables you to identify and correct any unexpected effects without impacting your production application.

The following sections outline high-level migration steps that you must take:

Without custom plugins

If you don’t have any custom plugins for Flex UI, complete the following steps:

  1. Ensure that you have read Set up your account with Flex Conversations: Prerequisites. Flex UI 2.x.x is designed to work with Conversations.
  2. Enable Flex UI 2.x.x on your account.

With custom plugins

If you have deployed custom plugins to Flex UI, complete the following steps to ensure that your plugins will work with Flex UI 2.x.x:

  1. Review Flex UI 2.x.x updates that can affect your customizations to understand what updates you will need to make.
  2. Ensure that you have read Set up your account with Flex Conversations: Prerequisites. Flex UI 2.x.x is designed to work with Flex Conversations.
  3. Disable your existing 1.x.x-based plugins.
  4. Enable the latest version of Flex UI on your account using the Versioning and Updates page on
  5. Update dependencies to be compatible with Flex 2.x.x.
  6. Test your plugins in Flex UI 2.x.x. If necessary, update your plugins for Flex 2.x.x.
  7. Apply any updates to your customizations that you identified in step 1.
  8. Deploy your Flex UI 2.x.x plugins.
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!