Customizing the embedded AI chat

Use the headers configuration to customize the embedded AI chat.

To customize the embedded AI chat, add the DEFAULT_CHAT_HEADER_CONFIG constant object inside the embedded AI chat script and then configure the custom customization for the embedded chat.

In the DEFAULT_CHAT_HEADER_CONFIG object, the customization configurations are made with three objects.

Object	Required	Description
`headerTitle`	Optional	Use this object to configure the custom title of your embedded AI chat. For more information, see Configuring embedded AI chat title
`left`	Optional	Use this object to configure the items like menus, buttons, or links that pertain to the platform. These items appear in the left side on the embedded AI chat. For more information, see Configuring embedded AI chat items.
`right`	Optional	Use this object to configure the items like menus, buttons, or links that pertain to the embedded AI chat. These items appear in the right side on the embedded AI chat. For more information, see Configuring embedded AI chat items.

Depending on the items quantity that you configure in the left and right objects, these items size might be larger than the page size of the embedded AI chat. When it occurs, the embedded AI chat automatically creates an overflow menu for the left and right side to group all items that didn't fit due to lack of space in the embedded AI chat. Therefore, first configure the items that you want to have a higher chance of being displayed outside the overflow menu.

The following example demonstrates customizing the embedded AI chat with a custom title, a button for each side of the AI chat, and a link on the left side.

<script>
  const DEFAULT_CHAT_HEADER_CONFIG = {
    headerTitle: { title: 'My custom title', name: '[Name]' },
    left: [
      {
        type: 'button',
        label: 'Left Button',
        onClick: () => { }
      },
      {
        type: 'link',
        url: 'https://www.ibm.com',
        label: 'ibm.com'
      },
    ],
    right: [
      {
        type: 'button',
        label: 'Right Button',
        onClick: () => { }
      },
    ],
  };
</script>

Configuring embedded AI chat title

Use the headerTitle to configure a custom title of your embedded AI chat. In the headerTitle object, you can configure the following properties.

Property	Required	Type	Description
`title`	Optional	String	Set the custom title for your embedded AI chat. Note: If you configure the `headerTitle` object but don't configure this property, then a blank title is shown.
`name`	Optional	String	Set the custom name for your embedded AI chat. It appears in bold right after the title of your embedded AI chat Note: If you configure the `headerTitle` object but don't configure this property, then a blank name is shown.

The following example shows how to configure the embedded AI chat with the "My custom title" tile and "NAME" name.

<script>
  const DEFAULT_CHAT_HEADER_CONFIG = {
    headerTitle: {
      title: 'My custom title',
      name: 'NAME'
    },
  };
</script>

Custom title example — Figure 1. The image shows how the previous example of title configuration looks like on the embedded AI chat.

Configuring embedded AI chat items

Use the left and right objects to configure custom items like menus, links, and buttons in your embedded AI chat. In these objects, you can configure the following properties.

Property	Required	Type	Description
`type`	Yes	String	The type of the item. It can be: menu link button
`label`	Yes	String	The name of the item.
Type specific properties	Yes	Depends on the item type	Each item type requires a set of properties configurations to work correctly. For more information, see Item types configuration.

The following example demonstrates configuring a button for each side of the AI chat, and a link on the left side.

<script>
  const DEFAULT_CHAT_HEADER_CONFIG = {
    left: [
      {
        type: 'button',
        label: 'Left Button',
        onClick: () => { }
      },
      {
        type: 'link',
        url: 'https://www.ibm.com',
        label: 'ibm.com'
      },
    ],
    right: [
      {
        type: 'button',
        label: 'Right Button',
        onClick: () => { }
      },
    ],
  };
</script>

Custom items example — Figure 2. The image shows how the previous example of items configuration looks like on the embedded AI chat.

Configuring the item types

There are three item types you can configure:

menu

A dropdown menu that you can use to have multiple items in just one menu.

To configure a menu item, add a items list and in that list configure all items that you want in the menu. You configure the items in this list in the same way that you configure any other item in the embedded AI chat.

You can nest up to 1 menu item within a menu item to create submenus in one menu item. However, create submenus inside submenus is not possible in the embedded AI chat.

This principle is also valid for overflow menus that are created automatically to group items for each side depending on the page size. For that reason be careful when you create submenus to not break it in cases that it enters in one overflow menu.

The following example shows how to configure a menu item on the left side. This menu contains a link and button items.

<script>
  const DEFAULT_CHAT_HEADER_CONFIG = {
    left: [
      {
        type: 'menu',
        label: 'Menu',
        items: [
          {
            type: 'link',
            url: 'https://www.ibm.com',
            label: 'IBM'
          },
          {
            type: 'button',
            label: 'Button',
            onClick: () => {
              alert('Button clicked');
            },
          },
        ],
      },
    ],
  };
</script>

In addition to the normal types, with a menu item you can also configure a new item type called radio-group. A radio-group item groups a list of options inside the menu item, with it you can configure functions when each one of these options is selected.

To configure the radio-group, inside the items property of one menu item configure an item with the following properties:

Property	Required	Type	Description
`type`	Yes	string	The type of the item. It must be `radio-group`.
`label`	Yes	string	The name of the radio group that is used internally to track the currently selected item.
`defaultSelectedItem`	Optional	string	The option from the list of option that is selected by default.
`items`	Yes	list of strings	The list of the options that need to be grouped in the `radio-group`.
`onChange`	Optional	function	A `onChange` function that describes the action that needs to be made when each option is selected.

The following example shows how to configure a radio-group with four options when the "Option 1" is the one that is selected by default.

<script>
  const DEFAULT_CHAT_HEADER_CONFIG = {
    left: [
      {
        type: 'menu',
        label: 'Group',
        items: [
          {
            type: 'radio-group',
            label: 'options-group',
            defaultSelectedItem: 'Option 1',
            items: ['Option 1', 'Option 2', 'Option 3', 'Option 4'],
            onChange: item => {
              alert(`${item} selected`);
            },
          },
        ],
      },
    ],
  };
</script>

link

A link that when it is clicked it redirects the user to the configured link.

To configure the link, add the url property and set the link that you want in a string format.

The following example shows how to configure a link item that redirects the user to `https://www.ibm.com.

<script>
  const DEFAULT_CHAT_HEADER_CONFIG = {
    left: [
      {
        type: 'link',
        url: 'https://www.ibm.com',
        label: 'IBM'
      },
    ],
  };
</script>

button

A button that, upon being clicked, executes a programmed action.

To configure an action that the button performs when clicked, add the onClick function and then configure the action.

The following example demonstrates configuring a button that, when clicked, spans an alert stating "Button clicked":

<script>
  const DEFAULT_CHAT_HEADER_CONFIG = {
    left: [
      {
        type: 'button',
        label: 'Button',
        onClick: () => {
          alert('Button clicked');
        },
      },
    ],
  };
</script>