Skip to main contentIBM watsonx Assistant web chat

Features and customization

Using the features of web chat to customize its appearance and behavior.

Contents

Overview
Custom/user-defined responses

Cards

Languages

Launcher

Theming

Rich text responses

Writeable elements

Custom Panel

CSS helper classes

Using namespaces

Overview

Warning: since web chat gives you plenty of hooks to amend and change content, and web chat itself is just HTML, CSS and JavaScript, it can be tempting to manipulate content outside of what it allows by default. We highly recommend you do not do that to avoid unintended issues as web chat deploys new releases. Also, it is important to note that if you are heavily using !important in the CSS on your site you will likely run into problems correctly rendering web chat.

There are a variety of ways you can extend the look of web chat to match the needs of your brand and customer workflows.

Custom/user-defined responses

In addition to rendering HTML content in responses, web chat can render content from your own HTML, CSS, or JavaScript on your page, using a user_defined response type. This allows for a much better authoring experience for development, and it enables you to make changes to responses without editing your dialog skill. These user_defined responses also inherit styling and helper CSS classes from web chat, just like text responses with HTML. You can even make use of portals in advanced frameworks like React to render content from your main application.

To learn more about the user_defined response type, see the tutorial or the React based carousel tutorial.

Any CSS you define, either for HTML in a text response or for a user_defined response, should be prefixed by #WACContainer.WACContainer. Web chat uses an aggressive CSS reset in order to allow embedding on your page instead of in an iframe. In order to override our resets, you need the CSS specificity provided by using the prefix.

Example
#WACContainer.WACContainer .myAwesomeClass {
  background: hotpink;
  color: indigo;
}

A common way to wrap CSS in #WACContainer.WACContainer is by using SASS or similar CSS templating engines.

Cards

Cards allow you to compose complex responses in a card using the IBM watsonx Assistant JSON Editor. For a reference of available response types to use in a card, see the response types documention. To see examples and experiement with making your own cards, use the Response editor.

Languages

Most of the content displayed inside of web chat is content that comes from IBM watsonx Assistant and is displayed using whatever language that content is written in. However, some content displayed in web chat is static text that is hard-coded inside of web chat. This includes things like the "Type something..." message that appears as the placeholder text in the input field, the "Choose a date" text that appears on a date picker or the word "Suggestions" that appears in the suggestions menu when web chat provides suggested messages to the user. By default, these texts are displayed in English but the language of those texts can be changed. Web chat provides a number of out-of-the-box translations for these texts and web chat can be configured to use those languages. Note, that this language is independent of the language you may have set in your assistant. In addition, the individual texts may be changed 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 out-of-the-box 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 web chat to use one of these languages by calling the updateLocale instance method and passing it the given language code.

In addition to switching to any of the supported languages, you can also provide your own strings to either change the string for any given 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 out-of-the-box 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 IBM 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 the languages listed above, 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 supported by web chat are a superset of the languages supported by action and dialog skills. Web chat supports the locales that are provided by the dayjs library.

Launcher

The web chat launcher welcomes and engages customers so they know where to find help if they need it. For more information about the default launcher behavior see, launcher appearance and behavior.

Theming

You can customize colors and fonts used in rendering of web chat. First, in the IBM watsonx Assistant user interface, you can select a primary, secondary and action color that will change colors based on the instructions inside IBM watsonx Assistant. Second, as part of your initial web chat configuration, you can choose one of four themes using the carbonTheme property: white, gray 10, gray 90 or gray 100. The white and gray 10 themes are light, and the gray 90 and gray 100 themes use dark grays and blacks. Finally, you also have fine-grained control over individual properties by making use of the updateCSSVariables instance method.

Using Carbon Components

In addition to using your own custom HTML, CSS, and JavaScript, you can also use the IBM Carbon library inside web chat without importing any additional CSS. All theming choices you have made inside of IBM watsonx Assistant and through the updateCSSVariables instance method are automatically applied to your components. This opens up many components like tables, file uploads, accordions, buttons and forms to use in your user_defined responses at minimal effort. This support extends to the Carbon Charts data visualization extension. Currently, web chat does not support the Modal Carbon component. Some components like DataTable or visualizations like a tree chart are built for a wider view that the default web chat and are not recommended for use cases that need mobile device support.

Web chat uses version 10.45.x of the carbon-components library and version 0.58.2 of the @carbon/charts library.

Rich text responses

Web chat also supports basic styling inside text responses to match the theme of your web chat, both with a limited set of Markdown or HTML content returned from the Assistant. It is highly recommended you make use of Markdown instead of HTML in your text responses. This more easily allows adding channels that do not support HTML (such as Facebook, Slack, or Whatsapp), without having to rewrite your content.

Markdown

If you are authoring your dialog or actions to support other channels (such as Facebook, Whatsapp or Slack) in addition to web chat, HTML might not be supported for all channels. As an alternative, web chat supports a limited subset of Markdown. For italics, bold, and URLs, you can use Markdown tagging that the IBM-provided integrations parse into formats that the corresponding channels understand. For more information, see the IBM watsonx Assistant documentation.

These styles match those of the rest of web chat and are the easiest way to send styled content in a text response. In fact, the built-in text response editor for actions can insert Markdown formatting for you.

HTML content

If you include HTML (including style and script tags) in your text response from your dialog skill, web chat will render those elements as provided. Web chat is configured so that all elements (such as button or table) are automatically styled to match the web chat content. A better approach, however, is to use a user_defined response instead of adding HTML directly to your responses. This makes it far easier for you to later add support for channels that do not support HTML.

If you need to override the styles in your text response, they should be wrapped with #WACContainer.WACContainer .ibm-web-chat--default-styles to override web chat styles. The class ibm-web-chat--default-styles provides a reasonable default for HTML elements, enabling nontechnical users to match web chat without worrying about styling. Any complicated rendering of HTML/CSS should be done in a user_defined response.

Writeable elements

Web chat provides access to a variety of elements located strategically around web chat. You can directly write to these elements or, if you are using advanced frameworks like React or Angular, write to them as portals from your own application.

Learn more about writeable elements

Custom Panel

Web chat allows you to open an overlay panel with custom content at any time. Panels are effective for use cases ranging from pre-chat content forms, post-chat feedback forms, or multistep processes. You can open the panel at any time, whether from an event, a user_defined response, or even an action a user takes on your website.

Learn more about the custom panel

CSS helper classes

Web chat also provides helper CSS classes that enable you to build more complex non-native layouts that match native web chat layouts. These classnames are available to use in user_defined responses and writeable elements. These classes act as a superset to the classes available in the IBM Carbon library you can also use.

Class name Description
ibm-web-chat--default-styles Automatically applied to text responses and resets base HTML elements (such as a, button, and p) to defaults that match web chat. You can also use this class in a user_defined response or writeable element, but note that the reset is aggressive.
ibm-web-chat--card Adds styling for a card like those used in image responses, search results, and other native response types in your own custom response type. This class inherits from the Carbon bx--tile class.
ibm-web-chat--card-home-screen Adds styling for a card like those used in the home screen, including correct padding and spacing. This class inherits from the Carbon bx--tile class.
ibm-web-chat--card-home-screen--transparent Adds styling for a transparent card used in the home screen, including correct padding and spacing.
ibm-web-chat--card-home-screen--accent Adds styling for a card the color of the accent color used in your home screen, including correct padding and spacing.
ibm-web-chat--card-home-screen__title-outer Adds styling for a title for a card, based on either .ibm-web-chat--card-home-screen or .ibm-web-chat--card-home-screen--transparent.
ibm-web-chat--card-home-screen__title-inner Adds styling for a title for a card, based on either .ibm-web-chat--card-home-screen or .ibm-web-chat--card-home-screen--accent.

Examples

<div class="ibm-web-chat--card-home-screen__title-outer"></div>
<div class="ibm-web-chat--card-home-screen"></div>

<div class="ibm-web-chat--card-home-screen">
  <div class="ibm-web-chat--card-home-screen__title--inner"></div>
</div>

Using namespaces

If you are using the namespace configuration option, you will need to run the following command in your browser console to get the correct unique hashed CSS safe id for your namespaced web chat.

document.querySelector('[data-namespace="THE NAMESPACE YOU CHOSE"]').getAttribute('id');

This should output an id that looks something like WACContainer--ns-308302247. You would then use #WACContainer--ns-308302247.WACContainer as your CSS selector instead of #WACContainer.WACContainer for all styling you do with web chat.