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 web chat
Using the API

Customizing the view

Service desks

Internationalization

Security, Authentication and Authorization

Installing web chat

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 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 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 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 web chat provides a collection of runtime methods that your website can call any time after the instance is available on your website. These methods can be applied before or after the web chat is rendered 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 web chat text strings, and more.

For more information, see Instance methods.

Events

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

  • Manipulate the contents of messages before they are sent or after they are received.
  • Change how your website is rendered 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, 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 web chat to render into. 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, web chat renders its layout to fit seamlessly.
  • For large, central elements, web chat expands to fill the space following the best practices for larger formats.

For more information, see web chat layout configuration.

Homescreen

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

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

For other service desks, 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 is displayed in web chat originates from an assistant and displays the language that the content is written in. However, some content that is displayed in web chat is static text that is hard-coded inside of 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 are displayed in English but the language of those texts can be changed. Web chat provides several translations for these texts and web chat can be configured 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 web chat does not have support for.

The list of languages and their language codes that 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 are prompting 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. Replacement strings are specified in a JSON object.

You can find the strings that web chat uses in the languages folder. Make sure to access the files for the version of web chat that you are using; 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 are supported by watsonx Assistant action skills, dialog skills and the web chat widget.

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

Locales

In addition to languages, 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 web chat. For example, date strings in UK English are in dd/mm/yyyy format, while US English dates are in 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 web chat itself.

The locales that are supported by web chat are a superset of the languages that are supported by action and dialog skills. 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

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