Configure the Flex WebChat 2.0 UI
Warning
Webchat 2.0 is no longer supported. It uses Flex UI 1.x.x's legacy messaging, which has reached end-of-life.
If you are using Webchat 2.0, migrate to Webchat 3.x.x.
If you are starting out with Webchat, build with Webchat 3.x.x instead.
Info
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:
- via
componentProps
in the Configuration Object - via the defaultProps API
Basic configuration allows you to do 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.
1const defaultConfiguration: Config = {2disableLocalStorage: false,3available: true,4colorTheme: {5baseName: "BlueMediumTheme"6},7componentProps: {8MessagingCanvas: {9avatarCallback: (identity: string) => SessionActions.getAgentAvatar(identity),10showTrayOnInactive: true11},12MessageCanvasTray: {13onButtonClick: () => Actions.invokeAction("RestartEngagement")14}15},16tokenServerUrl: "https://iam.twilio.com/v1/Accounts/{accountSid}/Tokens",17flexWebChannelsUrl: "https://flex-api.twilio.com/v1/WebChannels",18context: {19friendlyName: "Anonymous"20},21startEngagementOnInit: true,22sdkOptions: {23chat: {}24}25};
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. See above for an 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:{ enabled: true } |
tokenServerUrl | string | Token server URL |
flexWebChannelsUrl | string | Flex 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:
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: () => { Actions.invokeAction("MinimizeChat"); } |
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 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:
1{2yourDefaultName: 'You',3theirDefaultName: 'Agent',4yourFriendlyNameOverride: false,5theirFriendlyNameOverride: false6}
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. |
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 |