getWriteableElement() - IBM watsonx Orchestrate ADK

Retrieves a reference to a writeable element container where custom HTML content can be injected into specific locations within the chat interface. Use this method to add custom notifications, images, carousels, banners, and other interactive content to enhance the chat experience.

Syntax

instance.getWriteableElement(elementName);

Parameters

elementName

string

required

The name of the writeable element location. Must be one of the available writeable element names.

Available writeable element locations

Element Name	Location	Description
`belowHeader`	Below chat header	Appears on a new line directly below the chat header. You can use for notifications, banners, or alerts.
`aboveInputBar`	Above input area	Positioned between the message area and the input field. Suitable for contextual information or quick actions.
`aboveWelcomeTitle`	Above welcome message	Displays in the main message body directly above the welcome message title.
`belowWelcomeStarters`	Below starter prompts	Appears in the main message body directly below the starter prompt cards.
`aiTooltipAfterDescription`	In AI disclaimer tooltip	Positioned within the AI disclaimer tooltip after the description content. For more information, see `aiTooltipAfterDescription`.
`chatWelcomeComponent`	Center of chat area	Displays in the center of the chat interface, overlaying the main content area. For more information, see `chatWelcomeComponent`.

`chatWelcomeComponent`

The chatWelcomeComponent location overlays the main chat area. When content is added to this element:

A CSS class has-center-chat-component is automatically added to the document body.
The class is removed when the element is empty.
Use this location sparingly as it obscures the main chat interface.
Use for loading screens, full-screen notifications, or modal-like content.

`aiTooltipAfterDescription`

This location appears within the AI disclaimer tooltip and has limited space. Keep content minimal and relevant to AI usage disclaimers.

Returns

HTMLDivElement

Returns an HTMLDivElement reference that can be used to inject custom HTML content.

Examples

The following example shows how to add a notification banner below the header:

const element = instance.getWriteableElement('belowHeader');
element.innerHTML = `
  <div class="WxOChatContainer WxOChatReset WxOChatStyles">
    <div style="padding: 12px; background-color: #0f62fe; color: white; text-align: center;">
      🔔 System maintenance scheduled for tonight at 10 PM EST
    </div>
  </div>
`;

The following example demonstrates adding a custom image carousel above the input bar:

const element = instance.getWriteableElement('aboveInputBar');
element.innerHTML = `
  <div class="WxOChatContainer WxOChatReset WxOChatStyles">
    <div style="display: flex; gap: 8px; padding: 12px; overflow-x: auto;">
      <img src="https://example.com/image1.jpg" style="width: 100px; height: 100px; border-radius: 8px;" />
      <img src="https://example.com/image2.jpg" style="width: 100px; height: 100px; border-radius: 8px;" />
      <img src="https://example.com/image3.jpg" style="width: 100px; height: 100px; border-radius: 8px;" />
    </div>
  </div>
`;

The following example demonstrates adding interactive buttons with click handlers:

const element = instance.getWriteableElement('belowWelcomeStarters');
element.innerHTML = `
  <div class="WxOChatContainer WxOChatReset WxOChatStyles">
    <div style="padding: 16px; text-align: center;">
      <button id="customAction1" style="padding: 8px 16px; margin: 4px; background-color: #0f62fe; color: white; border: none; border-radius: 4px; cursor: pointer;">
        View Latest Updates
      </button>
      <button id="customAction2" style="padding: 8px 16px; margin: 4px; background-color: #24a148; color: white; border: none; border-radius: 4px; cursor: pointer;">
        Contact Support
      </button>
    </div>
  </div>
`;

The following example demonstrates adding content with scrollable overflow:

const element = instance.getWriteableElement('aboveWelcomeTitle');
element.innerHTML = `
  <div class="WxOChatContainer WxOChatReset WxOChatStyles">
    <div style="max-height: 150px; overflow-y: auto; padding: 12px; background-color: #f4f4f4; border-radius: 8px;">
      <h3 style="margin: 0 0 8px 0;">Latest Product Updates</h3>
      <ul style="margin: 0; padding-left: 20px;">
        <li>New AI-powered search feature</li>
        <li>Enhanced security protocols</li>
        <li>Improved mobile experience</li>
        <li>Integration with third-party tools</li>
        <li>Performance optimizations</li>
        <li>Bug fixes and stability improvements</li>
      </ul>
    </div>
  </div>
`;

The following example shows how to add custom content to the AI disclaimer tooltip:

const element = instance.getWriteableElement('aiTooltipAfterDescription');
element.innerHTML = `
  <div class="WxOChatContainer WxOChatReset WxOChatStyles">
    <div style="margin-top: 12px; padding-top: 12px; border-top: 1px solid #e0e0e0; font-size: 12px;">
      <p style="margin: 0 0 8px 0; font-weight: 600;">Additional Information:</p>
      <ul style="margin: 0; padding-left: 20px; line-height: 1.5;">
        <li>AI responses are generated based on available data</li>
        <li>Always verify critical information independently</li>
        <li>For support, contact <a href="mailto:support@example.com" style="color: #0f62fe;">support@example.com</a></li>
      </ul>
    </div>
  </div>
`;

The following example demonstrates using the center chat component for a loading screen:

const element = instance.getWriteableElement('chatWelcomeComponent');
element.innerHTML = `
  <div class="WxOChatContainer WxOChatReset WxOChatStyles">
    <div style="display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; background-color: rgba(255, 255, 255, 0.95); padding: 24px;">
      <div style="width: 48px; height: 48px; border: 4px solid #e0e0e0; border-top-color: #0f62fe; border-radius: 50%; animation: spin 1s linear infinite;"></div>
      <p style="margin-top: 16px; font-size: 16px; color: #161616;">Loading your personalized experience...</p>
    </div>
    <style>
      @keyframes spin {
        to { transform: rotate(360deg); }
      }
    </style>
  </div>
`;

The following example demonstrates clearing writeable element content:

// Clear the content
const element = instance.getWriteableElement('belowHeader');
element.innerHTML = '';

Considerations

Required CSS classes for styling

To override the default chat styles, make sure your CSS selector includes the WxO container classes. For example:

.WxOChatContainer.WxOChatReset.WxOChatStyles .your-class {
  <!-- Your custom content here -->
}

This is required because the chat implements CSS reset to prevent host page styles from affecting the chat interface.

Layout support

Writeable elements are available for the following layout forms:

Floating (float)
Custom (custom)
Fullscreen (fullscreen-overlay)

Content size and layout

The chat does not impose specific size limits on writeable element content. However, large amounts of content might create undesirable layouts. Consider the following practices:

Use max-height with overflow: auto for scrollable content.
Test your content across different screen sizes.
Avoid content that significantly increases the chat height.
Consider using responsive design techniques.

// Good: Controlled height with scrolling
element.innerHTML = `
  <div class="WxOChatContainer WxOChatReset WxOChatStyles">
    <div style="max-height: 200px; overflow-y: auto;">
      <!-- Large content here -->
    </div>
  </div>
`;

Timing and initialization

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

// CORRECT: Called after chat initialization
window.watsonxOrchestrate.onLoad = function(instance) {
  const element = instance.getWriteableElement('belowHeader');
  element.innerHTML = '<div class="WxOChatContainer WxOChatReset WxOChatStyles">Content</div>';
};

// INCORRECT: Called before chat initialization
const element = wxoChat.getWriteableElement('belowHeader'); // This implementation fails

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

Do you need practical examples?

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

​Syntax

​Parameters

​Available writeable element locations

chatWelcomeComponent

aiTooltipAfterDescription

​Returns

​Examples

​Considerations

​Required CSS classes for styling

​Layout support

​Content size and layout

​Timing and initialization

Do you need practical examples?

Syntax

Parameters

Available writeable element locations

`chatWelcomeComponent`

`aiTooltipAfterDescription`

Returns

Examples

Considerations

Required CSS classes for styling

Layout support

Content size and layout

Timing and initialization