Configure the Flex WebChat UI

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

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.

You can change the Flex WebChat 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

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: "https://iam.twilio.com/v1/Accounts/{accountSid}/Tokens",
    flexWebChannelsUrl: "https://flex-api.twilio.com/v1/WebChannels",
    context: {
        friendlyName: "Anonymous"
    },
    startEngagementOnInit: true,
    sdkOptions: {
        chat: {}
    }
};

WebChat basic configuration properties

Variable name	Type	Description
accountSid	string	The identifier for the Twilio account to which you want to connect the Webchat instance.
flexFlowSid	string	The unique identifier for the Flex Flow that will handle messages.
chatFriendlyName	string	Friendly name to use for created chat channels
available	boolean	Chat service availability. It sets whether to display the EntryPoint or not
logLevel	string	Specificity of log output 0 – 'trace' 1 – 'debug' 2 – 'info' 3 – 'warn' 4 – 'error' 5 – 'silent'
context	json object	Context object. Metadata that gets passed to backend about the request
colorTheme	json object	Theme configuration
disableLocalStorage	boolean	Configuration to disable local storage
preEngagementConfig	json object	pre-engagement form
startEngagementOnInit	boolean	pre-engagement form on/off
componentProps	json object	Represents defaultProps of each component in WebChat Example: `componentProps: {` `MessagingCanvas: {` `avatarCallback:(identity:string)=>SessionActions.getAgentAvatar(identity),` `showTrayOnInactive:true},` `MessageCanvasTray: {onButtonClick:()=>Actions.invokeAction("RestartEngagement")` `}` `},`
sdkOptions	json object	Tailor SDK parameters { voice: {}, worker: {}, chat: {}, insights: {} }
markdownSupport	json object	Disabled by default. Config object needs to be enabled for Chat Markdown Support: `{` `enabled: true` `}`
tokenServerUrl	string	Token server URL
flexWebChannelsUrl	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:

MainContainer
EntryPoint
MainHeader
MessagingCanvas
MessageListItem
MessageInput
MessageCanvasTray

MainContainer

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

EntryPoint

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

MainHeader

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: () => { Actions.invokeAction("MinimizeChat"); }

MessagingCanvas

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
memberDisplayOptions	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
welcomeMessageText	CompiledTemplate	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

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;

memberDisplayOptions

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

}

MessageListItem

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
avatarUrl		Url to the avatar of the author
message		An object which represents a single message.

MessageInput

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.

MessageCanvasTray

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

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.

Need some help?

Thank you for your feedback!

Thanks for your feedback!