Configure the Flex WebChat 2.0 UI

This guide is for Flex UI 1.x.x and channels that use Programmable Chat and Proxy. If you are using Flex UI 2.x.x or you are starting out, we recommend that you build with Webchat 3.0.

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

You can change the Flex WebChat 2.0 look, feel, and behavior via configuration settings. You can override any of the default configuration values.

There are two ways to configure the Flex UI:

Using the Basic Configuration

Basic configuration allows you to do simple customizations to WebChat display options and behavior. With a few lines of code you can make changes like:

  • Show or hide the logo in the header
  • Change the properties of any WebChat component
  • Pass context for routing or to be displayed to an agent
  • Configure how the author of the message is displayed
  • Show or hide a typing indicator or message read receipt

and much more.

Configuration object

In the configuration object, you can define default properties to WebChat Components (listed below) and also configure properties that are not tied to specific Components.

WebChat default configuration

const defaultConfiguration: Config = {
    disableLocalStorage: false,
    available: true,
    colorTheme: {
        baseName: "BlueMediumTheme"
    componentProps: {
        MessagingCanvas: {
            avatarCallback: (identity: string) => SessionActions.getAgentAvatar(identity),
            showTrayOnInactive: true
        MessageCanvasTray: {
            onButtonClick: () => Actions.invokeAction("RestartEngagement")
    tokenServerUrl: "{accountSid}/Tokens",
    flexWebChannelsUrl: "",
    context: {
        friendlyName: "Anonymous"
    startEngagementOnInit: true,
    sdkOptions: {
        chat: {}

WebChat basic configuration properties

Variable name Type Description


string The identifier for the Twilio account to which you want to connect the Webchat instance.


string The unique identifier for the Flex Flow that will handle messages.


string Friendly name to use for created chat channels
available boolean Chat service availability. It sets whether to display the EntryPoint or not



Specificity of log output

0 – 'trace'

1 – 'debug'

2 – 'info'

3 – 'warn'

4 – 'error'

5 – 'silent'


json object Context object. Metadata that gets passed to backend about the request


json object Theme configuration


boolean Configuration to disable local storage


json object pre-engagement form


boolean pre-engagement form on/off


json object

Represents defaultProps of each component in WebChat. See above for an example


json object

Tailor SDK parameters

voice: {},
worker: {},
chat: {},
insights: {}


json object

Disabled by default. Config object needs to be enabled for Chat Markdown Support:

enabled: true


string Token server URL


string Flex WebChannels URL

React default props API

You may also configure default properties for components using the React defaultprops API.

componentProps: { [Component Name]: { [Prop Name]: [PropValue] } }

Examples of setting props for Components:

FlexWebChat.MainHeader.defaultProps.showImage = true;

This example sets logo to be shown in the main header

Component props

You can find the full list of WebChat components here. Below are the lists of component-specific props for the following components:


Prop Name Type Description
startEngagementOnInit boolean pre-engagement form on, on chat startup
height string Height of the expanded webchat
width string

Width of the expanded webchat

bottom string

Distance from webchat bottom to the bottom of the screen

right string

Distance from webchat right side to right edge of the screen


Prop Name Type Description
hideTaglineWhenExpanded boolean

Tells if the tagline has to be hidden when expended

iconClosed string

Represents icon to be shown when not expanded. Example: "MessageBold"

collapsedIconAriaProps AriaProps

Collapsed icon aria props.

openedIconAriaProps AriaProps

Opened icon aria props.

iconExpanded string

Represents icon to be shown when expanded. Example: "ArrowDown"

tagline string

tagline content


Prop Name Type Description
titleText string

Override header title of the expanded webchat

imageUrl string

Override header logo of the expanded webchat

showTitle boolean

Should the title be displayed in the header

showImage boolean

Should the logo be displayed in the header

closeCallback Function

A callback to trigger when close button is clicked. Example:

closeCallback: () => {




Prop Name Type Description
PredefinedMessage json object

Represents an initial automated message, shown in the chat. See below for an example.

avatarCallback (identity: string) => string Callback function to return avatar URL of a member

json object

Allows to override chat participant names, e.g. setting agent to Agent and customer to Customer. See an example below.

messageStyle string

Defines the visual style of the message area. Options are "Rounded", "Squared", and "Minimal"

showReadStatus boolean Controls if message read indicator will be shown
showTypingIndicator boolean Controls if [SomeOne] is typing will be shown
showWelcomeMessage boolean Controls if welcome message will be shown at the beginning of the conversation


Text displayed as a welcome message

showTrayOnInactive boolean

Display message tray component, indicating that the chat is no longer active whenever channel status is inactive

charLimit number

Identifies character limit for a single message

inputDisabledReason string

A reason on why the input element is disabled

autoInitChannel MessagingCanvas.autoInitChannel

Should the component automatically initialize chat channel if not initialized already.


PredefinedMessage represents an initial automated message, shown in the chat

  • body - content of the message
  • authorName - name of the author
  • isFromMe - whether it appears as message from the current user or not

Turning the PredefinedMessage off:

FlexWebChat.MessagingCanvas.defaultProps.predefinedMessage = false;


Allows to override chat participant names, e.g. setting agent to Agent and customer to Customer.

Example of setting a default message author instead of using member friendlyName:


yourDefaultName: 'You',

theirDefaultName: 'Agent',

yourFriendlyNameOverride: false,

theirFriendlyNameOverride: false



Prop Name Type Description
useFriendlyName boolean

Override chat participant name with a friendly name

messageStyle string

Visual style of the individual message. Options are "Rounded", "Squared", and "Minimal"

authorName string

A custom author name to be used

useFriendlyName boolean

Use friendlyName as author name instead of custom authorName


Url to the avatar of the author


An object which represents a single message.


Prop Name Type Description
areaStyle string Visual style of the text input element.
disabledReason string A reason on why MessageInput is disabled.
sendButtonAriaProps AriaProps SendButton aria props
textAreaAriaProps AriaProps TextArea aria props
charLimit number Identifies character limit for a single message.
returnKeySendsMessage boolean Whether pressing the return key should send a message
useLocalState boolean

If set to true, it keeps the message value in the local component state, instead of the Redux state. Please set it to false if you want to set the input value using the "SetInputText" action.


Prop Name Type Description
showButton boolean

Display a ‘Start new chat’ button in the tray

onButtonClick () => void A handler for a 'Start new chat' button click

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!