updateWelcomeScreen()

Updates welcome 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 welcome screen element. You can call this method at any time to change the current welcome screen display.

Syntax

instance.updateWelcomeScreen(config);

Parameters

object

required

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

`config` properties

string

Primary greeting heading that is 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 ('').

For an optimal experience on the chat welcome screen, keep the welcome message to 100 characters or fewer. Concise messages improve readability and help ensure consistent display across screen sizes and devices.

string

Supporting information that is 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 ('').

boolean

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

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

array

Array of interactive prompt cards. One to three cards display in a static grid, and four or more 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.

string

required

Main heading of the prompt card.

Character limit: 1000 characters (capped at 2 lines)

string

Supporting text below the title.

Character limit: 1000 characters (capped at 2 lines)

string

required

The actual text sent to the agent when clicked.

`agentIcon` property

string

Visual identifier that persists beyond the welcome 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

Returns a void operator.

Examples

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

instance.updateWelcomeScreen({
    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.updateWelcomeScreen({
    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.updateWelcomeScreen({
    welcomeMessage: 'Welcome!',
    agentIcon: '' // Explicitly removes icon
});

The following example shows how to hide the timestamp:

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

The following example demonstrates removing all starter prompts:

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

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

instance.updateWelcomeScreen({
    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.updateWelcomeScreen({
    welcomeMessage: 'Custom SVG Icon',
    agentIcon: `data:image/svg+xml;base64,${svgBase64}`
});

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

instance.updateWelcomeScreen({
    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.updateWelcomeScreen({
    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.updateWelcomeScreen({
    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 welcome screen elements:

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

Alternative approach: You can also hide the welcome screen by configuring the agent settings in the watsonx Orchestrate UI. This provides another way to control welcome screen visibility without using the updateWelcomeScreen() 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 updateWelcomeScreen configuration, the system uses the previous value that is stored in Redux. This means that previously set values persist unless explicitly overridden. To reset to defaults, you must explicitly set the property, for example, empty string for text or empty array for prompts.

Empty string vs null vs omitted

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

Examples:

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

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

// Remove all starter prompts
instance.updateWelcomeScreen({
    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.updateWelcomeScreen({
    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 that is provided in the text is 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 display as plain text.

Starter prompts display

One to three cards: Displayed in a static grid layout.
Four or more cards: Displayed in a horizontal slider or carousel.
No quantity limit: Supports unlimited number of prompt cards.

Timing

Important: Do not call updateWelcomeScreen() 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 updateWelcomeScreen
    instance.updateWelcomeScreen({
        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

Welcome 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 welcome screen. It is not displayed in the chat view or across the session.

Error handling

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

try {
    instance.updateWelcomeScreen({
        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, for example, passing a number instead of a string.
Malformed URLs for agentIcon.

Best practices

Review 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 100 characters..."

Consider carousel threshold

// One to three prompts: Static grid (optimal for quick scanning)
starterPrompts: [prompt1, prompt2, prompt3]

// Four or more 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.updateWelcomeScreen(config);
};

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

Personalize when possible

Use user context to create relevant experiences.

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

instance.updateWelcomeScreen({
    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.updateWelcomeScreen({
    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?

​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