Theming & custom content
You can control how custom content looks and behaves, and make sure it matches core web chat functionality.
Overview
There are a variety of ways you can extend the look of the web chat to match the needs of your brand and customer workflows.
Table of contents
Theming
You can customize colors and fonts used in rendering of the web chat. First, in the Watson Assistant user interface, you can select a primary, secondary and action color that will change colors based on the instructions inside Watson 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.
User-defined responses
In addition to rendering HTML content in responses, the 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 the 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 tutorial.
Any CSS you define, either for HTML in a text response or for a user_defined
response, should be prefixed by #WACContainer.WACContainer
. The 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 is 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;
}
}
Using Carbon Components
In addition to using your own custom HTML, CSS, and JavaScript, you can also use the IBM Carbon library inside the web chat without importing any additional CSS. All theming choices you have made inside of Watson 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. Currently, the web chat does not support the Modal
Carbon component.
The web chat uses version 10.43.x
of the carbon-components library.
Text responses
The 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 the web chat, HTML might not be supported for all channels. As an alternative, the 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 Watson Assistant documentation.
These styles match those of the rest of the 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, the web chat will render those elements as provided. The 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 the web chat without worrying about styling. Any complicated rendering of HTML/CSS should be done in a user_defined
response.
Writeable elements
The web chat provides access to a variety of elements located strategically around the 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.
CSS helper classes
The 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 the 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 .Example
|
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 .Example
|