Features and customization
Using the features of web chat to customize its appearance and behavior.
Contents
Overview
Custom/user-defined responses
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. It is important to note that when SASS compiles your code, globals like @font-face
, and @keyframes
are not correctly processed when wrapped in a parent selector. In these cases you must manually pull these declarations out of the #WACContainer.WACContainer
selector.
Do not do this in SASS
#WACContainer.WACContainer {
/* Will NOT compile correctly. */
@font-face {
font-family: myFirstFont;
src: url(sansation_light.woff);
}
/* Will NOT compile correctly. */
@keyframes example {
from {background-color: red;}
to {background-color: yellow;}
}
/* Will compile correctly. */
.myAwesomeClass {
background: hotpink;
color: indigo;
}
}
Do this in SASS
@font-face {
font-family: myFirstFont;
src: url(myFirstFont.woff);
}
@keyframes example {
from {background-color: red;}
to {background-color: yellow;}
}
#WACContainer.WACContainer {
.myAwesomeClass {
background: hotpink;
color: indigo;
}
}
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.