Chat UI Components

This guide provides a structured overview of Chat UI Generic Components and how they fit into the Workflow Response Node Schema. It covers card-list, card-detail, button-group, dropdown, and files components with proper schemas, examples, and best practices.

Workflow Response Node Schema

Every response follows a common schema:

{
  "component": {
    "type": "card-detail | card-list | button-group | dropdown | files | ...",
    "data": {
      "items": [],         // in case of card-list
      "pagination": {},    // in case of card-list
      "detail": {}         // in case of card-detail
    }
  },
  "summary": {
    // A simple summary of the action performed
  },
  "lazySummary": {
    // Optional: detailed description for further actions
  }
}

Schema Note

summary is always required for quick readability.
lazySummary is optional but recommended when future actions depend on detailed context.
component.type determines how the data is rendered inside the chat UI.

Card List

Use this to display multiple products/items in a scrollable list.

{
  "component": {
    "type": "card-list",
    "data": {
      "items": [
        {
          "title": "<string>",        // product name
          "description": "<string>",  // product description
          "images": ["<url>"],        // array of product image URLs
          "highlight": "<string>",    // selling price
          "badge": "<string>",        // brand name
          "actions": [
            {
              "text": "<string>",
              "icon": "<string>",
              "instructions": [{
                "type": "quick_reply | navigate",
                "options": { "value": "<>" }
              }]
            }
          ]
        }
      ],
      "pagination": {
        "pageNo": 1,
        "pageSize": 20,
        "totalItems": 100,
        "hasNext": true
      }
    }
  },
  "summary": {
    "message": "Showing product list"
  }
}

When to Use

Choose card-list when you want to present multiple options or products in one view, usually with pagination for longer lists.

Card Detail

Use this to show detailed information about a single product/item.

{
  "component": {
    "type": "card-detail",
    "data": {
      "badge": "Bombay Begum",
      "title": "Men Regular Fit Spread Collar Shirt",
      "images": [
        "https://cdn.fynd.com/.../shirt1.jpg",
        "https://cdn.fynd.com/.../shirt2.jpg",
        "https://cdn.fynd.com/.../shirt3.jpg",
        "https://cdn.fynd.com/.../shirt4.jpg"
      ],
      "highlight": "Rs. 434",
      "categories": ["Men's Shirts", "Linen", "Regular Fit"],
      "description": "Off-White, Regular Fit, Spread Collar, Linen, Full-Length. Package contains 1 shirt. Machine wash cold. Recommended: buy one size smaller.",
      "actions": [
        {
          "icon": "Info",
          "text": "Show Similar",
          "instructions": [{
            "type": "quick_reply",
            "options": {
              "value": "Show similar shirts to bombay-begum-regular-fit-offwhite"
            }
          }]
        },
        {
          "icon": "redirect",
          "text": "View",
          "instructions": [{
            "type": "navigate",
            "options": {
              "value": "https://fynd.hostx5.de/product/bombay-begum-regular-fit-offwhite-shirt"
            }
          }]
        }
      ]
    }
  },
  "summary": {
    "message": "Showing detailed product info"
  }
}

Best Fit

Use card-detail when the user needs deep context on a single product/item, e.g., description, price, categories, and actions.

Button Group

Use this for multiple action buttons in a compact layout.

{
  "type": "button-group",
  "data": {
    "title": "Choose an action",
    "actions": [
      {
        "text": "Click to checkout",
        "icon": "quickreply",
        "variant": "primary | secondary",   // default: secondary
        "size": "large | medium | small",   // default: small
        "instructions": [{
          "type": "quick_reply",
          "options": {
            "message": "Add to my cart",
            "value": "Add xyz to my cart"
          }
        }]
      },
      {
        "text": "View Cart",
        "icon": "redirect",
        "instructions": [{
          "type": "navigate",
          "options": {
            "value": "https://www.tirabeauty.com/cart/bag"
          }
        }]
      }
    ]
  }
}

UX Tip

Use primary for the most important action (e.g., Checkout), and secondary for less critical actions (e.g., View Cart).

Use for selection-based inputs (single or multiple). Supports dynamic templating using and .

{
  "type": "dropdown",
  "data": {
    "title": "Book Appointment",
    "subtitle": "Schedule your free consultation today!",
    "defaultOption": "",     // optional, value from options
    "multiple": false,       // allow multiple selections
    "placeholder": "",       // optional
    "submitOnClick": false,  // if true, auto-submit selected value(s)
    "options": [
      {
        "label": "9:00 AM - 10:00 AM",
        "value": "9-10",
        "icon": "https://cdn.fynd.com/.../clock.png"
      },
      {
        "label": "10:00 AM - 11:00 AM",
        "value": "10-11"
      }
    ],
    "actions": [
      {
        "text": "Confirm",
        "icon": "quickreply",
        "instructions": [{
          "type": "quick_reply",
          "options": {
            "message": "Book appointment for ",
            "value": "Book appointment at "
          }
        }]
      }
    ]
  }
}

Dynamic Variables

→ selected option label(s)
→ selected option value(s) If multiple selections are allowed, values are appended automatically.

Validation

Ensure value fields are unique identifiers (e.g., "9-10") and not user-facing text.

Files

Use to send images or PDFs.

{
  "_agent_components": [{
    "type": "files",
    "data": [
      {
        "url": "https://cdn.fynd.com/product.jpg",
        "name": "Product Image",
        "type": "image | pdf"
      }
    ]
  }]
}

Supported Types

Currently, only image and pdf types are supported. Other file types will not render correctly.

Conclusion

This guide equips you with the knowledge to confidently design and render interactive chat UI components, including card-list, card-detail, button-group, dropdown, and files. By following the schema and adhering to best practices, you ensure a consistent, reliable, and professional user experience across all interactions.

If you require further clarification or encounter any difficulties, please contact us at support@kaily.ai.

Workflow Response Node Schema​

Card List​

Card Detail​

Button Group​

Dropdown​

Files​

Conclusion​