Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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(link takes you to an external page) 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:

  • via componentProps in the Configuration Object
  • via the defaultProps API

Using the Basic Configuration

using-the-basic-configuration page anchor

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.

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

webchat-default-configuration page anchor

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

webchat-basic-configuration-properties page anchor
Variable nameTypeDescription
accountSidstringThe identifier for the Twilio account to which you want to connect the Webchat instance.
flexFlowSidstringThe unique identifier for the Flex Flow that will handle messages.
chatFriendlyNamestringFriendly name to use for created chat channels
availablebooleanChat service availability. It sets whether to display the EntryPoint or not
logLevelstringSpecificity of log output 0 - 'trace'

1 - 'debug'

2 - 'info'

3 - 'warn'

4 - 'error'

5 - 'silent'
contextjson objectContext object. Metadata that gets passed to backend about the request
colorThemejson objectTheme configuration

booleanConfiguration to disable local storage
preEngagementConfigjson objectpre-engagement form

booleanpre-engagement form on/off

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

json objectTailor SDK parameters

{ voice: {}, worker: {}, chat: {}, insights: {} }
markdownSupportjson objectDisabled by default. Config object needs to be enabled for Chat Markdown Support:

{ enabled: true }
tokenServerUrlstringToken server URL
flexWebChannelsUrlstringFlex WebChannels URL

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

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


maincontainer page anchor
Prop NameTypeDescription
startEngagementOnInitbooleanpre-engagement form on, on chat startup
heightstringHeight of the expanded webchat
widthstringWidth of the expanded webchat
bottomstringDistance from webchat bottom to the bottom of the screen
rightstringDistance from webchat right side to right edge of the screen
Prop NameTypeDescription
hideTaglineWhenExpandedbooleanTells if the tagline has to be hidden when expended
iconClosedstringRepresents icon to be shown when not expanded. Example: "MessageBold"
collapsedIconAriaPropsAriaPropsCollapsed icon aria props.
openedIconAriaPropsAriaPropsOpened icon aria props.
iconExpandedstringRepresents icon to be shown when expanded. Example: "ArrowDown"
taglinestringtagline content
Prop NameTypeDescription
titleTextstringOverride header title of the expanded webchat
imageUrlstringOverride header logo of the expanded webchat
showTitlebooleanShould the title be displayed in the header
showImagebooleanShould the logo be displayed in the header
closeCallbackFunctionA callback to trigger when close button is clicked. Example:

closeCallback: () => { Actions.invokeAction("MinimizeChat"); }
Prop NameTypeDescription
PredefinedMessagejson objectRepresents an initial automated message, shown in the chat. See below for an example.
avatarCallback(identity: string) => stringCallback function to return avatar URL of a member
memberDisplayOptionsjson objectAllows to override chat participant names, e.g. setting agent to Agent and customer to Customer. See an example below.
messageStylestringDefines the visual style of the message area. Options are "Rounded", "Squared", and "Minimal"
showReadStatusbooleanControls if message read indicator will be shown
showTypingIndicatorbooleanControls if [SomeOne] is typing will be shown
showWelcomeMessagebooleanControls if welcome message will be shown at the beginning of the conversation
welcomeMessageTextCompiledTemplateText displayed as a welcome message
showTrayOnInactivebooleanDisplay message tray component, indicating that the chat is no longer active whenever channel status is inactive
charLimitnumberIdentifies character limit for a single message
inputDisabledReasonstringA reason on why the input element is disabled
autoInitChannelMessagingCanvas.autoInitChannelShould 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 NameTypeDescription
useFriendlyNamebooleanOverride chat participant name with a friendly name
messageStylestringVisual style of the individual message. Options are "Rounded", "Squared", and "Minimal"
authorNamestringA custom author name to be used
useFriendlyNamebooleanUse friendlyName as author name instead of custom authorName
avatarUrlUrl to the avatar of the author
messageAn object which represents a single message.
Prop NameTypeDescription
areaStylestringVisual style of the text input element.
disabledReasonstringA reason on why MessageInput is disabled.
sendButtonAriaPropsAriaPropsSendButton aria props
textAreaAriaPropsAriaPropsTextArea aria props
charLimitnumberIdentifies character limit for a single message.
returnKeySendsMessagebooleanWhether pressing the return key should send a message
useLocalStatebooleanIf 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 NameTypeDescription
showButtonbooleanDisplay a 'Start new chat' button in the tray
onButtonClick() => voidA handler for a 'Start new chat' button click

Rate this page: