Skip to main contentWatson Assistant web chat

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 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. 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 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;
  }
}

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

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 multi-step 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 web site.

Learn more about the custom panel

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 nameDescription
ibm-web-chat--default-stylesAutomatically 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--cardAdds 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-screenAdds 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--transparentAdds styling for a transparent card used in the home screen, including correct padding and spacing.
ibm-web-chat--card-home-screen--accentAdds 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-outerAdds 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

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

ibm-web-chat--card-home-screen__title-innerAdds 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

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