Configuration

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 the 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 must adjust your code to load window.loadWatsonAssistantChat.

Configuration options object

The options object assigned to watsonAssistantChatOptions supports the following parameters:

Theme configuration

You can customize colors and fonts the web chat uses for rendering.

In the watsonx Assistant user interface, configure the theme in three key areas:

1. Choose between light or dark mode for the web chat.
2. Choose if you want to apply the Carbon for AI theme on top of that choice.

If you are using the 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.

1. You can customize the colors and fonts of the web chat in the watsonx Assistant user interface. Choose a primary, secondary, and action color. Also, you can apply one of four Carbon themes by using the carbonTheme 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: The web chat provides many hooks to amend and change content, and the web chat uses HTML, CSS, and JavaScript for its build. Avoid manipulating content outside the default configuration to prevent unintended issues when the web chat deploys new releases.

Layout configuration

The web chat provides a layout configuration that allows you to modify the widget frame and content.

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.

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 the web chat configures a service desk integration, this object controls the options that the 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.

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

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

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. You can set these values to the URL of your proxy (and you can add path information as well). If you use a proxy, 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 the 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 the web chat

If you want to create a link to the web chat that opens it and starts a conversation from a specific topic, you can use the pageLinkConfig configuration option. Use this configuration 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 the web chat, and begin the conversation with your "update account" conversation.

Pre-configure a set of link IDs that you can include in your external URLs. When the 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 the 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.

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 the 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:

Error types