(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Chat

Overview

• The DynamicChatComponent (Chat) is an interactive chat interface for dynamic applications.
• It supports messages with type (user or bot), content, and timestamp.
• The components provide configurable bot message rating icons with tooltips, click behavior, and alternate icons.
• It uses event-driven actions for sending messages, handling content clicks, and rating icon clicks.
• The components include properties for testing and authorization configuration.

Specs

Tokens

Structure

• The component manages an array of chat messages and defines actions the user can trigger.

(Configured in General Properties)

• displayName — Sets the display name of the component, shown in the structure panel for easy identification.
• id — Specifies the unique identifier for the component. Used for referencing and programmatic access.

(Configured in Data Documentation)

• The component manages an array of chat messages, each with properties such as type (user or bot), content, and timestamp.
• Example message:

  {
    "type": "user",
    "question": "How can I reset my password?",
    "timestamp": 1697800000000
  }

[IMAGE PLACEHOLDER: High-level structure showing displayName/id and the message array]

Styling

(Configured in Visual Properties)

• botMessageRatingIcons — Configures the set of icons displayed for rating bot messages. Each icon can have its own tooltip, click behavior, and alternate icon for toggling.
  Example:

  [
    {
      "name": "thumbs-up",
      "tooltipTranslations": { "en-US": "Helpful", "de-DE": "Hilfreich" },
      "alternateIcon": "thumbs-up-filled",
      "isClickableOnce": true,
      "events": [/* ... */]
    }
  ]

• maxMessageLength — Sets the maximum number of characters allowed in a user message. Controls input length and prevents excessively long messages.
• paddingClass — Configures the padding for the chat component using CSS classes.

Actions

(Configured in Event Actions)

• events — Defines the list of event actions the component can trigger. These events allow integration with dynamic actions, such as sending messages or handling content clicks.
  Example:

  [
    { "type": "ON_SEND_MESSAGE", "actions": [/* ... */] },
    { "type": "ON_CONTENT_CLICK", "actions": [/* ... */] }
  ]
    ```
    - **ON_INIT** – Triggered when the label component is initialized. Can be used to perform setup operations like setting initial context values.
    - **ON_DESTROY** – Triggered when the label component is removed from the DOM. Useful for cleanup operations and releasing resources.
    - **ON_GLOBAL_PARAMETERS_CHANGE** – Triggered when global parameters that might affect the component change.
    - **ON_DATA_HUB_CHANGE** - Emitted whenever the Data Hub’s active context or state changes.
    - **ON_SEND_MESSAGE** — Triggered when a user sends a message. Can be used to invoke backend APIs or trigger workflows.
    - **ON_CONTENT_CLICK** — Triggered when a user clicks on content within a message. Useful for handling links or interactive elements.
    - **ON_ICON_CLICK** — Triggered when a bot message rating icon is clicked. Allows for custom feedback handling or analytics.

### Tests
*(Configured in Testing Hooks)*
- **dataTestId** — Sets the testing hook ID for automated testing. Makes it easier to select the component in end-to-end or unit tests.  
  Example: `"support-chat-component"`

### Authorization
*(Configured in Authorization)*
- **visibilityPolicySetId** — Determines the visibility of the component based on a policy set. Restricts access to certain users or roles.  
  Example: `"supportAgentsOnly"`

### Links
- Figma: tba
- Live style guide: tba

## Guidelines

### Example Configuration

json { "id": "supportChat", "displayName": "Support Chat", "botMessageRatingIcons": [ { "name": "thumbs-up", "tooltipTranslations": { "en-US": "Helpful" }, "alternateIcon": "thumbs-up-filled", "isClickableOnce": true, "events": [{ "type": "ON_ICON_CLICK", "actions": [] }] } ], "maxMessageLength": 500, "events": [ { "type": "ON_SEND_MESSAGE", "actions": [] }, { "type": "ON_CONTENT_CLICK", "actions": [] } ], "dataTestId": "support-chat-component" } ```

Guidelines

Usage

• Use Chat for conversational interactions where users submit text and receive bot responses, and you need event hooks to process them.
• Collect immediate feedback on bot replies with a small, meaningful set of rating actions.
• Prevent runaway input and keep responses snappy by limiting user message length.
• Make the component easy to target in tests and telemetry.
• Keep authoring clear in complex boards by labeling the instance.

Sizing & Layout

• Adjust in-component whitespace without external CSS.
• Keep rating affordances compact—offer only the essential icons.
• Favor stable layouts when a rating is recorded—swap icons without shifting content.

States & Feedback

• Show selection/acknowledgement after a rating is made by toggling the icon.
• Prevent multiple ratings on the same message when appropriate.
• Execute side effects (e.g., analytics, persistence) directly from rating interactions.
• Initialize and tear down cleanly.

Tooltips

• Provide clear, localized hints for each rating icon; keep microcopy short and action-oriented.
• Tooltips are supplemental only—don’t rely on them for critical information.

Interactions & Events

• Send messages through the dedicated event and attach your action chain there.
• Make message content interactive (e.g., link taps) by handling content clicks.
• React to ambient context changes that should affect the chat experience.
• Free resources/listeners when the component is removed.

Data-Driven / Conditional Behavior

• Represent “rated” vs “not rated” using visual swaps rather than color alone.
• Gate which icons are present based on current context by rebuilding the icon list when inputs change.

Visibility & Authorization

• Hide the entire chat for disallowed audiences.

Content & Localization

• Localize all rating affordance texts; keep them concise.
• Distinguish authoring labels from end-user text.

Dos & Don’ts

Accessibility

• Convey state without color reliance by swapping to an alternate icon. (botMessageRatingIcons[].alternateIcon)
• Provide localized text for rating affordances. (botMessageRatingIcons[].tooltipTranslations)
• Cap input length to reduce cognitive load and prevent overflow. (maxMessageLength)
• Avoid exposing functionality to unauthorized users. (visibilityPolicySetId)