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/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.

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. Web chat 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 web chat 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
ObjectAccepts 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.
pageLinkConfigObjecttrueThis 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.
serversObjecttrueThis option lets you configure some of the server settings that control how web chat communicates with its servers such as being able to set up a proxy. See server configuration for more details.
serviceDeskObjectThis is a configuration object used for controlling the behavior of service desk integrations. See Service desk options for more information.
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 have openChatByDefault set to true.
showCloseAndRestartButtonBooleanfalseIndicates whether or not the close-and-restart button should be displayed in the header. This will add an additional "X" button to the header next to the close/minimize button. This button will restart the conversation a user is having with the bot and close the web chat window. It will also end any conversation with a human agent that the user may be engaged in. If the user re-opens web chat, the bot conversation will be cleared and a new conversation begun. The user will still be able to see the conversation history with an agent but they will have to start a new conversation if this wish to chat with a human agent again. This feature is currently only available with English text.
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
HYDRATIONThis 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_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.

Server configuration

The main web chat configuration object has a servers option object that let's you control some of how web chat communicates with its server. The different options available in this object are documented below.

ParameterTypeDefaultDescription
assistantURLPrefixStringThis is the prefix that is used by web chat when communication with Watson Assistant. This will modify the calls that fetch web chat configuration, session history and sending messages.

Setting up a proxy

The assistantURLPrefix property can be used if you need to set up a proxy between your users' browsers and Watson Assistant. This value 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 will forward all requests below the path specified by this prefix to the original URL. The requests should be forwarded without modification (including all non-proxy related headers). The content of the requests should be considered opaque and may change without notice.

For reference, the default value of this property is https://integrations.<region>.assistant.watson.appdomain.cloud, where <region> is the same as the region in your web chat embed code.

Example

<script>
  window.watsonAssistantChatOptions = {
    integrationID: "YOUR_INTEGRATION_ID",
    // Example region is us-east.
    region: "us-east",
    serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
    servers: {
      // Since the example region is us-east we need to use that same region in the url.
      assistantURLPrefix: 'https://integrations.us-east.assistant.watson.appdomain.cloud',
    },
    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>

Service desk options

When web chat has a service desk integration configured, this object controls the options that web chat provides for how it interacts with the integration. This object can be added to the top level configuration option under the serviceDesk property.

ParameterTypeDefaultDescription
availabilityTimeoutSecondsNumber5The timeout value in seconds to use when determining agent availability. When a "Connect to agent" response is received, the system will ask the service desk if any agents are available. If no response is received within the timeout window, the system will return "false" to indicate no agents are available.
skipConnectAgentCardBooleanfalseIndicates if web chat should auto-connect to an agent whenever it receives a "Connect to agent" response and agents are available. This essentially mimics the user clicking the "Request agent" button on the card. The card is still displayed to the user.

Example

<script>
  window.watsonAssistantChatOptions = {
    integrationID: "YOUR_INTEGRATION_ID",
    region: "YOUR_REGION",
    serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
    serviceDesk: {
      skipConnectAgentCard: true,
    }
    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>