Configuration
Tailor the chat to your needs by initializing it with your own custom options.
Contents
Overview
Configuration options object
Messaging configuration
Theme configuration
Layout configuration
Header configuration
Service desk configuration
Creating links to the AI chat
Listening for errors
Overview
Configuration options pass in when the AI chat initially starts and represents the static properties that do not change during a session with the chat.
Configuration options object
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| Core options | ||||
| messaging | Object |
Required | Configures communication with your server. For more information, see messaging. | |
| Theming and layout | ||||
| element | Element |
Defines the containing DOM element where the AI chat widget renders. The widget grows to the size of the specified DOM element and appears in the element's location on the page. By default, the widget generates its own element. If you specify your own element, you must provide your own launching mechanism and set showLauncher to false. If you use a custom element, change the styles of the element for the main web widget window to hide or show it. For custom animations, apply animation styles. For more information, see tutorial for using a custom element. |
||
| layout | Object |
Controls the layout behavior of the AI chat. For more information, see Layout configuration. | ||
| openChatByDefault | Boolean |
false | Determines whether the chat window initially renders in an open state when your page loads. By default, the chat window remains closed. | |
| showLauncher | Boolean |
true | Determines whether the chat launcher icon appears. If you set this option to false, your website code must call instance.openWindow() to open the chat window. Alternatively, use openChatByDefault and hideCloseButton to display a permanently open AI chat. For more information, see tutorial for using a custom launcher. |
|
| themeConfig | Object |
Controls the theming behavior of the AI chat. For more information, see Theme options. | ||
| headerConfig | Object |
Configures the behavior of the header. For more information, see Header config. | ||
| Human agents | ||||
| serviceDesk | Object |
Controls the behavior of service desk integrations. For more information, see Service desk configuration. | ||
| Less commonly used options | ||||
| disableCustomElementMobileEnhancements | Boolean |
false | Disables mobile enhancements when using element to specify a custom element. The AI chat improves the behavior of the widget when displaying in full-screen mode on a mobile device. It includes resizing the AI chat when the keyboard opens and changes in the zoom level of the view. If you are using a custom element, this functionality can interfere with how your element renders or its layout. To disable them, use this flag. If you do not use a custom element, this flag has no effect. | |
| disclaimer | Object |
Accepts an object with two arguments. isOn accepts a boolean. If set to true, the AI chat requires a user to accept your disclaimer before they can interact with your assistant. disclaimerHTML provides the disclaimer text (or full html) that a user must accept. The browser stores the disclaimer whether or not the user accepts it, The browser memory stores the disclaimer until the user closes the browser. |
||
| pageLinkConfig | Object |
true | Pre-configures a set of page link IDs that the AI chat recognizes when a user goes to your page with an ID included as a URL parameter. These IDs trigger different greeting messages, allowing you to generate links to the AI chat that can start specific conversations. For more information, see Creating links to AI chat. | |
| debug | Boolean |
false | Enables extra console logging. | |
| onError | Function |
Calls the callback when an error occurs within the AI chat. Errors that occur when the AI chat is loading and errors that occur later, such as errors that occur when the user tries to send a message to the assistant. For more information, see Listening for errors. | ||
| namespace | String |
Load multiple AI chats on the same page when needed, give them each a unique namespace to avoid conflicts. Using this property also changes your default CSS selector for styling components inside the AI chat. For more information, see namespaces. |
||
| shouldSanitizeHTML | Boolean |
false | Sanitizes HTML in messages before displaying them. By default, the AI chat allows your assistant to provide HTML and it renders that HTML as-is, included things like scripts or event listeners that are in HTML. This flag changes that behavior and removes any potentially harmful or unknown content from any HTML including script tags and event listeners. | |
| disablePDFViewer | Boolean |
Disables the internal AI chat PDF viewer. If true, the AI chat presents links to PDFs that open in the user's web browser instead of the AI chat viewer. This option is useful if the server hosting the PDF documents does not support CORS which is required for using the AI chat viewer. | ||
| disableWindowTitleChanges | Boolean |
false | Changes the title of the window/document to inform users of unread messages received while the AI chat is not visible. You can use this property to disable this functionality so the AI chat does not make any changes to the window title. | |
| enableFocusTrap | Boolean |
false | Activates a focus trap when AI chat opens. It locks focus inside the AI chat and the user cannot move focus outside the AI chat until they close it. Additionally, a semi-transparent background is placed behind the AI chat that prevents the user from interacting with other elements on the page. This property has no effect if you also use hideCloseButton. |
|
| shouldTakeFocusIfOpensAutomatically | Boolean |
true | Moves focus to the input field automatically when the AI chat opens upon page load. It applies when the chat is stored in an open state by session history or if you have openChatByDefault set to true. |
|
Messaging configuration
The AI chat provides various options for how to configure the AI chat to work with your server.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| messaging.customSendMessage | Function |
Required | Takes the message request, requestOptions and the instance of the chat as arguments. See the following examples for more details. | |
| messaging.customLoadHistory | Function |
Takes the instance of the chat as an argument. If defined, the AI chat calls this function to load in your conversation history. See the following examples for more details. | ||
| messaging.copyPreviousContextOnRequest | Boolean |
true | Keeps a local copy of the context and merge new values by default. If you want to handle the statefulness of the context on your server, set it to false |
|
| messaging.messageTimeoutSecs | Number |
40 | Throws a communication error if customSendMessage returns a promise that does not resolve within the specified amount of seconds. Calling instance.messaging.addMessage or instance.messaging.addMessageChunk also prevents a timeout message from showing. |
|
| messaging.messageLoadingIndicatorTimeoutSecs | Number |
4 | Shows a loading indicator if customSendMessage returns a promise that does not resolve within the specified amount of seconds. Calling instance.messaging.addMessage or instance.messaging.addMessageChunk also prevents the loading indicator from showning. |
|
| messaging.skipWelcome | Boolean |
false | Sends an empty messsage to the server when the chat starts to request a greeting message by default. This message request contains history.is_welcome_request as a boolean. Set this option to false, if you don't want a hard coded greeting message. |
Theme configuration
The AI chat allows you to pick a base theme and then adjust individual colors. To learn about adjusting individual colors, see instance.updateCSSVariables().
You can customize the Carbon theme of the AI chat. Choose one of four Carbon themes by using the carbonTheme property:
- White
- Gray 10
- Gray 90
- Gray 100
The light themes include White and Gray 10, while Gray 90 and Gray 100 provide dark grays and blacks. You also have fine-grained control over individual properties with the updateCSSVariables instance method.
For more information, see AI chat configuration.
| Parameter | Type | Default | Description |
|---|---|---|---|
| themeConfig.carbonTheme | String |
g10 | Use the carbonTheme option to theme your widget with a Carbon Theme as defined in the Carbon Design System. Accepted values are "white", "g10", "g90" or "g100". Defaults to "g10". You can override specific theming variables after setting a core theme. |
| themeConfig.corners | String |
'round' | Change the type of corners to give the AI chat widget. Accepted values are "square" or "round". |
Layout configuration
The AI chat provides a layout configuration that allows you to modify the widget frame and content.
| Parameter | Type | Default | Description |
|---|---|---|---|
| layout.showFrame | Boolean |
true | Indicates whether the AI chat frame displays. It includes the border and box-shadow on the outside of the main window. |
| layout.hasContentMaxWidth | Boolean |
true | Indicates whether the AI chat content constrains to a max-width for wide AI chat layouts. The max-width of the chat content is 627px. |
Header configuration
This object has some general configuration settings used for controlling the behavior of the header.
| Parameter | Type | Default | Description |
|---|---|---|---|
| headerConfig.minimizeButtonIconType | String |
'minimize' | Indicates what icon to use in the place of the minimize button in the header. The possible values are: minimize, close (X icon), side-panel-left and side-panel-right. |
| headerConfig.hideMinimizeButton | Boolean |
false | Indicates whether to hide the UI control that closes the chat window. Use this feature along with openChatByDefault if you want the AI chat to stay open on your page, or if you provided your own DOM element to contain the AI chat. |
| headerConfig.showRestartButton | Boolean |
false | Indicates whether or not the restart button displays in the header. You cannot use this feature with showCloseAndRestartButton |
| headerConfig.showCloseAndRestartButton | Boolean |
false | Indicates whether or not the close-and-restart button displays in the header. It adds an additional "X" button next to the close/minimize button. This button restarts the conversation that a user has with the bot and closes the AI chat window. It also ends any conversation with a human agent. If the user re-opens the AI chat, the bot conversation clears, and a new conversation begins. The user can still see the conversation history with an agent, but the user must start a new conversation if they want to chat with a human agent again. You cannot use this feature with showRestartButton. |
Service desk configuration
When the AI chat configures a service desk integration, this object controls the options that the AI chat provides for how it interacts with the integration. You can add this object to the top level configuration option under the serviceDesk property.
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceDesk.agentJoinTimeoutSeconds | Number |
(disabled) | The timeout value in seconds when the user is waiting for an agent to join after the user requests an agent. If no agents join the chat before this timeout, then the agent chat ends and the user receives an error message. If you do not define this value, then there is no timeout. |
| serviceDesk.availabilityTimeoutSeconds | Number |
5 | The timeout value in seconds when determining agent availability. When a "Connect to agent" response is received, the system asks the service desk if any agents are available. If no response is received within the timeout window, the system returns "false" to indicate no agents are available. |
| serviceDesk.disableAgentSessionHistory | Boolean |
false | Indicates whether the assistant stores a conversation between the user and a human agent in its session history. By default, when the user engages in a conversation with a human agent, all messages during that conversation are stored in session history so they can be retrieved if the user reloads the AI chat. To opt-out of this behavior, set this value to true. When set to true, these messages are never sent to the assistant. |
| serviceDesk.skipConnectAgentCard | Boolean |
false | Indicates whether the AI chat auto-connects to an agent whenever it receives a "Connect to agent" response and agents are available. It mimics the user clicking the "request agent" button at the top of the chat window. The user sees the "agents available" text from the response. |
Creating links to the AI chat
If you want to create a link to the AI chat that opens it and starts a conversation from a specific topic, you can use the pageLinkConfig configuration option. Use this configuration if you want to send an email to your customers with a link for something like "Click here to update your account". This link takes the customer to your website, open the AI chat, and begin the conversation with your "update account" conversation.
Pre-configure a set of link IDs that you can include in your external URLs. When the AI chat recognizes one of these IDs, it automatically opens and sends a message to your assistant by using the text that you configured for that ID. Your skill needs to recognize this text and start the conversation. This text is not visible to the user.
Configuration
To use a pre-configured ID, add it to any link to your website that uses the AI chat by using the URL parameter wa_lid.
To define the IDs, use the pageLinkConfig embed script configuration property, which has the following structure. You can use any text that you want for the IDs but we recommend that you use only numbers and letters in your link IDs since not all characters are allowed in URLs. And we recommend sticking to values that are not immediately obvious to your customers (e.g. make your link ID "abc123" instead of "update-account") to avoid customers trying to abuse or manipulate the values.
Then you can generate a link to your website that can look something like https://mywebsite.com/accounts?wa_lid=u35.
Note: If links to your website already have ? in them, you need to use & instead: https://mywebsite.com/?page=accounts&wa_lid=u35.
| Property | Type | Description |
|---|---|---|
| pageLinkConfig.linkIDs | Object |
This object defines all the recognized link IDs. |
| pageLinkConfig.linkIDs[id] | Object |
This value is an object that represents how the AI chat responds when it recognizes the ID. |
| pageLinkConfig.linkIDs[id].text | String |
This text is what your assistant recieves when it recognizes the ID. |
Listening for errors
Your AI chat configuration can include an onError option that acts as a callback where the AI chat calls when errors occur within the AI chat. These errors can occur in the initialization phases of the AI chat or they can occur later when your user is using the AI chat. Below are the details of what data passes to this callback when different errors occur.
Error data
The onError function is called with a single parameter that contains the following properties:
| Property | Type | Description |
|---|---|---|
| errorType | String |
The type of error the system reports. |
| message | String |
The text description of the error. |
| errorCode | Number |
The code associated with the error. The value provided here depends on what error type the system reports. |
| otherData | Anything |
The extra data that associates with the error. It can be a stack trace for example. |
Error types
| Error type | Description |
|---|---|
| HYDRATION | Occurrs when the AI chat tries to load but cannot load the necessary data to start. This error indicates a problem trying to fetch the welcome information and often appears with other errors. |
| MESSAGE_COMMUNICATION | Occurs when there was an error sending a message from the user to the assistant. This error fires after all the retry attempts fail and the AI chat gives up. In this case, the errorCode contains the HTTP response code from the request. |
| RENDER | Occurs when the AI chat encounters an error while rendering. The otherData contains the stack trace and other details about the error. |