Getting started

Overview

The AI chat is a rich and extendable chat component that IBM products use to interact with AI. It is the base of what watsonx Assistant and watsonx Orchestrate use and is compatible with watsonx.ai.

This project enables the Carbon and watsonx teams to focus on core chat behaviors, allowing other teams to enhance their product's unique extensibility.

Accessing the Github Repo (IBM Only)

The repository for this work is located at https://github.com/carbon-design-system/carbon-ai-chat. This repository includes code examples and language string translations in addition to source code and issues boards.

You need to follow the following steps for access.

1. Reach out to IBM Slack at #carbon-ai-chat for BlueGroup access to the internal repository.
2. Once you received confirmation of access with the team, onboard your public GitHub account to IBM's Github Enterprise Cloud (GHEC) by using the pinned instructions in the Slack channel.
3. See https://github.com/orgs/carbon-design-system/sso to initiate SSO login to the Github Enterprise Cloud
4. See https://github.com/carbon-design-system/carbon-ai-chat to validate access.

Sometimes the first time the SSO session doesn't correctly get updated with the new permissions until you shutdown your browser completely and log back in.

Installing the AI chat

You can install the AI chat into your application in multiple ways. Internally, the AI chat uses dynamic imports to only load the pieces of the AI chat that you need.

Using as a React component

The React component allows you to use the AI chat in your React application. It offers helpful facades and helpers to use the core Chat API in a more friendly way for a React developer.

Currently, this component does not support SSR, so if you are using Next.js or similar frameworks, make sure you render this component in client only modes.

Basic example

You can render this component anywhere in your application and provide the AI chat configuration options object as a prop.

import React from 'react';
import { ChatContainer } from '@carbon/ai-chat';

const chatOptions = {
  // Your configuration object.
};

function App() {
  return <ChatContainer config={chatOptions} />;
}

For more information, see the React component documentation.

Using as a web component

The web component allows you to use the AI chat in your application. It offers helpful facades and helpers to use the core Chat API in a more friendly way for a web component developer.

Basic example

You can render this component anywhere in your application and provide the AI chat configuration options object as a prop.

import '@carbon/ai-chat/dist/es/cds-aichat-container.js';

import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';

const config = {
  // Your configuration object.
}

@customElement('my-app')
export class MyApp extends LitElement {
  render() {
    return html`<cds-aichat-container .config={config} />`;
  }
}

For more information, see the web component documentation.

Using the API

Configuration

When your page initializes the AI chat widget, it passes in a configuration object that sets various immutable options. By editing the configuration object, you can control the appearance and behavior of the AI chat before your customers see it. The configuration options enable you to specify where the AI chat widget appears on your page, choose whether to use the IBM-provided launcher or your own, and more.

For more information, see Configuration.

Instance methods

Each instance of the AI chat provides a collection of runtime methods that your website can call any time after the instance is available on your website. You can apply these methods before or after the AI chat renders on the screen. You can open or close the AI chat widget from a custom control, send messages to your assistant from your own functions, theme the AI chat, dynamically update the AI chat text strings, and more.

For more information, see Instance methods.

Events

Throughout its life cycle, the AI chat fires a variety of events your code can subscribe to. To use the event handler callbacks, do the following steps:

• Manipulate the message contents before sending, or after receiving.
• Change how your website renders when the AI chat opens or closes.
• Render your own custom response types inside the AI chat widget.

For more information, see Events.

Connecting to your server

The AI chat can send messages and retrieve conversations from your server. It supports both streamed and non-streamed responses.

For more information, see the connecting to your server documentation.

TypeScript reference

The AI chat has the following TypeScript references:

• configuration
• instance methods
• events
• connecting to your server

For more information, see the TypeScript documentation.

Customizing the view

Layout

By default, the AI chat adds an element just before the tag and displays it as a floating widget in the lower right or left corner, based on your page's directional settings. This position is customizable and includes a replaceable launcher button.

Alternatively, you can specify an element for the AI chat to render into. The AI chat adapts to the container's dimensions and adjusts its layout responsively to suit the rendered size:

• For tall and narrow elements, such as sidebars, the AI chat renders its layout to fit seamlessly.
• For large, central elements, the AI chat expands to fill the space following the best practices for larger formats.

For more information, see the AI chat layout configuration.

Homescreen

The AI chat displays an optional home screen featuring content presented to users during their initial interaction and accessible later in the conversation. Many use it to give people sample prompts for their assistant.

For more information, see instance.updateHomeScreenConfig.

Theming

You can customize the Carbon theme of the AI chat. Choose one of four Carbon themes by using the carbonTheme property:

• White
• Gray 10
• Gray 90
• Gray 100

The light themes include White and Gray 10, while Gray 90 and Gray 100 provide dark grays and blacks. You also have fine-grained control over individual properties with the updateCSSVariables instance method.

For more information, see the AI chat configuration.

Extending the UI with custom code

You can customize how the AI chat looks on your website in many ways:

• Embed your own custom HTML/CSS/Javascript content as part of user_defined responses from your assistant.
• Create complex views by using a combination of native responses and user_defined responses by using the card response type (and then even put it in a carousel).
• Write custom content to various areas of the AI chat to enable extra content.

For more information, see Custom UI content.

Service desks

The AI chat supports fallback to human agents when an assistant cannot help with a topic:

• Genesys web messenger
• Nice CXone out of the box.

For other service desks, AI chat allows you to extend the AI chat with support for various service desks.

Go to GitHub for starter kits for extending with your own service desk. The GitHub repository has various starter kits for commonly used service desks.

Accessibility

IBM strives to provide products with usable access for everyone, regardless of age or ability.

The AI chat integration complies with the Web Content Accessibility 2.1 Level AA standard.

Internationalization

Languages

Most of the content that displays in the AI chat originates from an assistant and displays the language that the content is written in. However, some content that displays in the AI chat is static text that is hard-coded inside of the AI chat. This includes items such as the "Type something..." message that appears as the placeholder text in the input field or the "Choose a date" text that appears on a date picker. By default, these texts display in English but you can change the language of the texts. The AI chat provides several translations for these texts and you can configure the AI chat to use those languages.

In addition, the individual texts can change if you want to use different text or if you want to provide your own translations for a language the AI chat does not have support for.

The list of languages and their language codes that the AI chat provides 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 the language by calling the updateLocale instance method and by using the appropriate language code.

In addition to switching to the supported languages, you can also provide your own strings to either change the string for any message, or to provide your own language support. For example, when you prompt 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. The JSON object specifies the replacement strings.

You can find the strings that the AI chat uses in the languages folder.

These files are in the ICU Message Format JSON representations of all of the languages that watsonx Assistant action skills, dialog skills and the AI chat widget support.

Note: The provided JSON object does not need to contain all strings, just the strings you want to update. Your changes merge with the existing language strings.

Locales

In addition to languages, the AI 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 the AI chat. For example, date strings in UK English are in the dd/mm/yyyy format, while US English dates are in the mm/dd/yyyy format.

Note: This setting does not affect any strings received from your your assistant; it applies only to strings displayed by the AI chat itself.

The AI chat supports the locales that the dayjs library provide.

Bi-directional Support

Some languages are read from left to right (ltr), and others from right to left (rtl). The AI chat renders text in the same direction as the page based on the dir attribute on the <html> tag.

Cookies and GDPR

The AI chat does not use any cookies. It uses the browser's transient session storage for required behavior to track the state of the AI chat as you navigate from page to page (e.g., should the home screen be visible, do you have an active tour open, and so on).