Skip to main contentIBM watsonx Assistant web chat

Custom UI content

Tailor the chat appearance and behavior to your needs.

Contents

Overview
Customizing responses from the assistant

Customizing the web chat container

Using namespaces

Overview

Warning: web chat provides many hooks to amend and change content, and web chat is built with HTML, CSS, and JavaScript. Avoid manipulating content outside the default configuration to prevent unintended issues when web chat deploys new releases.

You can extend the look of web chat to match the needs of your brand and customer workflows in many ways. Learn how to inject custom code into the web chat to meet your users’ needs better.

For more information, see layout, theming, customization of the header, launcher, or the homescreen for customizations that don't require custom code.

For a list of standard response types, see response types reference.

Customizing responses from the assistant

Rich text responses

web chat also supports basic styling inside text responses to match the theme of your web chat, both with Markdown or HTML content returned from the Assistant. Using Markdown instead of HTML in your text responses is recommended. It allows adding channels that do not support HTML (such as Facebook, Slack, or WhatsApp) without having to rewrite your content.

Markdown

When you design your dialog or actions to support multiple channels, such as Facebook, WhatsApp, confirm compatibility with or Slack, not all platforms support HTML. Make your content compatible with the capabilities of each channel. As an alternative, web chat supports 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 watsonx Assistant documentation.

These styles match the rest of web chat and are the easiest way to send styled content in a text response. 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 assistant, web chat renders those elements as provided. web chat is configured so that common elements (such as button or table) are automatically styled to match the web chat content. A better approach is to use a user_defined response instead of adding HTML directly to your responses to make adding support for channels that do not support HTML easier.

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 by using a user_defined response type. It allows for a better authoring experience for development and enables you to change responses without editing your assistant. You can even use portals in advanced frameworks like React to render content from your main application.

Like text responses with HTML, these ’user-defined’ responses inherit styling and helper CSS classes from web chat.

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

You must prefix any CSS for HTML in a text response or a user_defined response with #WACContainer.WACContainer
web chat uses an aggressive CSS reset to allow embedding on your page instead of in an iframe. You need the CSS specificity that is provided by using the prefix to override the resets. Refer to the following example.

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.

Alternatively, this area is where web components or rendering a React component into a ShadowRoot shine. The CSS variables that are used by the web chat and Carbon pass through ShadowRoot’s scope, maintaining theming without complicated CSS selectors and CSS wrapping.

Using Carbon Components

In addition to using your custom HTML, CSS, and JavaScript, you can also use the IBM Carbon library inside web chat without importing any additional CSS. All theming choices that you make inside watsonx Assistant and through the updateCSSVariables instance method are automatically applied to your components. With minimal effort, it opens up many components for your user_defined responses.

Cards

Cards provide a way to compose complex responses in a card by using the watsonx Assistant JSON Editor. For a reference of available response types to use in a card, see the response types documentation. To see examples and experiment with making your own cards, use the Response editor.

Customizing the web chat container

Writeable elements

web chat strategically provides access to various elements around web chat. You can directly write to these elements or write to them as portals from your application if you use advanced frameworks like React, Angular, Vue, or a web component.

For more information, see Learn more about writeable elements

Custom Panel

web chat opens an overlay panel with custom content anytime. Panels are effective for use cases that range 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.

For more information, see Learn more about the custom panel

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.

Using namespaces

Most users do not need to use the namespace configuration option, but it is needed if you are using multiple instances of web chat on the same page.

If you use the namespace configuration option, you must 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 outputs an id that looks like WACContainer--ns-308302247, then use #WACContainer--ns-308302247.WACContainer as your CSS selector instead of #WACContainer.WACContainer for all styling you do with web chat.

Usually, you need to use a namespace; you can also use a custom element. Another option is to give your container an id and create a CSS selector with equal or greater specificity, like #MyContainer.myContainer.myContainer .WACContainer.

Finally, web components, rendering your React component into a ShadowRoot, and importing styling inline can eliminate concerns. The CSS variables that are used by web chat and Carbon pass through the ShadowRoot scope, maintaining theming without requiring complex CSS selectors.