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?

Installing and using Flex WebChat

Auto-Generated Documentation for the Flex Webchat UI is now available as a beta distribution. The auto-generated documentation is accurate and comprehensive but may differ from what you see in the official Flex Webchat UI documentation.

What is Flex WebChat?

Flex WebChat is a chat widget that you can embed on your website. The widget helps your customers chat with an agent without needing to leave your webpage. It is natively integrated with the Flex Contact Center.

What can you do with WebChat?

The Flex WebChat experience is fully customizable. WebChat can be customized in the following ways:

The following WebChat documentation applies to WebChat version 2.0.0 or higher. Please refer to the release notes to see what has changed since version 2.0.0

Getting started with WebChat

There are currently two ways to consume Flex WebChat:


To get access and set up Flex WebChat, you will need to complete the Flex Quickstart first.

Consuming from CDN

There are 2 ways to add Flex WebChat from CDN.

Option 1

The following steps are the quickest way to add Flex WebChat to your app. However, a CDN setup will not allow for more advanced programmability of the initialization flow for Flex WebChat.

1. Add the following script tag to the index.html head tag to include WebChat bundle from CDN

<script src=""></script>

2. Add the following script tag to the index.html body tag to initialize WebChat

            const appConfig = {

Option 2

The following steps will allow you to customize FlexWebChat initialization flow before you render the WebChat, as it consists of two parts – initialize and render – and allows you to tap into customization before the render method executes.

Twilio.FlexWebChat.createWebChat(appConfig).then(webchat => {
    const { manager } = webchat;
//Posting question from preengagement form as users first chat message
    Twilio.FlexWebChat.Actions.on("afterStartEngagement", (payload) => {
        const { question } = payload.formData;
        if (!question)

        const { channelSid } =;
            .then(channel => channel.sendMessage(question));
// Changing the Welcome message
    manager.strings.WelcomeMessage = "New text for welcome message";

// Render WebChat

You can find your flexFlowSid and accountSid on the 'Developer Setup' page within the admin view of Flex.

Consuming from NPM and running locally

We provide a sample project based on create-react-app to get you started with consuming @twilio/flex-webchat-ui package from npm. This sample project is available on GitHub at

To get started with the sample project, do the following steps:

1. Clone the sample project from GitHub

$ git clone

2. Go to flex-webchat-ui-sample, install dependencies, and run the sample project

cd flex-webchat-ui-sample
npm install
npm start

3. Your local Flex UI will be running on http://localhost:8081

WebChat default behaviour


Out of the box, the WebChat is configured to initiate chat (trigger startEngagement action) on user entryPoint click. The following steps happen on start of the engagement:

  • Token is issued
  • Chat channel is created
  • Programmable chat user is created with default friendlyName and added as a member to the channel
  • MessagingCanvas is loaded with the created channelSid
  • A predefined message is shown to the user as a call to action.

WebChat is one of the channels for Flex and is integrated with it out of the box. When a incoming message is sent to the chat channel, this triggers a Studio Flow. By default, this is the 'Webchat Flow', which you can customize within the Twilio Console.

The first incoming message on the chat channel will trigger a new execution on the Studio flow. Here you can automate a conversation using the 'Send & Wait for Reply' widget before passing the conversation directly to an agent with the 'Send to Flex' widget.

The 'Send to Flex' widget will create a TaskRouter task with the attributes provided, and it will remove the chat channel webhook so that future incoming messages won't retrigger the Studio flow.

Pre-engagement data can be accessed by Studio's Liquid syntax. For example you could include in the 'Send to Flex' widget:

{"question": "{{trigger.message.ChannelAttributes.pre_engagement_data.question}}"}

What's next?

Now that you are all set up and got WebChat running, you can:

and much more!

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.