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 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 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 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:
|
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:
|
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
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.