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 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. | ||
clientVersion | string | The semantic version of web chat to use. If not set, the latest version will be used. You can also, optionally, pass in the string latest to force using the latest version. When passing in a semantic version, this string can an exact version like 2.0.0 . You can also automatically allow minor or patch versions by not setting them in the string. For instance if you set the version to 2.0 you will be given the latest 2.0.x version. If you set the version to 2 you will be given the latest 2.x.x version. If no matching version is found, an error will be logged and the latest version will be used. Visit web chat versions and changelog | ||
learningOptOut | Boolean | false | Setting this to true will add the X-Watson-Learning-Opt-Out header to all traffic to Watson Assistant. | |
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 | ||
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. | |
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. | ||
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 . | ||
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. | |
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. | |
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. | |
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. | |
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. | ||
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. |