Skip to main contentWatson Assistant web chat

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/loadWatsonAssistantChat.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 watsonAssistantChatOptionssupports the following parameters.

ParameterTypeRequiredDefaultDescription
integrationIDStringRequiredThe integration ID of your web chat integration. This is exposed as a UUID (for example, 1d7e34d5-3952-4b86-90eb-7c7232b9b540).
regionStringRequiredWhich data center your integration was created in (for example, us-south).
serviceInstanceIDStringRequiredThe service instance ID of the assistant hosting your web chat integration. This is exposed as a UUID (for example, 6435434b-b3e1-4f70-8eff-7149d43d938b).
onLoadFunctionRequiredThe 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.
subscriptionIDStringThe 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.
carbonThemeStringg10You 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.
clientVersionStringBy 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
cspNonceStringIf 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.
debugBooleanfalseAutomatically adds a listener that outputs a console message for each event and sends other logging info to console.log.
directionStringSome 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.
disableCustomElementMobileEnhancementsBooleanfalseThis 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 BetaObjectAccepts 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.
elementElementThe 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.
enableFocusTrapBooleanfalseDetermines 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.
hideCloseButtonBooleanfalseWhether 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.
identityTokenJWT tokenIf 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
learningOptOutBooleanfalseSetting this to true will add the X-Watson-Learning-Opt-Out header to all traffic to Watson Assistant.
onErrorFunctionThis 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.
openChatByDefaultBooleanfalseWhether 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.
shouldTakeFocusIfOpensAutomaticallyBooleantrueIf 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.
showLauncherBooleantrueWhether 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.

PropertyTypeDescription
errorTypeStringThe type of error being reported.
messageStringA text description of the error.
errorCodeNumberA code associated with the error. The value provided here depends on what error type is being reported.
otherDataAnythingAny extra data that may be associated with the error. This may be a stack trace for example.
Error types
Error typeDescription
IDENTITY_TOKENThis 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_CONFIGThis 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_ERRORThis 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_COMMUNICATIONThis 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_CONFIGWhen 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.
RENDERThis 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.