Customizing the chat UI

Customize the user interface (UI) of the chat to better fit your website’s design and enhance the user experience. You can modify various aspects of the chat UI, including layout, styles, header options, and language settings.

Header

Controls the visibility of chat header actions. To apply header configuration, add a header component inside the window.wxOConfiguration object in your web chat script. In this component, you can configure the following parameters:

Parameter	Type	Default	Description
header.showResetButton	Boolean	true	Displays the Reset Chat button in the header when set to true.
header.showAiDisclaimer	Boolean	true	Displays the AI disclaimer icon/button in the header when set to true.
header.showMaximize	Boolean	false	Controls the visibility of the ‘Maximize chat’ button in the chat header. You can combine this parameter with additional layout modifiers, such as: Custom elements: Explicitly set height to the custom element (layout.customElement) to render the chat window within it. Padding: Define layout.showMaxWidth to control whether additional vertical padding is applied between the chat border and content container.

The following is an example of how to customize the embedded web chat header:

All parameters

<script>
window.wxOConfiguration = {
  orchestrationID: "my-tenant-id",
  hostURL: "my-host-url",
  rootElementID: "root",            // fullscreen-overlay only
  showLauncher: false,              // fullscreen-overlay only, false = direct render, true = launcher bubble
  chatOptions: {
    agentId: "12345_test_agent1",            // required
    agentEnvironmentId: "my-agent-env-id"    // required
  },
  header: {
    showResetButton: true,   // optional; defaults to true
    showAiDisclaimer: true,   // optional; defaults to true
    showMaximize: false  // optional; defaults to false
  },
};

setTimeout(function() {
  const script = document.createElement('script');
  script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
  script.addEventListener('load', () => wxoLoader.init());
  document.head.appendChild(script);
}, 0);
</script>

Features

Control the visibility and behavior of chat features. To apply feature configuration, add a features component inside the window.wxOConfiguration object in your chat script. In this component, you can configure the following parameters:

Parameter	Type	Default	Description
features.showThreadList	Boolean	Default behavior varies by layout: fullscreen-overlay: defaults to true float and custom: defaults to false	Controls the visibility of the chat history (thread list) in the side panel. When enabled, users can view and navigate their conversation history through the side panel. When disabled, the side panel displays only custom header items (if configured). You can explicitly set this to true or false to override the default behavior for any layout.
features.showAgentMemory	Boolean	false	Controls the visibility of the agent memory button in the side panel. When enabled, users can access the agent memory button to view and delete their memories, or turn the feature off. When disabled, the agent memory button is not displayed. To configure memory for an agent, see the feature implementation in the Understanding agent memory documentation.

• In the Float and Custom form factors, the thread list can be hidden either by omitting the property (as false is the default) or by explicitly setting showThreadList: false.
• In the Full-screen form factor, however, you must explicitly set showThreadList: false to hide the thread list, as the default value is true.

The following examples show how to configure the thread list feature:

Enable showThreadList and showAgentMemory

<script>
window.wxOConfiguration = {
  orchestrationID: "my-tenant-id",
  hostURL: "my-host-url",
  rootElementID: "root",            // fullscreen-overlay only
  showLauncher: false,              // fullscreen-overlay only, false = direct render, true = launcher bubble
  chatOptions: {
    agentId: "12345_test_agent1",            // required
    agentEnvironmentId: "my-agent-env-id"    // required
  },
  features: {
    showThreadList: true, // explicitly enable for any layout
    showAgentMemory: true
  },
};

setTimeout(function() {
  const script = document.createElement('script');
  script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
  script.addEventListener('load', () => wxoLoader.init());
  document.head.appendChild(script);
}, 0);
</script>

Language

Define the default language of the chat interface. To apply language configuration, add the following parameters inside the window.wxOConfiguration object in your web chat script:

Parameter	Type	Default	Description
defaultLocale	String	en	Defines the default language supported by the chat.

The following table lists the supported locale strings:

Language	Language code
Chinese - Traditional	zh-TW
Chinese - Simplified	zh-CN
English	en
French	fr
German	de
Italian	it
Japanese	ja
Korean	ko
Portuguese - Brazil	pt-BR
Spanish	es

The following is an example of how to customize the embedded web chat language:

<script>
window.wxOConfiguration = {
  orchestrationID: "my-tenant-id",
  hostURL: "my-host-url",
  rootElementID: "root",            // fullscreen-overlay only
  showLauncher: false,              // fullscreen-overlay only, false = direct render, true = launcher bubble
  chatOptions: {
    agentId: "12345_test_agent1",            // required
    agentEnvironmentId: "my-agent-env-id"    // required
  },
  defaultLocale: 'ja',
};

setTimeout(function() {
  const script = document.createElement('script');
  script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
  script.addEventListener('load', () => wxoLoader.init());
  document.head.appendChild(script);
}, 0);
</script>

Styles

You can customize embedded web chats to create a unique chat interface that better fits your webpage. To apply custom styles, add a style component inside the window.wxOConfiguration object in your web chat script. In this component, you can configure the following parameters:

Parameter	Type	Default	Description
headerColor	String	—	Set a six-digit hex code that defines the chat header color.
userMessageBackgroundColor	String	—	Set a six-digit hex code that defines the user message bubble color.
primaryColor	String	—	Set a six-digit hex code that defines the interactive elements color.
showBackgroundGradient	Boolean	true	Displays the background gradient when set to true.

The following is an example of how to customize the embedded web chat styles:

<script>
window.wxOConfiguration = {
  orchestrationID: "my-tenant-id",
  hostURL: "my-host-url",
  rootElementID: "root",            // fullscreen-overlay only
  showLauncher: false,              // fullscreen-overlay only, false = direct render, true = launcher bubble
  chatOptions: {
    agentId: "12345_test_agent1",            // required
    agentEnvironmentId: "my-agent-env-id"    // required
  },
   style: {
    headerColor: '', //6-digit hex value or empty for default
    userMessageBackgroundColor: '', //6-digit hex value or empty for default
    primaryColor: '', //6-digit hex value or empty for default
    showBackgroundGradient: true, // optional; defaults to true
  },
};

setTimeout(function() {
  const script = document.createElement('script');
  script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
  script.addEventListener('load', () => wxoLoader.init());
  document.head.appendChild(script);
}, 0);
</script>

Layout

Control how and where the chat UI appears. To apply layout configuration, add a layout component inside the window.wxOConfiguration object in your web chat script. In this component, you can configure the following parameters:

Parameter	Type	Default	Scope	Description
rootElementID	String	—	fullscreen-overlay only	The ID of the container node to mount chat into.
showLauncher	Boolean	true	fullscreen-overlay only	Sets the initial launcher visibility: show the bubble launcher (true) or render chat immediately (false). To control launcher visibility at runtime for any layout mode, use the changeView() instance method.
layout.form	String	float	—	Defines the layout form of your web chat. Use fullscreen-overlay to display the web chat in fullscreen mode. No additional parameters are required. Use float to display the web chat as a floating window. Also configure: width: Width of the web chat height: Height of the web chat Use custom to define a custom layout. Also configure the customElement parameter with your custom element.
layout.width	String	—	float only	Popup width (e.g. ‘350px’, ‘30rem’).
layout.height	String	—	float only	Popup height (e.g. ‘500px’, ‘40rem’).
layout.showOrchestrateHeader	Boolean	true	—	Render the standard header bar (true) or hide it (false).
layout.showMaxWidth	Boolean	false	—	Controls whether additional vertical padding is applied between the chat border and content container.
layout.customElement	HTMLElement	—	—	Element reference to render into.

The following is an example of how to customize the embedded web chat layout:

Float mode

<script>
window.wxOConfiguration = {
  orchestrationID: "my-tenant-id",
  hostURL: "my-host-url",
  rootElementID: "root",            // fullscreen-overlay only
  showLauncher: false,              // fullscreen-overlay only, false = direct render, true = launcher bubble

  chatOptions: {
    agentId: "12345_test_agent1",            // required
    agentEnvironmentId: "my-agent-env-id"    // required
  },

  layout: {
    form: 'float',                           // 'fullscreen-overlay' | 'float' | 'custom'
    width: '600px',                          // float only
    height: '600px',                         // float only
    showOrchestrateHeader: true,            // hide header if false
    showMaxWidth: true,                     // optional; defaults to false
    customElement: hostElement              // custom only
  }
};

setTimeout(function() {
  const script = document.createElement('script');
  script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
  script.addEventListener('load', () => wxoLoader.init());
  document.head.appendChild(script);
}, 0);
</script>