Configuration
Tailor the chat to your needs by initializing it with your own custom options.
Contents
Overview
Configuration options object
Theme configuration
Layout configuration
Header configuration
Service desk configuration
Server configuration
Creating links to web chat
Listening for errors
Overview
When you create a web chat integration, the watsonx Assistant UI gives you a small embed code to add to your website:
Example
<script>
window.watsonAssistantChatOptions = {
// A UUID like '1d7e34d5-3952-4b86-90eb-7c7232b9b540' included in the embed code provided in watsonx Assistant.
integrationID: 'YOUR_INTEGRATION_ID',
// Your assistants region e.g. 'us-south', 'us-east', 'jp-tok' 'au-syd', 'eu-gb', 'eu-de', etc.
region: 'YOUR_REGION',
// A UUID like '6435434b-b3e1-4f70-8eff-7149d43d938b' included in the embed code provided in watsonx Assistant.
serviceInstanceID: 'YOUR_SERVICE_INSTANCE_ID',
// The callback function that is called after the widget instance has been created.
onLoad: async (instance) => {
await instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>
watsonAssistantChatOptions
define the web chat configuration options. By default, watsonx Assistant provides the embed code that configures only the integrationID
, serviceInstanceID
, and the region
parameters (enterprise plans also include subscriptionID
). These options also include an onLoad
callback that calls when the web chat's code loads and creates a new instance. You need to call render
on that instance to display the widget.
You can modify watsonAssistantChatOptions
with other parameters that control the immutable behavior of your web chat's instance.
If you need to run dynamic operations to generate your configuration for web chat, or you are using the namespace
configuration property to allow multiple web chats on the page, you can omit window.watsonAssistantChatOptions
and instead pass a configuration object into window.loadWatsonAssistantChat()
when you are ready to load the web chat. You need to adjust your code to make sure that window.loadWatsonAssistantChat
loads.
Configuration options object
The options
object assigned to watsonAssistantChatOptions
supports the following parameters:
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
Core options | ||||
integrationID | String |
Required | The integration ID of your web chat integration, it is exposed as a UUID (for example, 1d7e34d5-3952-4b86-90eb-7c7232b9b540 ). |
|
region | String |
Required | The data center where you created your integration (for example, us-south ). |
|
serviceInstanceID | String |
Required | The service instance ID of the assistant that hosts your web chat integration. It is exposed as a UUID (for example, 6435434b-b3e1-4f70-8eff-7149d43d938b ). |
|
subscriptionID | String |
The ID of your subscription. Enterprise instances require this option and is included in the code snippet when you create the web chat integration. If you are not using an enterprise instance, this ID is absent. | ||
onLoad | Function |
Required | The callback that is called when the web chat instance is loaded and created. You need to provide a function here that calls render on the provided instance to display the widget. |
|
clientVersion | String |
By default, web chat loads the latest version. You can also specify a specific major, minor or patch version. It is recommended you lock to a major version of web chat. See current web chat versions and change log to see current version information | ||
Theming and layout | ||||
element | Element |
The containing DOM element where the web chat widget is rendered within the page. The web chat widget grows to the size of the specified DOM element and appears in the location of the element on the page. By default, web chat generates its own element. If you use this option to specify your own element to contain web chat, you can also provide your own launching mechanism and set showLauncher to false . If you use a custom element, you are responsible for changing the styles of the element for the main web widget window to hide or show it. If you want custom animations, it allows you to apply animation styles. For more information, see tutorial for using a custom element. |
||
layout | Object |
This configuration object controls the layout behavior of web chat. For more information, see Layout configuration. | ||
openChatByDefault | Boolean |
false | Whether to render the chat window initially in an open state when your page loads. By default, the chat window initially renders in a closed state. | |
showLauncher | Boolean |
true | Whether to render the chat launcher icon that users can click to open the chat window. If you specify false , your website code is responsible for calling instance.openWindow() to open the chat window. Alternatively, you can use the openChatByDefault and hideCloseButton options to show a web chat that is always open. For more information, see tutorial for using a custom launcher. |
|
themeConfig | Object |
This configuration object controls the theming behavior of web chat. For more information, see Theme options. | ||
Header | ||||
hideCloseButton Deprecated | Boolean |
false | Moved to Header config. Whether to hide the UI control that closes the chat window. Use this option along with openChatByDefault if you want the web chat to always be open on your page, or if you provide your own DOM element to contain the web chat. | |
closePanelButtonConfig Deprecated | Object |
This configuration object changes the behavior of the close button when it is clicked. For more information, see closePanelButtonConfig. | ||
showRestartButton Deprecated | Boolean |
false | Moved to Header config. Indicates whether the restart button displays in the header. This feature cannot be used with showCloseAndRestartButton |
|
showCloseAndRestartButton Deprecated | Boolean |
false | Moved to Header config. Indicates whether or not the close-and-restart button is displayed in the header. It adds an extra "X" button to the header next to the close/minimize button. This button restarts the conversation that a user has with the bot and closes the web chat window. It also ends any conversation with a human agent. If the user re-opens web chat, the bot conversation clears, and a new conversation begins. The user can still see the conversation history with an agent, but they have to start a new conversation if they want to chat with a human agent again. This feature cannot be used with showRestartButton . |
|
Human agents | ||||
serviceDesk | Object |
This configuration object controls the behavior of service desk integrations. For more information, see Service desk configuration. | ||
Security and identity | ||||
cspNonce | String |
If you enable a Content-Security-Policy on your site that only permits elements with a defined nonce, you can provide that value here and the widget applies it to the script and style elements that the widget generates. |
||
identityToken | JWT token |
If you enable security features, this method takes a JWT to authenticate and authorize requests from web chat to watsonx Assistant. For billing purposes, it must include a sub claim to denote a userID. Optionally, you can leave this blank and only generate the JWT when web chat asks for a new JWT via event.For more information, see web chat security. |
||
disableCustomElementMobileEnhancements | Boolean |
false | This value indicates whether or not to disable the mobile enhancements when using element to specify a custom element. Web chat provides some functionality to improve the behavior of the widget when displaying in a full screen mode on a mobile device. It includes resizing web chat when the keyboard opens and accounts for 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 are not using a custom element, this flag has no effect. | |
disclaimer Beta | Object |
This value accepts an object with two arguments. isOn accepts a boolean. If set to true , web 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. Wether or not the user accepts the disclaimer, it is stored in the browser memory until the browser is closed. |
||
pageLinkConfig | Object |
true | This option pre-configures a set of page link IDs that web chat recognizes when a user goes to your page with an ID included as a URL parameter. These IDs trigger different greeting messages to your user allowing you to generate links to web chat that can start specific conversations. For more information, see Creating links to web chat. | |
debug | Boolean |
false | Enables extra console logging. | |
onError | Function |
This callback is called when an error occurs within the web chat. It is not limited to errors that occur when the web chat is loading but 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 |
If you have a use case that requires loading multiple web chats on the same page, give them each a unique namespace to avoid conflicts. Instead of providing your configuration object in window.watsonAssistantChatOptions , you pass the configuration object into window.loadWatsonAssistantChat() and load the web chat when you need it. Using this property also changes your default CSS selector for styling components inside web chat. For more information, see namespaces. |
||
learningOptOut | Boolean |
false | Set to true if you want to add the X-Watson-Learning-Opt-Out header to all traffic to watsonx Assistant. | |
disablePDFViewer | Boolean |
Indicates if you want to disable the internal web chat PDF viewer. If true, web chat presents links to PDFs as actual links that open in the user's web browser by using the browser's native viewer instead of the web chat viewer. It can be useful if the server hosting the PDF documents does not support CORS which is required for using the web chat viewer. | ||
disableWindowTitleChanges | Boolean |
false | Web chat can change the title of the window/document to inform the user about unread messages that were received while web chat was not visible. This property can be used to disable this functionality so web chat does not make any changes to the window title. | |
enableFocusTrap | Boolean |
false | Determines if the web chat activates a focus trap when it is opened. It locks focus inside the web chat and a user is unable to move focus outside until they close the web chat. In addition, a semi-transparent background is placed behind the web 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 | If the web chat needs to put focus on the input field for web chat automatically when the web chat is open when the page loads. It applies when the chat is stored in an open state by session history or if you have openChatByDefault set to true . |
|
servers | Object |
This option configures some of the server settings that control how web chat communicates with its servers such as being able to set up a proxy. For more information, see server configuration. |
Theme configuration
You can customize colors and fonts web chat uses for rendering.
In the watsonx Assistant user interface, configure the theme in three key areas:
- Choose between light or dark mode for web chat.
- Choose if you want to apply the Carbon for AI theme on top of that choice.
If you are using web chat for an internal IBM use case, turn on the Carbon for AI theme. This theme is placed on top of your carbonTheme
choice. It disables your ability to update colors with the updateCSSVariables
instance method and ignores many other styling settings that you can make inside watsonx Assistant.
- You can customize the colors and fonts of web chat in the watsonx Assistant user interface. Choose a
primary
,secondary
, andaction
color. Also, you can apply one of four Carbon themes by using thecarbonTheme
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 web chat configuration.
Warning: since web chat gives you many hooks to amend and change content, and web chat itself is just HTML, CSS and JavaScript. We highly recommend that you do not manipulate content outside of what it allows by default to avoid unintended issues as web chat deploys new releases.
Parameter | Type | Default | Description |
---|---|---|---|
themeConfig.carbonTheme | String |
g10 | You can 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.useAITheme | Boolean |
false | For internal IBM usage to add IBM Carbon for AI branding to the web chat. |
Layout configuration
Web 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 web chat frame is displayed. It includes the border and box-shadow on the outside of the main window. |
layout.hasContentMaxWidth | Boolean |
false | Indicates whether the web chat content is constrained to a max-width for wide web chat layouts. The max-width of the chat content is 627px. If the AI theme is enabled, this option defaults to true . |
Example
For a fullscreen version of the web chat, you can use the following configuration:
<script>
window.watsonAssistantChatOptions = {
integrationID: 'YOUR_INTEGRATION_ID',
region: 'YOUR_REGION',
serviceInstanceID: 'YOUR_SERVICE_INSTANCE_ID',
element: myElementThatIsFullScreen,
themeConfig: {
corners: 'square',
},
layout: {
showFrame: false,
hasContentMaxWidth: true,
},
onLoad: async (instance) => {
await instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>
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 | Whether to hide the UI control that closes the chat window. Use this option along with openChatByDefault if you want the web chat to always be open on your page, or if you provided your own DOM element to contain the web chat. |
headerConfig.showRestartButton | Boolean |
false | Indicates whether or not the restart button displays in the header. This feature cannot be used with showCloseAndRestartButton |
headerConfig.showCloseAndRestartButton | Boolean |
false | Indicates whether or not the close-and-restart button is displayed in the header. It adds an additional "X" button to the header next to the close/minimize button. This button restarts the conversation that a user has with the bot and closes the web chat window. It also ends any conversation with a human agent. If the user re-opens web chat, the bot conversation clears, and a new conversation begins. The user can still see the conversation history with an agent, but they must start a new conversation if they want to chat with a human agent again. This feature cannot be used with showRestartButton . |
Example
<script>
window.watsonAssistantChatOptions = {
integrationID: 'YOUR_INTEGRATION_ID',
region: 'YOUR_REGION',
serviceInstanceID: 'YOUR_SERVICE_INSTANCE_ID',
headerConfig: {
minimizeButtonIconType: 'side-panel-left',
},
onLoad: async (instance) => {
await instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>
Service desk configuration
When web chat configures a service desk integration, this object controls the options that web 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 to use 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 this value is not defined, then there is no timeout. |
serviceDesk.availabilityTimeoutSeconds | Number |
5 | The timeout value in seconds to use 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 web 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 web 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. |
Example
<script>
window.watsonAssistantChatOptions = {
integrationID: 'YOUR_INTEGRATION_ID',
region: 'YOUR_REGION',
serviceInstanceID: 'YOUR_SERVICE_INSTANCE_ID',
serviceDesk: {
skipConnectAgentCard: true,
},
onLoad: async (instance) => {
await instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>
Close panel button config Deprecated
You can modify the web chat minimize button look and behavior to enable custom closing behavior for web chat in a panel-like layout by using a custom element.
When you click the button, it fires a closePanelButton:toggled event for you to hook into and implement your panel closing logic.
It is deprecated. Use headerConfig instead.
Parameter | Type | Default | Description |
---|---|---|---|
closePanelButtonConfig.is_on | Boolean |
false | Indicates whether web chat uses the "close panel" button. It changes the minimize button icon to an icon that indicates closing a panel and prevents web chat from minimizing. |
closePanelButtonConfig.closeIconDirection | String |
Indicates the direction that the button icon faces. Either 'left' or 'right' . The default value is automatically set to 'right' if the page direction is not rtl. If the page direction is rtl, the default value is 'left' . You can still override the default behavior by setting the value. |
Example
<script>
function handler() {
// Your panel closing logic.
}
window.watsonAssistantChatOptions = {
integrationID: 'YOUR_INTEGRATION_ID',
region: 'YOUR_REGION',
serviceInstanceID: 'YOUR_SERVICE_INSTANCE_ID',
closePanelButtonConfig: {
is_on: true,
},
onLoad: async (instance) => {
instance.on({ type: 'closePanelButton:toggled', handler: handler });
await instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>
Server configuration
The main web chat configuration object has a servers
option object that controls how web chat communicates with its server. The different options available in this object are documented below.
Note: These options do not work with the old "loadWatsonAssistantChat.js" form of the web chat embed script. Make sure that your script uses the "WatsonAssistantChatEntry.js" version. You can find it in the embed tab of the web chat configuration settings in watsonx Assistant.
Parameter | Type | Default | Description |
---|---|---|---|
servers.assistantURLPrefix | String |
Web chat uses this prefix when it communicates with watsonx Assistant. It modifies the calls that fetch web chat configuration, session history and sending messages. | |
servers.webChatScriptPrefix | String |
Web chat uses this prefix when it downloads extra JavaScript files that are used by web chat. These are static files that the content delivery network (CDN) hosts. |
Setting up a proxy
You can use the assistantURLPrefix
and webChatScriptPrefix
properties if you need to set up a proxy between your users' browsers and watsonx Assistant. The assistantURLPrefix
controls communication with the assistant and webChatScriptPrefix
controls communication with the CDN where it hosts the web chat JavaScript. These values can be set to the URL of your proxy (and you can add path information as well). If you use a proxy, it is expected that the proxy forwards all requests below the path specified by this prefix to the original URL. The requests are forwarded without modification (including all non-proxy related headers). The content of the requests are considered opaque and can change without notice.
You can use any paths that you want in each prefix and you can use separate proxies for each if you need. However, you either need multiple proxies or a single proxy that can forward requests based on path in order to make sure that requests for the assistant go to the assistant and requests for web chat scripts go to the web chat CDN.
For reference, the default value of assistantURLPrefix
is https://integrations.<region>.assistant.watson.appdomain.cloud
, where <region>
is the same as the region in your web chat embed code. The default value of webChatScriptPrefix
is https://web-chat.global.assistant.watson.appdomain.cloud
.
Example
<script>
window.watsonAssistantChatOptions = {
integrationID: 'YOUR_INTEGRATION_ID',
// Example region is us-east.
region: 'us-east',
serviceInstanceID: 'YOUR_SERVICE_INSTANCE_ID',
servers: {
assistantURLPrefix: 'https://proxy.privatecompany.com/assistant',
webChatScriptPrefix: 'https://proxy.privatecompany.com/webchat',
},
onLoad: async (instance) => {
async instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>
With this example, the proxy at proxy.privatecompany.com
forwards all requests from /assistant/*
to https://integrations.<region>.assistant.watson.appdomain.cloud/*
and all requests from /webchat/*
to https://web-chat.global.assistant.watson.appdomain.cloud/*
.
Creating links to web chat
If you want to create a link to web chat that opens it and starts a conversation from a specific topic, you can use the pageLinkConfig
configuration option. It can be useful, for example, 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 web chat, and begin the conversation with your "update account" conversation.
The way that it works is that you pre-configure a set of link IDs that you can include in your external URLs. When web 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 web 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 web chat responds when it recognizes the ID. |
pageLinkConfig.linkIDs[id].text | String |
This text is what your assistant recieves when it recognizes the ID. |
Example
<script>
window.watsonAssistantChatOptions = {
integrationID: 'YOUR_INTEGRATION_ID',
region: 'YOUR_REGION',
serviceInstanceID: 'YOUR_SERVICE_INSTANCE_ID',
pageLinkConfig: {
linkIDs: {
'u35': {
text: 'I would like to update my account'
},
'r23': {
text: 'I need to reset my password'
}
}
},
onLoad: async (instance) => {
await instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>
Listening for errors
Your web chat configuration can include an onError
option that acts as a callback where web chat calls when errors occur within the web chat. These errors can occur in the initialization phases of the web chat or they can occur later when your user is using the web 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 |
A text description of the error. |
errorCode | Number |
A code associated with the error. The value provided here depends on what error type the system reports. |
otherData | Anything |
Any extra data that can be associated with the error. It can be a stack trace for example. |
Error types
Error type | Description |
---|---|
HYDRATION | It indicates that an error occurred when the web chat is trying to load and it was unable to load data necessary to start. It indicates a problem trying to fetch the welcome information and is often accompanied by one of the other errors. |
IDENTITY_TOKEN | It indicates that an error occurred with the configuration of the identity token. It indicates that web chat requested a new identity token by using the identityTokenExpired event but that no subscriber provided a token. It indicates an error in the host web page and not the web chat. |
INITIAL_CONFIG | This error occurs when the web chat is first being loaded on the page and it was unable to load the initial configuration data. When this error occurs, the launcher is not displayed and the web chat does not load at all. In this case, the errorCode contains the HTTP response code from the request. |
INTEGRATION_ERROR | It indicates that there was some problem with the configuration of the integration. The only condition currently reported is the case where the integration returns a "Connect to agent" response but no service desk was configured that is capable of responding to it. |
MESSAGE_COMMUNICATION | It indicates that there was an error sending a message from the user to the assistant. This error is only fired after all the retry attempts have been made and failed and the web chat has given up. In this case, the errorCode contains the HTTP response code from the request. |
OPEN_CONFIG | When a user opens the web chat, it makes a request to load extra configuration data for the integration. If the request fails, the error is generated. In this case, the errorCode contains the HTTP response code from the request. |