> ## 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. # 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 ```javascript theme={null} instance.updateWelcomeScreen(config); ``` ## Parameters Configuration object containing welcome screen element definitions. All properties are optional. ### `config` properties 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. 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 (`''`). 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 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 Unique identifier for the prompt. Main heading of the prompt card. * **Character limit**: 1000 characters (capped at 2 lines) Supporting text below the title. * **Character limit**: 1000 characters (capped at 2 lines) The actual text sent to the agent when clicked. ### `agentIcon` property 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: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} instance.updateWelcomeScreen({ welcomeMessage: 'Welcome!', agentIcon: '' // Explicitly removes icon }); ``` The following example shows how to hide the timestamp: ```javascript theme={null} instance.updateWelcomeScreen({ welcomeMessage: 'Welcome to Support', description: 'How can we help you today?', showTimestamp: false }); ``` The following example demonstrates removing all starter prompts: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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:** ```javascript theme={null} // 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: 1. API calls are always made. 2. Programmatic values take precedence over API values. 3. API fills in missing fields with defaults. ```javascript theme={null} // 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`: ```javascript theme={null} // ✅ 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' }); }; ``` ```javascript theme={null} // ❌ INCORRECT: Called before chat initialization wxoChat.updateWelcomeScreen({ welcomeMessage: '🚫 Called BEFORE onLoad' }); // Chat initialization happens later window.wxOConfiguration = { orchestrationID: '', 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: ```javascript theme={null} 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 ```javascript theme={null} // ✅ 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. ```javascript theme={null} // ✅ 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 ```javascript theme={null} // 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: ```javascript theme={null} // ✅ 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: ` ` ``` ### Call early in lifecycle ```javascript theme={null} // ✅ 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. ```javascript theme={null} // ✅ 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. ```javascript theme={null} // ✅ Good: Supports multiple languages and emojis instance.updateWelcomeScreen({ welcomeMessage: 'Welcome! 🎉 Bienvenue! 欢迎!', description: 'We support English, Français, and 中文' }); ``` Learn how to apply the features available for embedded chat into your implementation with guidance and examples.