Architecting Carousel and List Picker Rich Message Components for Dynamic Product Recommendations in Genesys Cloud CX

How-To-Articles
1

Architecting Carousel and List Picker Rich Message Components for Dynamic Product Recommendations in Genesys Cloud CX

What This Guide Covers

This guide details the implementation of dynamic Carousel and List Picker rich message components within a Genesys Cloud CX Bot to drive product recommendations. You will configure bot variables, JSON schemas, and widget bindings to render interactive product catalogs. The end result is a production-ready bot flow that fetches real-time inventory data, filters results based on user intent, and presents them in responsive UI widgets optimized for both desktop and mobile clients.

Prerequisites, Roles & Licensing

To execute this architecture, the following environment requirements must be met:

  • Licensing Tier: Genesys Cloud CX Digital Engagement license including Bot Builder. Access to Digital Engagement > Bots permissions is mandatory.
  • User Permissions: The executing user requires the Bot Author role and Content Management access to upload assets (images) to the CDN.
  • OAuth Scopes: If utilizing an external Product Information Management (PIM) system via API for dynamic fetching, the bot requires the contactcenter:write scope or a custom integration token with products.read permissions.
  • External Dependencies: A RESTful product catalog endpoint must be available with CORS headers enabled to allow requests from the Genesys Cloud Bot runtime environment. The endpoint should return JSON compliant with the schema defined in the implementation section.

The Implementation Deep-Dive

1. Designing the Dynamic Data Schema

The foundation of a high-performance recommendation bot is the data structure. Do not rely on static lists. A dynamic approach requires a standardized JSON object that maps to the Genesys Bot Variable system. This schema dictates how the frontend client renders the Carousel or List Picker.

Architectural Reasoning:
Genesys Cloud CX bots execute in a sandboxed environment where variable types are strictly enforced. Using a flat list for complex product data leads to serialization errors when passing large datasets to the UI widget. A structured object containing an array of items allows for client-side filtering and pagination logic if required.

Implementation Steps:

  1. Navigate to Digital Engagement > Bots. Select the target bot or create a new one.
  2. Open the Variables tab within the Bot Builder interface.
  3. Create a variable named productCatalog. Set the type to Object.
  4. Define the internal structure using the following JSON schema. This ensures compatibility with both Carousel and List Picker widgets.
{
    "id": "prod_12345",
    "name": "Premium Noise-Canceling Headphones",
    "price": {
        "amount": 299.00,
        "currency": "USD"
    },
    "image_url": "https://cdn.example.com/images/headphones.jpg",
    "description": "Industry-leading active noise cancellation with 30-hour battery life.",
    "category": "Audio",
    "in_stock": true,
    "sku": "NC-ANC-299"
}

The Trap:
A common misconfiguration occurs when developers nest the product array inside a variable named products but forget to define the root variable as an Object containing that array. The Bot Builder will accept the input but fail to bind it to the widget’s items property, resulting in an empty UI render. Always ensure the variable type is set to Object and the content begins with { "items": [ ... ] }.

Production-Ready Payload Example:
When initializing the bot flow or receiving data from an API, the payload must match this structure exactly:

{
  "productCatalog": {
    "items": [
      {
        "id": "prod_12345",
        "name": "Premium Noise-Canceling Headphones",
        "price": { "amount": 299.00, "currency": "USD" },
        "image_url": "https://cdn.example.com/images/headphones.jpg",
        "description": "Industry-leading active noise cancellation with 30-hour battery life.",
        "category": "Audio",
        "in_stock": true,
        "sku": "NC-ANC-299"
      },
      {
        "id": "prod_67890",
        "name": "Wireless Ergonomic Keyboard",
        "price": { "amount": 149.50, "currency": "USD" },
        "image_url": "https://cdn.example.com/images/keyboard.jpg",
        "description": "Mechanical switches with customizable RGB backlighting.",
        "category": "Peripherals",
        "in_stock": true,
        "sku": "WRG-KEY-149"
      }
    ]
  }
}

2. Configuring the Carousel Widget for High-Value Recommendations

The Carousel widget is designed for horizontal scrolling and is optimal when displaying high-value items where visual hierarchy matters more than quantity. This is best used for “Featured Products” or “Top Sellers.”

Architectural Reasoning:
Carousels consume more viewport width on desktop devices. On mobile, they require swipe gestures which can be less intuitive for users with motor impairments. Use Carousels only when the number of items is between 3 and 6. Beyond this threshold, scroll performance degrades significantly in the Genesys Digital Engagement client SDK due to rendering constraints.

Implementation Steps:

  1. In the Bot Builder Flow, add a Rich Message node.
  2. Select the Carousel widget from the available component list.
  3. Configure the binding properties:
    • Title Field: Map this to {{ productCatalog.items[0].name }}. This is static for the container title but can be dynamic based on context.
    • Items Mapping: Bind the variable productCatalog.items to the widget’s data source field.
    • Image Property: Map image_url to ensure the CDN asset loads correctly.
    • Action Button: Configure a “View Details” button bound to the SKU or ID for backend tracking.

Configuration Snippet (Bot Flow Expression):
When defining the mapping logic within the widget configuration, use the following expression pattern to ensure type safety:

{{ $var.productCatalog.items | json }}

The Trap:
Developers often attempt to bind a single object instead of an array to the Items field. The Carousel widget requires an array of objects. If you pass a single product object, the widget will not render any cards. Furthermore, ensure the image_url is HTTPS. Genesys Cloud CX enforces secure content policies; HTTP images will fail to load in production environments, leaving the user with a broken icon and zero trust in the recommendation.

Performance Implication:
Large images (over 500KB) within a Carousel will increase page load time on mobile networks. Implement image compression at the source or use a CDN that serves responsive images based on the client’s viewport size. Do not host product images directly on your internal intranet; always route through a public-facing CDN to reduce latency during the bot interaction.

3. Configuring the List Picker for Extended Catalogs

The List Picker widget presents items in a vertical scrollable list. This is superior for inventory checks, price comparisons, or when the user needs to see more than 6 options simultaneously without horizontal navigation.

Architectural Reasoning:
Vertical lists are generally more accessible and faster to scan on mobile devices compared to Carousels. However, they consume more vertical screen real estate. If the list exceeds 10 items, consider implementing a pagination mechanism or a search filter within the bot logic before rendering the List Picker. The Genesys Bot engine has limits on how many DOM elements it can render efficiently in a single message payload.

Implementation Steps:

  1. Add a Rich Message node and select the List Picker widget.
  2. Map the data source to productCatalog.items.
  3. Configure the display fields:
    • Primary Text: Product Name (name).
    • Secondary Text: Price or SKU (sku or price.amount).
    • Action: “Select” button that triggers a bot intent like ProductSelected.

Binding Logic Example:
To ensure the list filters out-of-stock items automatically, use a filter expression within the Bot Builder logic prior to rendering.

{{ productCatalog.items | filter: in_stock == true }}

The Trap:
A critical failure mode occurs when the List Picker receives null or undefined values for required fields like name or id. The bot will crash or display a generic error message to the user. Always implement a default fallback value in your JSON structure. If an item lacks a price, set it to “Call for Price” rather than leaving the field empty. This ensures the UI remains consistent and professional.

API Integration Pattern:
For real-time inventory checks, do not make API calls from the Bot flow node directly if possible. Instead, pre-fetch data during the user session initialization or cache results in a bot variable. If you must fetch live data, use the HTTP Request node with a strict timeout of 2000ms. If the request fails, revert to a static fallback catalog.

{
  "method": "GET",
  "url": "https://api.product-catalog.com/v1/items?category=Audio",
  "headers": {
    "Authorization": "Bearer {{ $var.apiToken }}"
  },
  "timeout": 2000
}

4. Handling Latency and Caching Strategies

Product recommendation bots often suffer from perceived latency if the bot waits for an API response before sending the rich message to the user. This creates a “dead air” effect that degrades user experience scores.

Architectural Reasoning:
The Genesys Cloud Bot engine processes logic synchronously. An HTTP request blocking the flow will delay the rich message delivery. To mitigate this, use a two-stage approach: send a loading indicator or text acknowledgment immediately, then push the rich message once data arrives. Alternatively, cache product data at the session level if the catalog does not change frequently (e.g., hourly).

Implementation Steps:

  1. Set up a Bot Session Variable to store the fetched product list.
  2. Configure a scheduled task or an on-demand fetch logic that populates this variable before the user interaction begins, if possible.
  3. If real-time fetching is required, execute the HTTP Request node first. Store the result in the productCatalog variable. Only proceed to the Rich Message node once the variable is populated.

The Trap:
A frequent error involves race conditions where the rich message attempts to render before the API response completes. The user will see a blank list or an error state. To prevent this, add a conditional check in the flow logic: IF productCatalog.items.length > 0 THEN Send Rich Message ELSE Send Fallback Text. Do not allow the bot to proceed without verifying the data payload exists.

Code Snippet for Conditional Logic:
In the Bot Builder logic tab, use the following expression to validate the data before rendering:

{{ $var.productCatalog.items and $var.productCatalog.items.length > 0 }}

If this evaluates to false, route the flow to a fallback node that informs the user of temporary unavailability.

5. Mobile Responsiveness and Accessibility Optimization

Genesys Cloud CX supports multiple client channels (Web Chat, Mobile App). The rendering engine behaves differently on each. A Carousel that works on desktop may be unusable on mobile if the touch target sizes are not optimized.

Architectural Reasoning:
Accessibility standards require that interactive elements have a minimum tap target size of 44x44 pixels. Genesys widgets generally adhere to this, but custom actions attached to rich messages must be explicitly defined as “Click” rather than “Hover”. Ensure all product cards include an explicit call-to-action button for mobile users who may not discover the swipe gesture immediately.

Implementation Steps:

  1. Review the widget configuration in the Designer view.
  2. Enable the Mobile Optimization toggle if available in your tenant settings.
  3. Verify that all image URLs return a responsive image format (WebP or JPEG) rather than oversized PNGs which bloat data usage on mobile networks.

The Trap:
Developers often assume that text truncation handles long product titles gracefully. On small screens, a long title can cut off mid-word without an ellipsis indicator, making the item unreadable. Always enforce a character limit in your backend data preparation or use the truncate filter in your Bot expressions to ensure consistent display across devices.

{{ productCatalog.items[0].name | truncate: 25 }}

Validation, Edge Cases & Troubleshooting

Edge Case 1: Empty Dataset Rendering

The Failure Condition: The API returns a valid JSON structure but the items array is empty ([]). The rich message widget renders an empty state.
The Root Cause: No fallback logic exists to handle zero results. The user interface displays nothing, leading to confusion about whether the bot failed or simply has no products.
The Solution: Implement a conditional branch in the Bot flow immediately after data fetching. If items.length equals zero, trigger a text message node saying “No products found matching your criteria.” Do not send the Rich Message widget if the array is empty.

Edge Case 2: Image CDN Latency Failures

The Failure Condition: The rich message loads, but images appear as broken icons or placeholders.
The Root Cause: The image URL is either expired, CORS blocked, or hosted on an insecure HTTP domain.
The Solution: Audit all image URLs against the Genesys Cloud Content Delivery Network (CDN) policies. Ensure all images are served over HTTPS and that the CDN headers allow GET requests from the *.genesyscloud.com domain. Implement a fallback mechanism where a generic product icon is used if the primary URL fails to resolve.

Edge Case 3: Variable Type Mismatch

The Failure Condition: The bot throws a runtime error when attempting to bind data to the widget.
The Root Cause: The variable type in the Bot Builder does not match the expected JSON structure. For example, defining productCatalog as an Array instead of an Object containing an items array.
The Solution: Revisit the Variable definition in the Variables tab. Ensure the root type is set to Object. Verify the inner structure matches the widget schema exactly. Use the Debug tool within the Bot Builder to inspect the variable state before sending the message.

Official References