> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutorial: Customizing embedded chat to match your brand

In this tutorial, you learn how to customize the appearance and behavior of the watsonx Orchestrate embedded chat widget so that it matches your website's brand. By default, the widget ships with IBM Blue styling. This tutorial covers three levels of customization, from point-and-click UI settings to full embed script control.

Customization is organized into three levels, each building on the previous one:

| Level | Approach       | Time estimate | What you control                                         |
| ----- | -------------- | ------------- | -------------------------------------------------------- |
| 1     | Builder UI     | \~10 minutes  | Agent name, starter prompts, voice mode, document upload |
| 2     | ADK YAML edits | \~15 minutes  | Custom icon, welcome message, hide reasoning trace       |
| 3     | Embed script   | \~20 minutes  | Colors, typography, layout, header controls              |

## Before you begin

This tutorial uses a fictional banking assistant called **Lendyr** to exemplify branding customizations you can apply to any embedded chat deployment.

Before you start this tutorial, ensure you have the following:

* An active watsonx Orchestrate account with an agent created and published.
* The [Agent Development Kit (ADK)](../getting_started/installing) installed for YAML-based edits.
* Security configured for the embedded chat. For more information, see [Configuring security for embedded chat](https://www.ibm.com/docs/SSAVQO/deploy/web_chat_agent/web_chat_configuring_security.html).
* Your `orchestrationID` and `agentId` values from the **Channels** tab in the Builder UI.

## Level 1: Builder UI settings

The Builder UI provides point-and-click controls for the most common settings. No code is required.

1. Log in to the watsonx Orchestrate Builder UI.
2. Open your agent.
3. Configure the following settings:
   * **Agent name**, such as `Lendyr Banking Assistant`.
   * **Starter prompts**, such as `Apply for a loan` and `Find nearest branch`.
   * **Chat with docs** toggle: enable to allow document uploads.
   * **Voice mode** toggle: enable to allow speech input.

## Level 2: ADK YAML edits

Three settings are not available in the Builder UI and require direct edits to the agent YAML file: hiding the reasoning trace, adding a custom icon, and writing a branded welcome message.

1. Open your agent YAML file in the ADK.

2. Add the following fields:

   ```yaml YAML [expandable] theme={null}
   hide_reasoning: true

   icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
     <rect width="100" height="100" fill="#2d5016"/>
     <text x="50" y="70" font-family="Arial" font-size="60"
           font-weight="bold" fill="#81c784" text-anchor="middle">D</text>
   </svg>'

   welcome_content:
     welcome_message: "Hi, I'm the Lendyr assistant!"
     description: "How can I help you today?"
     is_default_message: false
   ```

3. Deploy the updated agent:

   ```bash BASH theme={null}
   orchestrate agents import -f your_agent.yaml
   ```

<Note>
  The custom icon SVG is the first visual element users see and carries the greatest branding impact. Set `hide_reasoning: true` in production deployments to prevent the agent's internal thinking trace from reaching end users.
</Note>

## Level 3: Embed script configuration

The embed script gives you full control over colors, typography, layout, and header behavior.

1. Get the embed script from the **Channels** tab. You can also generate it from the CLI:

   ```bash BASH theme={null}
   orchestrate channels webchat embed --agent-name=your_agent_name
   ```

2. Before the closing `</body>` tag of your page, add the `window.wxOConfiguration` object with your customizations:

   ```javascript JavaScript [expandable] theme={null}
   window.wxOConfiguration = {
       orchestrationID: "your-orchestration-id",
       hostURL: "https://dl.watson-orchestrate.ibm.com",
       rootElementID: "root",
       showLauncher: true,

       chatOptions: {
           agentId: "your-agent-id",
           agentEnvironmentId: "your-env-id"
       },

       layout: {
           form: 'float',
           width: '800px',
           height: '600px',
           showMaxWidth: true
       },

       style: {
           headerColor: '#2d5016',
           userMessageBackgroundColor: '#2d5016',
           primaryColor: '#2d5016',
           showBackgroundGradient: true,
           fontFamily: 'Inter, system-ui, sans-serif'
       },

       header: {
           showResetButton: true,
           showAiDisclaimer: false,
           showMaximize: true,
           showAgentName: false,
           showAgentAvatar: false
       },

       features: {
           showThreadList: true
       },

       language: 'en'
   };
   ```

3. Test on your staging site and adjust the colors and layout as needed.

4. Deploy to production.

## Key configuration reference

| Category   | Property                     | Description                                                       |
| ---------- | ---------------------------- | ----------------------------------------------------------------- |
| `style`    | `headerColor`                | Brand color for the chat header background                        |
| `style`    | `primaryColor`               | Color for interactive accents and highlights                      |
| `style`    | `userMessageBackgroundColor` | Color for user message bubbles                                    |
| `style`    | `fontFamily`                 | Font stack to match your brand typography                         |
| `header`   | `showResetButton`            | Show or hide the conversation reset button                        |
| `header`   | `showMaximize`               | Show or hide the maximize button                                  |
| `header`   | `showAgentName`              | Show or hide the agent name in the header                         |
| `header`   | `showAgentAvatar`            | Show or hide the agent avatar in the header                       |
| `layout`   | `form`                       | `'float'` for a chat bubble, `'fullscreen-overlay'` for full-page |
| `layout`   | `width` / `height`           | Override the default chat dimensions                              |
| `features` | `showThreadList`             | Show or hide the conversation history panel                       |

For a full list of supported options, see the [UI configuration](../webchat/ui_configuration).

## Testing your customization

After you deploy the embed script, verify the following:

1. The chat header uses your brand color.
2. User message bubbles use your brand color.
3. Your custom icon appears when the chat bubble is closed.
4. The welcome message matches your configured `welcome_content`.
5. Users do not see the reasoning trace or internal thinking.
6. Starter prompts appear on the chat landing screen.

## Common issues

| Issue                                  | Solution                                                                                            |
| -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Colors appear different on your site   | Test on a staging environment against your actual page background                                   |
| Custom icon does not display           | Check that the SVG syntax is valid and correctly inlined in YAML                                    |
| Changes do not appear after deployment | Clear the browser cache and confirm you are targeting the correct environment, either Live or Draft |