Tutorial: Customizing embedded chat to match your brand

​

Before you begin

• An active watsonx Orchestrate account with an agent created and published.
• The Agent Development Kit (ADK) installed for YAML-based edits.
• Security configured for the embedded chat. For more information, see Configuring security for embedded chat.
• Your orchestrationID and agentId values from the Channels tab in the Builder UI.

​

Level 1: Builder UI settings

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

1. Open your agent YAML file in the ADK.
2. Add the following fields:
   YAML

   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
   

   See all 12 lines
3. Deploy the updated agent:
   BASH

   orchestrate agents import -f your_agent.yaml
   

​

Level 3: Embed script configuration

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

   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

   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'
   };
   

   See all 40 lines
3. Test on your staging site and adjust the colors and layout as needed.
4. Deploy to production.

​

Key configuration reference

​

Testing your customization

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