Web chat development overview

If you want to customize the style and appearance of the web chat beyond the options that are available on the Style tab in the web chat settings, you can do so by choosing a different Carbon Design theme.

The supported themes are color themes that are defined by IBM Carbon Design. To set the Carbon theme, use the carbonTheme configuration option.

You can also set individual variables within the theme to customize specific UI elements. For example, the text that is displayed in the chat window uses the fonts IBMPlexSans, Arial, Helvetica, sans-serif. If you want to use a different font, you can specify it by using the updateCSSVariables() instance method.

The home screen greets the customer and optionally shows a list of suggested conversation starters. You can customize the style and content of the home screen:

• To add elements to the home screen, you can define custom HTML using the writeableElements.homeScreenAfterStartersElement theming variable:

  instance.writeableElements.homeScreenAfterStartersElement.innerHTML = 
    '<div class="MyCustomClass">This is my custom element</div>';
  

  Example: For a working example that shows how to add custom elements to the home screen, see Home screen custom elements for watsonx Assistant web chat.

• To change the home screen style, use CSS helper classes.

You can customize the strings that define the various labels and hardcoded phrases displayed by the web chat. To customize strings, use the updateLanguagePack() instance method to replace strings in the current language pack. For more information, see Languages.

By default, the strings displayed by the web chat are in English. To change to a different language, use the updateLanguagePack() instance method to replace the current language pack with one of the available translated language packs. For more information, see Supporting global audiences in web chat.

To better integrate with your website, you might want to replace the built-in launcher icon with a different mechanism for opening the web chat. To hide the default launcher, set the showLauncher configuration option to false. To open the web chat based on some other interaction, use the openWindow instance method.

Tutorial: For a tutorial that shows you how to implement a custom launcher, see Using a custom launcher.

If you want to keep the web chat always open on your page, use the openChatByDefault configuration open to render the page with the chat window open, and the hideCloseButton option to prevent customers from closing it.

Your website design might require that you change where and how the web chat window renders on your website. For example, you might want it to appear in a different position on the page, at a different size, or nested within another element on the page.

To change the size of the web chat window, you can use the updateCSSVariables() instance method to modify the CSS styling.

If you need to change the position of the web chat window, or you need to change the size beyond the limits allowed in the CSS, you can use a custom DOM element to contain the web chat window. To do this, use the element configuration option.

Tutorial: For a tutorial that shows how render the web chat in a custom element, see Tutorial: Customizing the size and position of the web chat.

You can use a WebView with a JavaScript bridge to add the web chat to your mobile application. For more information, see Adding the web chat to your mobile application.

By subscribing to events, your code can intercept messages that are sent and received between the customer and the assistant, and even modify their content.

Subscribe to the pre:receive event if you want to intercept a customer's message before it is sent to the assistant. For example, you might want to remove personally identifiable information from the message text or add context variables to the message payload.

Subscribe to the pre:send event if you want to intercept an incoming response from the assistant before it is shown to the customer. For example, you might want to add formatting, links, or other elements that are specific to the web chat.

Tutorial: For a tutorial showing how to use the pre:receive event to intercept and modify incoming messages, see Tutorial: implementing custom option buttons in the web chat.

If your assistant sends specialized responses using a custom (user_defined) response type, you can implement a custom view to display these responses in the web chat window. To do this, subscribe to the customResponse event, which is fired each time a user_defined response is received. In your event handler method, you can then read the contents of the response and render the output using your own elements.

Tutorial: For a tutorial showing how to render a custom response type as a replacement for the default options response, see Tutorial: implementing custom option buttons in the web chat.

You can use one of the web chat starter kits to integrate with a contact center (service desk) platform other than the ones available in as built-in watsonx Assistant integrations. Fully functional reference implementations are available for several contact center platforms; in addition, you can use a starter kit to develop a custom integration with the platform of your choice.

For more information, see Adding contact center support.

The web chat associates a user ID with each message it sends to the assistant; this user ID is used for user-based billing and other purposes. You can either allow the web chat to generate an anonymous ID for each user, or you can control the user ID yourself.

Depending on whether you have enabled security for the web chat, you can use either the updateUserID instance method or the updateIdentityToken method to specify user identity information.

For more information about how user identity information is specified and how it is used, see Managing user identity information in web chat.

To secure the web chat, you can use JSON Web Token (JWT) to authenticate users and encrypt private data. For more information, see Securing the web chat.

The web chat code hosted by IBM Cloud is regularly updated with improvements and new features. By default, the embed script automatically uses the latest version of the web chat. To avoid unexpected changes that might affect your website, you might want to control which version of the web chat your website uses, giving you an opportunity to test each new version before you deploy in in production., in order to avoid unexpected changes when a new version is released.

For more information about web chat versioning, see Controlling the web chat version.