Configuration
Tailor web chat to your needs by initializing it with your own custom options.
Overview
When you create a web chat integration, the Watson Assistant UI gives you a small embed code to add to your website, as in this example:
Example
<script>
window.watsonAssistantChatOptions = {
// A UUID like '1d7e34d5-3952-4b86-90eb-7c7232b9b540' included in the embed code provided in Watson 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 Watson Assistant.
serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
// The callback function that is called after the widget instance has been created.
onLoad: function(instance) {
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>
The web chat configuration options are defined by the parameters of watsonAssistantChatOptions
. By default, the embed code provided by Watson Assistant configures only the integrationID
, serviceInstanceID
, and the region
parameters (premium plans also include subscriptionID
). These options also include a onLoad
callback that will be called when the web chat code has been loaded and a new instance has been created. You will need to call render
on that instance to actually display the widget.
You can modify watsonAssistantChatOptions
with additional parameters that control immutable behavior of your web chat instance.
Configuration options object
The options
object assigned to watsonAssistantChatOptions
supports the following parameters.
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
integrationID | String | Required | The integration ID of your web chat integration. This is exposed as a UUID (for example, 1d7e34d5-3952-4b86-90eb-7c7232b9b540 ). | |
region | String | Required | Which data center your integration was created in (for example, us-south ). | |
serviceInstanceID | String | Required | The service instance ID of the assistant hosting your web chat integration. This is exposed as a UUID (for example, 6435434b-b3e1-4f70-8eff-7149d43d938b ). | |
onLoad | Function | Required | The callback that is called when the web chat instance has been loaded and created. You will need to provide a function here that calls render on the provided instance to actually display the widget. | |
subscriptionID | String | The ID of your subscription. For Premium instances, this option is required and is included in the code snippet provided when you create the web chat integration. If you are not using a Premium instance, this ID is absent. | ||
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. Visit instance.updateCSSVariables() to learn more. | |
clientVersion | String | By default, web chat will load the latest version. You can also specify a specific major, minor or patch version. Visit current web chat versions and changelog | ||
cspNonce | String | If your site has a Content-Security-Policy enabled that only permits elements with a given nonce defined, you can provide that value here and the widget will apply it to the script and style elements that are generated by the widget. | ||
debug | Boolean | false | Automatically adds a listener that outputs a console message for each event and sends other logging info to console.log . | |
direction | String | Some languages are meant to be read from left to right (ltr ), and others from right to left (rtl ). This setting indicates the direction the web chat should render by accepting ltr or rtl as values. By default, the web chat will render in the same direction as the page it is on based on the dir attribute on the <html> tag. Most users should use the default. | ||
disableCustomElementMobileEnhancements | Boolean | false | This value indicates whether or not to disable the mobile enhancements when using element to specify a custom element. The widget provides some functionality to improve the behavior of the widget when it is displayed in a full screen mode on a mobile device. This include resizing the widget when the keyboard is opened and accounting for changes in the zoom level of the view. If you are using a custom element, this functionality may interfere with how your element is rendered or laid out. To disable them, use this flag. If you are not using a custom element, this flag has no effect. | |
disclaimer Beta | Object | 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 are able to interact with your assistant. disclaimerHTML provides the disclaimer text (or full html) that must be accepted. Wether or not the user had accepted the disclaimer is stored in browser memory until the browser is closed. | ||
element | Element | The containing DOM element where the web chat widget should be 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 might want to also provide your own launching mechanism and set showLauncher to false . | ||
enableFocusTrap | Boolean | false | Determines if the web chat should activate a focus trap when it is opened. This will lock focus inside the web chat and a user will be unable to move focus outside until the web chat is closed. In addition, a semi-transparent background will be placed behind the web chat that will prevent the user from interacting with other elements on the page. This property will have no effect if hideCloseButton is also being used. | |
hideCloseButton | 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 always to be open on your page, or if you have provided your own DOM element to contain the web chat. | |
identityToken | JWT token | If you have security features enabled, this method takes a JWT used to authenticate and authorize requests from web chat to Watson Assistant. For billing purposes this 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.Read more | ||
launcherBeta Beta | Boolean | Introducing the web chat interactive launcher (beta): designed to better introduce itself to your customers and help them get started. Use this flag to opt into the Beta program and get the latest version of this feature. By default, the flag is set to false and the default launcher is shown. Note: If enabled the Interactive Launcher is only shown to desktop users in order to save space for mobile users. | ||
launcherBetaGreeting Beta | String | If you opt into the web chat interactive launcher (beta) with the flag above you can use this setting to change the greeting text that's shown on the launcher. If no string is provided the homescreen greeting message is used. If there is no homescreen configuration then this default string is used "If you need anything, we're here to help." | ||
learningOptOut | Boolean | false | Setting this to true will add the X-Watson-Learning-Opt-Out header to all traffic to Watson Assistant. | |
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. See the Listening for errors section for more details. | ||
openChatByDefault | Boolean | false | Whether to render the chat window initially in an open state when your page loads. By default, the chat window is initially rendered in a closed state. | |
shouldTakeFocusIfOpensAutomatically | Boolean | true | If the web chat should put focus on the input field for web chat automatically when the web chat is open when the page loads. This applies when the chat is stored in an open state by session history or if you haveopenChatByDefault set to true . | |
pageLinkConfig | Object | true | This option lets you pre-configure a set of page link IDs that will be recognized by web chat when a user visits your page with an ID included as a URL parameter. These IDs will 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. | |
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. |
Listening for errors
Your web chat configuration can include an onError
option that will act as a callback that web chat will call when errors occur within the web chat. These errors may occur in the initialization phases of the web chat or they may occur later when your user is using the web chat. Below is the details of what data is passed 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 being reported. |
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 is being reported. |
otherData | Anything | Any extra data that may be associated with the error. This may be a stack trace for example. |
Error types
Error type | Description |
---|---|
HYDRATION | This indicates that an error has occurred when the web chat is trying to load and it was unable to load data necessary to start. This likely indicates a problem trying to fetch the welcome information and will often be accompanied by one of the other errors. |
IDENTITY_TOKEN | This indicates that an error has occurred with the configuration of the identity token. It indicates that web chat requested a new identity token using the identityTokenExpired event but that no subscriber provided a token. This generally 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 will not be displayed and the web chat will not load at all. In this case the errorCode will contain the HTTP response code from the request. |
INTEGRATION_ERROR | This indicates that there was some problem with the configuration of the integration. The only condition currently reported is the case where the integration as returned a "Connect to agent" response but no service desk was configured that is capable of responding to it. |
MESSAGE_COMMUNICATION | This indicates that there was an error sending a message from the end 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 will contain the HTTP response code from the request. |
OPEN_CONFIG | When the web chat is opened, it will make a request to load additional configuration data for the integration. If that request fails, this error will be generated. In this case the errorCode will contain the HTTP response code from the request. |
RENDER | This indicates that some error occurred within the web chat itself while attempting to render. In this case the otherData will contain the stack trace and other details about the error. |
Creating links to web chat
If you want to create a link to web chat that will open it and start a conversation from a specific topic, you can use the pageLinkConfig
configuration option. This 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". When clicked, this link will take the customer to your website, open web chat, and begin the conversation with your "update account" conversation.
The way this works is that you will pre-configure a set of link IDs that you can include in your external URLs. When web chat recognizes one of these IDs, it will open automatically and send a message to your assistant using the text that you've configured for that ID. Your skill will need to recognize this text and start the conversation appropriately. This text will not be visible to the end user.
Configuration
To use a pre-configured ID, add it to any link to your website that uses web chat using the URL parameter wa_lid
.
To define the IDs, use the pageLinkConfig
embed script configuration property which has the structure below. You can use any text 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 may look something like https://mywebsite.com/accounts?wa_lid=u35
. Note that 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 |
---|---|---|
linkIDs | Object | This object defines all the recognized link IDs. |
linkIDs[id] | Object | This value is an object that represents how web chat should respond when it recognizes the given ID. |
linkIDs[id].text | String | This is the text that will be sent to your assistant when the given ID is recognized. |
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: function(instance) {
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>