Skip to main contentIBM watsonx Assistant web chat

Getting started

Web chat is meant to be completely extendable to allow you to concentrate on what makes your use case unique, and let web chat worry about universal chat needs.

Contents

Installing the web chat
Using the API

Customizing the view

Service desks

Internationalization

Security, Authentication and Authorization

Installing the web chat

The web chat is a versioned JavaScript library hosted on a CDN. It uses lazy loading to dynamically load components, minimizing unnecessary overhead.

You can install the web chat in two ways:

1. Using the <script> tag:

This method is framework-agnostic and works alongside web components, Angular, Vue, Svelte, and more. The embed code is available in the Embed tab inside watsonx Assistant.

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>

2. Using the react component

Install the assistant-web-chat-react component. This option simplifies the web chat's wiring into your React application.

Using the API

Configuration

When your page initializes the web chat widget, it passes in a configuration object that sets various immutable options. By editing the configuration object, you can control the appearance and behavior of the web chat before your customers see it. The configuration options enable you to specify where the web chat widget appears on your page, choose whether to use the IBM-provided launcher or your own, and more.

For more information, see Configuration.

Instance methods

Each instance of the web chat provides a collection of runtime methods that your website can call any time after the instance is available on your website. You can apply these methods before or after the web chat renders on the screen. You can open or close the web chat widget from a custom control, send messages to your assistant from your own functions, theme the web chat, dynamically update the web chat text strings, and more.

For more information, see Instance methods.

Events

Throughout its life cycle, the web chat fires a variety of events your code can subscribe to. To use the event handler callbacks, do the following steps:

  • Manipulate the message contents before sending, or after receiving.
  • Change how your website renders when the web chat opens or closes.
  • Render your own custom response types inside the web chat widget.

For more information, see Events.

Customizing the view

Layout

By default, the web chat adds an element just before the tag and displays it as a floating widget in the lower right or left corner, based on your page's directional settings. This position is customizable and includes a replaceable launcher button.

Alternatively, you can specify an element for the web chat to render into. The web chat adapts to the container's dimensions and adjusts its layout responsively to suit the rendered size:

  • For tall and narrow elements, such as sidebars, the web chat renders its layout to fit seamlessly.
  • For large, central elements, the web chat expands to fill the space following the best practices for larger formats.

For more information, see the web chat layout configuration.

Homescreen

The web chat displays an optional home screen featuring content presented to users during their initial interaction and accessible later in the conversation. Many use it to give people sample prompts for their assistant.

You can statically configure this home screen in watsonx Assistant, or you can update it in real time by using custom code.

For more information, see instance.updateHomeScreenConfig.

Theming

You can customize colors and fonts of the web chat in the watsonx Assistant user interface. Choose a primary, secondary, and action color. Additionally, 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 the web chat configuration.

Extending the UI with custom code

You can customize how the web chat looks on your website in many ways:

  • Embed your own custom HTML/CSS/Javascript content as part of user_defined responses from your assistant.
  • Create complex views by using a combination of native responses and user_defined responses by using the card response type (and then even put it in a carousel).
  • Write custom content to various areas of the web chat to enable extra content.

For more information, see Custom UI content.

Service desks

The web chat supports fallback to human agents when an assistant cannot help with a topic:

For other service desks, the web chat allows you to extend the web chat with support for various service desks.

Go to GitHub for starter kits for extending with your own service desk. The GitHub repository has various starter kits for commonly used service desks.

Internationalization

Languages

Most of the content that displays in the web chat originates from an assistant and displays the language that the content is written in. However, some content that displays in the web chat is static text that is hard-coded inside of the web chat. This includes items such as the "Type something..." message that appears as the placeholder text in the input field or the "Choose a date" text that appears on a date picker. By default, these texts display in English but you can change the language of the texts. The web chat provides several translations for these texts and you can configure the web chat to use those languages.

Note: This language is independent of the language you set in your assistant.

In addition, the individual texts can change if you want to use different text or if you want to provide your own translations for a language the web chat does not have support for.

The list of languages and their language codes that the web chat provides translations for are:

  • Arabic (ar)
  • Chinese (zh)
  • Chinese/Taiwan (zh-tw)
  • Czech (cs)
  • Dutch (nl)
  • English (en)
  • French (fr)
  • German (de)
  • Italian (it)
  • Japanese (ja)
  • Korean (ko)
  • Portuguese/Brazil (pt-br)
  • Spanish (es)

You can switch the language by calling the updateLocale instance method and by using the appropriate language code.

In addition to switching to the supported languages, you can also provide your own strings to either change the string for any message, or to provide your own language support. For example, when you prompt for the user's name, you might want to replace the default text "Type something..." with "Enter your name".

To change any text string, use the updateLanguagePack instance method. The JSON object specifies the replacement strings.

You can find the strings that the web chat uses in the languages folder. Make sure to access the files for the version of the web chat that you use; you can find that list on the tags page.

These files are in the ICU Message Format JSON representations of all of the languages that watsonx Assistant action skills, dialog skills and the web chat widget support.

Note: The provided JSON object does not need to contain all strings, just the strings you want to update. Your changes merge with the existing language strings.

Locales

In addition to languages, the web chat supports locales with a more specific region code (e.g. en-gb). The region goes beyond the language and controls other things such as the format of dates and times shown by the web chat. For example, date strings in UK English are in the dd/mm/yyyy format, while US English dates are in the mm/dd/yyyy format.

Note: This setting does not affect any strings received from your action, dialog or search skill; it applies only to strings displayed by the web chat itself.

The locales that are supported by the web chat are a superset of the languages that are supported by action and dialog skills. The web chat supports the locales that are provided by the dayjs library.

Bi-directional Support

Some languages are read from left to right (ltr), and others from right to left (rtl). The web chat renders text in the same direction as the page based on the dir attribute on the <html> tag.

Security, Authentication and Authorization

The web chat secures the chat with any external authentication provider. See watsonx Assistant security documentation.