updateHomeScreen()

Updates home screen elements including welcome message, description, starter prompts, timestamp, and agent icon by modifying the agentWelcomeContent Redux state. This method enables dynamic customization of the chat interface’s initial appearance and content. The method accepts a configuration object that defines the properties of each home screen element. You can call this method anytime to change the current home screen display.

Syntax

instance.updateHomeScreen(config);

Parameters

config

object

required

Configuration object containing home screen element definitions. All properties are optional.

`config` properties

welcomeMessage

string

Primary greeting heading displayed as large text. Supports Markdown formatting.

Character limit: 150 characters (capped at 4 lines in the UI)
Default behavior: When omitted, the previous Redux value is retained. To remove the welcome message, set it to an empty string ('').

description

string

Supporting information shown as subheading below the welcome message. Supports Markdown formatting.

Character limit: 1000 characters (capped at 2 lines in the UI)
Default behavior: When omitted, the previous Redux value is retained. To remove the description, set it to an empty string ('').

showTimestamp

boolean

Controls whether the current time is displayed in the top-left corner of the home screen.

Default behavior: When omitted, the previous Redux value is retained.

starterPrompts

array

Array of interactive prompt cards. 1-3 cards display in a static grid; 4+ cards display in a horizontal carousel.

Default behavior: When omitted, the previous Redux value is retained. To remove all prompts, set it to an empty array ([]).

`starterPrompts` item properties

string

required

Unique identifier for the prompt.

title

string

required

Main heading of the prompt card.

Character limit: 1000 characters (capped at 2 lines)

subtitle

string

Supporting text below the title.

Character limit: 1000 characters (capped at 2 lines)

prompt

string

required

The actual text sent to the agent when clicked.

`agentIcon` property

agentIcon

string

Visual identifier that persists beyond the home screen. Accepts a URL string.

Supported formats: External URL, SVG data URL with base64 encoding (recommended for SVG), PNG, JPG, SVG
Default behavior: When omitted, the previous Redux value is retained. To remove the icon, set it to an empty string ('') or null.

Returns

void

Returns a void operator.

Examples

The following example shows a full configuration with all available properties:

instance.updateHomeScreen({
    welcomeMessage: '# Welcome to WxO Chat! 🎉',
    description: 'This is a complete configuration example with all available properties enabled.',
    showTimestamp: true,
    starterPrompts: [
        {
            id: 'prompt-1',
            title: '🚀 Quick Start',
            subtitle: 'Get started quickly',
            prompt: 'How do I get started?'
        },
        {
            id: 'prompt-2',
            title: '📚 Documentation',
            subtitle: 'Browse guides',
            prompt: 'Show me the documentation'
        }
    ],
    agentIcon: 'https://raw.githubusercontent.com/twitter/twemoji/master/assets/svg/1f916.svg'
});

The following example shows a minimal configuration with only the welcome message:

instance.updateHomeScreen({
    welcomeMessage: 'Hello! How can I help you today?'
    // All other properties omitted - they will keep their previous Redux values
});

The following example demonstrates removing the agent icon by setting it to an empty string:

instance.updateHomeScreen({
    welcomeMessage: 'Welcome!',
    agentIcon: '' // Explicitly removes icon
});

The following example shows how to hide the timestamp:

instance.updateHomeScreen({
    welcomeMessage: 'Welcome to Support',
    description: 'How can we help you today?',
    showTimestamp: false
});

The following example demonstrates removing all starter prompts:

instance.updateHomeScreen({
    welcomeMessage: 'Welcome!',
    description: 'Type your question below',
    starterPrompts: [] // Removes all prompts
});

The following example shows a custom icon loaded from an external URL:

instance.updateHomeScreen({
    welcomeMessage: 'Welcome to Support',
    agentIcon: 'https://raw.githubusercontent.com/twitter/twemoji/master/assets/svg/1f916.svg'
});

The following example demonstrates using a base64-encoded SVG data URL for a custom icon:

const svgBase64 = 'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDAgMTAwIj48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImdyYWQiIHgxPSIwJSIgeTE9IjAlIiB4Mj0iMTAwJSIgeTI9IjEwMCUiPjxzdG9wIG9mZnNldD0iMCUiIHN0eWxlPSJzdG9wLWNvbG9yOiM2NjdlZWE7c3RvcC1vcGFjaXR5OjEiIC8+PHN0b3Agb2Zmc2V0PSIxMDAlIiBzdHlsZT0ic3RvcC1jb2xvcjojNzY0YmEyO3N0b3Atb3BhY2l0eToxIiAvPjwvbGluZWFyR3JhZGllbnQ+PC9kZWZzPjxjaXJjbGUgY3g9IjUwIiBjeT0iNTAiIHI9IjQ1IiBmaWxsPSJ1cmwoI2dyYWQpIi8+PC9zdmc+';

instance.updateHomeScreen({
    welcomeMessage: 'Custom SVG Icon',
    agentIcon: `data:image/svg+xml;base64,${svgBase64}`
});

The following example shows 4 starter prompts that will display in a carousel:

instance.updateHomeScreen({
    welcomeMessage: 'How can we help you?',
    starterPrompts: [
        {
            id: 'prompt-1',
            title: 'Product Info',
            subtitle: 'Learn about products',
            prompt: 'Tell me about your products'
        },
        {
            id: 'prompt-2',
            title: 'Pricing',
            subtitle: 'View pricing plans',
            prompt: 'What are your pricing options?'
        },
        {
            id: 'prompt-3',
            title: 'Support',
            subtitle: 'Get help',
            prompt: 'I need technical support'
        },
        {
            id: 'prompt-4',
            title: 'Documentation',
            subtitle: 'Browse docs',
            prompt: 'Show me the documentation'
        }
    ]
});

The following example demonstrates a personalized greeting using JavaScript variables:

const userName = 'Alice Johnson';
const userRole = 'Senior Developer';
const userCompany = 'IBM';
const currentTime = new Date().toLocaleTimeString();

instance.updateHomeScreen({
    welcomeMessage: `Hello ${userName}! 👋`,
    description: `Welcome back! You're logged in as ${userRole} at ${userCompany}. Current time: ${currentTime}`,
    showTimestamp: true,
    starterPrompts: [
        {
            id: 'prompt-1',
            title: 'My Profile',
            subtitle: 'View your information',
            prompt: `Show me my profile as ${userName}`
        },
        {
            id: 'prompt-2',
            title: 'My Tasks',
            subtitle: 'View pending tasks',
            prompt: 'What are my pending tasks?'
        }
    ]
});

The following example demonstrates multilingual support with emojis:

instance.updateHomeScreen({
    welcomeMessage: 'Welcome! 🎉  مرحبا 欢迎 स्वागत Bienvenue',
    description: 'Supporting emojis 🚀 and international text: English, 中文 (Chinese), العربية (Arabic), हिन्दी (Hindi), Français',
    showTimestamp: true,
    starterPrompts: [
        {
            id: 'prompt-1',
            title: 'Multilingual 🌍',
            subtitle: 'International support',
            prompt: 'Tell me about multilingual support'
        },
        {
            id: 'prompt-2',
            title: 'Languages 🗣️',
            subtitle: 'Available languages',
            prompt: 'What languages do you support?'
        }
    ]
});

The following example shows how to hide all home screen elements:

instance.updateHomeScreen({
    welcomeMessage: '',
    description: '',
    agentIcon: '',
    starterPrompts: [],
    showTimestamp: false
});

Alternative approach: You can also hide the home screen by configuring the agent settings in the watsonx Orchestrate UI. This provides another way to control home screen visibility without using the updateHomeScreen() method.

Considerations

Property behavior

When a property is omitted from the configuration object, the previous Redux state value is retained. This allows for partial updates without affecting other properties.

Important: When you omit a property from the updateHomeScreen configuration, the system will use the previous value stored in Redux. This means previously set values will persist unless explicitly overridden. To reset to defaults, you need to explicitly set the property (e.g., empty string for text, empty array for prompts).

Empty string vs null vs omitted

Value	Behavior
Omitted	Previous Redux value is retained
Empty string (`''`)	Property is cleared/removed
`null`	Property is cleared/removed
Empty array (`[]`)	All items are removed (for `starterPrompts`)

Examples:

// Remove description using empty string
instance.updateHomeScreen({
    description: ''  // Description is removed
});

// Remove agent icon using null
instance.updateHomeScreen({
    agentIcon: null  // Icon is removed
});

// Remove all starter prompts
instance.updateHomeScreen({
    starterPrompts: []  // All prompts are removed
});

Character limits and line capping

The UI enforces character limits and line capping to maintain a clean interface:

Property	Character limit	Line cap	Behavior when exceeded
`welcomeMessage`	150 characters	4 lines	Text is truncated with ellipsis
`description`	1000 characters	2 lines	Text is truncated with ellipsis
`starterPrompts[].title`	1000 characters	2 lines	Text is truncated with ellipsis
`starterPrompts[].subtitle`	1000 characters	2 lines	Text is truncated with ellipsis
`starterPrompts[].prompt`	No limit	N/A	Full text is sent to agent

Merge strategy

The method uses a deep merge strategy with array replacement:

Objects: Deeply merged (nested properties combined)
Arrays: Completely replaced (not merged)
Scalars: Replaced with new values

When both programmatic configuration and API responses are present:

API calls are always made
Programmatic values take precedence over API values
API fills in missing fields with defaults

// Programmatic config
instance.updateHomeScreen({
    welcomeMessage: "Custom Welcome"
});

// API response provides
{
    welcomeMessage: "Default Welcome",
    description: "Default Description",
    starterPrompts: [...]
}

// Final result
{
    welcomeMessage: "Custom Welcome",        // Programmatic wins
    description: "Default Description",      // API fills missing
    starterPrompts: [...]                    // API fills missing
}

Content formatting

Customization of the welcome screen’s visual style is not supported. Only the default welcome screen design is applied. Text content can be modified; however, no formatting is supported. Any Markdown or HTML syntax provided in the text will be rendered as plain text and is not interpreted.

Limitations

Only text content can be updated
Styling, layout, and formatting cannot be customized
Markdown and HTML tags are not supported and will display as plain text

Starter prompts display

1-3 cards: Displayed in a static grid layout
4+ cards: Displayed in a horizontal slider/carousel
No quantity limit: Supports unlimited number of prompt cards

Timing

Important: Do not call updateHomeScreen() before the chat instance is initialized. The method requires an active instance and will fail if called before the onLoad callback fires.

The method can be called immediately from onLoad without waiting for chat:ready:

// ✅ CORRECT: Called after chat initialization
window.watsonxOrchestrate.onLoad = function(instance) {
    // Now it's safe to call updateHomeScreen
    instance.updateHomeScreen({
        welcomeMessage: '✅ Called AFTER onLoad',
        description: 'This is set after chat initialized'
    });
};

// ❌ INCORRECT: Called before chat initialization
wxoChat.updateWelcomeScreen({
    welcomeMessage: '🚫 Called BEFORE onLoad'
});

// Chat initialization happens later
window.wxOConfiguration = {
    orchestrationID: '<tenantId>',
    chatOptions: {
        onLoad: function(instance) {
            // Instance is now available
        }
    }
};

Layout support

Home screen customization is available for the following form layouts:

✅ Floating: Floating chat widget
✅ Custom: Custom implementations (including side panel)
✅ Fullscreen: Fullscreen chat interface
❌ Standalone: Not supported (embedded chat only)

Agent icon persistence

The customized agent icon is currently supported only on the home screen. It is not displayed in the chat view or across the session.

Error handling

The updateHomeScreen() method validates input and throws errors for invalid configurations:

try {
    instance.updateHomeScreen({
        welcomeMessage: 'Hello!',
        starterPrompts: [
            {
                // Missing required 'id' property
                title: 'Test',
                prompt: 'Test prompt'
            }
        ]
    });
} catch (error) {
    console.error('Configuration error:', error.message);
}

Common error scenarios:

Missing required properties in starter prompt objects (id, title, prompt)
Invalid data types (e.g., passing a number instead of a string)
Malformed URLs for agentIcon

Best practices

Check the following practices for creating better starter prompts.

Provide meaningful starter prompts

// ✅ Good: Clear, actionable prompts
starterPrompts: [
    {
        id: 'prompt-1',
        title: "Track My Order",
        subtitle: "Check delivery status and tracking information",
        prompt: "I want to track my order"
    }
]

// ❌ Bad: Vague prompts
starterPrompts: [
    {
        id: 'prompt-1',
        title: "Help",
        subtitle: "Get help",
        prompt: "Help"
    }
]

Keep text concise

Respect character limits and line caps for optimal display. Test with long text to verify how your content appears when truncated.

// ✅ Good: Concise and within limits
welcomeMessage: "Welcome to Support! 👋"

// ⚠️ Caution: May be truncated
welcomeMessage: "This is a very long welcome message that exceeds 150 characters..."

Consider carousel threshold

// 1-3 prompts: Static grid (optimal for quick scanning)
starterPrompts: [prompt1, prompt2, prompt3]

// 4+ prompts: Carousel (better for many options)
starterPrompts: [prompt1, prompt2, prompt3, prompt4, prompt5]

SVG icon formats

SVG icons can be provided in multiple formats:

// ✅ Recommended: Base64-encoded SVG data URL
agentIcon: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDAgMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI0NSIgZmlsbD0iIzY2N2VlYSIvPjwvc3ZnPg=='

// ✅ Also supported: External URL
agentIcon: 'https://example.com/icon.svg'

// ✅ Also supported: Inline SVG string
agentIcon: `
<svg width="24" height="24" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
  <circle cx="32" cy="20" r="10" fill="#4CAF50"/>
  <path d="M10 58c0-12 10-18 22-18s22 6 22 18" fill="#4CAF50"/>
  <circle cx="32" cy="20" r="3" fill="white"/>
</svg>
`

Call early in lifecycle

// ✅ Good: Call from onLoad
window.watsonxOrchestrate.onLoad = function(instance) {
    instance.updateHomeScreen(config);
};

// ⚠️ Acceptable but unnecessary: Wait for chat:ready
instance.on('chat:ready', () => {
    instance.updateHomeScreen(config);
});

Personalize when possible

Use user context to create relevant experiences.

// ✅ Good: Personalized based on user context
const userName = getUserName();
const userRole = getUserRole();

instance.updateHomeScreen({
    welcomeMessage: `Hello ${userName}!`,
    starterPrompts: getRoleSpecificPrompts(userRole)
});

Support internationalization

Test with multilingual text and emojis to ensure proper display.

// ✅ Good: Supports multiple languages and emojis
instance.updateHomeScreen({
    welcomeMessage: 'Welcome! 🎉 Bienvenue! 欢迎!',
    description: 'We support English, Français, and 中文'
});

Do you need practical examples?

Learn how to apply the features available for embedded chat into your implementation with guidance and examples.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Syntax

Parameters

`config` properties

`starterPrompts` item properties

`agentIcon` property

Returns

Examples

Considerations

Property behavior

Empty string vs null vs omitted

Character limits and line capping

Merge strategy

Content formatting

Limitations

Starter prompts display

Timing

Layout support

Agent icon persistence

Error handling

Best practices

Provide meaningful starter prompts

Keep text concise

Consider carousel threshold

SVG icon formats

Call early in lifecycle

Personalize when possible

Support internationalization

Do you need practical examples?

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Documentation Index

​Syntax

​Parameters

​config properties

​starterPrompts item properties

​agentIcon property

​Returns

​Examples

​Considerations

​Property behavior

​Empty string vs null vs omitted

​Character limits and line capping

​Merge strategy

​Content formatting

​Limitations

​Starter prompts display

​Timing

​Layout support

​Agent icon persistence

​Error handling

​Best practices

​Provide meaningful starter prompts

​Keep text concise

​Consider carousel threshold

​SVG icon formats

​Call early in lifecycle

​Personalize when possible

​Support internationalization

Do you need practical examples?

Syntax

Parameters

`config` properties

`starterPrompts` item properties

`agentIcon` property

Returns

Examples

Considerations

Property behavior

Empty string vs null vs omitted

Character limits and line capping

Merge strategy

Content formatting

Limitations

Starter prompts display

Timing

Layout support

Agent icon persistence

Error handling

Best practices

Provide meaningful starter prompts

Keep text concise

Consider carousel threshold

SVG icon formats

Call early in lifecycle

Personalize when possible

Support internationalization