Skip to main content

​
Overview

Display configuration transforms raw API data into rich, visual responses:
Display TypeBest For
product_cardSingle item with image, price, details
product_carouselMultiple products, recommendations
tableStructured data, comparisons
buttonsQuick actions, choices
imageSingle image display
textPlain text (default)
customCustom HTML/template

​
Configuration Structure

{
  "displayConfig": {
    "type": "product_carousel",
    "fieldMappings": {
      "title": "$.products[*].name",
      "price": "$.products[*].price",
      "image": "$.products[*].image_url",
      "url": "$.products[*].product_url"
    },
    "options": {
      "showPrice": true,
      "showImage": true,
      "showAddToCart": true
    },
    "textFallback": "Found {{count}} products for you."
  }
}

​
Field Mappings

Field mappings use JSONPath to extract data from API responses:

​
JSONPath Basics

PatternMeaning
$.fieldRoot level field
$.nested.fieldNested field
$.array[0]First array item
$.array[*].fieldField from all array items

​
Example API Response

{
  "products": [
    {
      "name": "Blue Widget",
      "price": 29.99,
      "image_url": "https://...",
      "sku": "BW-001"
    },
    {
      "name": "Red Widget",
      "price": 34.99,
      "image_url": "https://...",
      "sku": "RW-002"
    }
  ]
}

​
Mapping Configuration

{
  "fieldMappings": {
    "title": "$.products[*].name",
    "price": "$.products[*].price",
    "image": "$.products[*].image_url",
    "id": "$.products[*].sku"
  }
}

​
Display Types

​
Product Card

Single product display with image, title, price, and action button. 
{
  "displayConfig": {
    "type": "product_card",
    "fieldMappings": {
      "title": "$.product.name",
      "price": "$.product.price",
      "image": "$.product.image",
      "description": "$.product.description",
      "url": "$.product.url"
    },
    "options": {
      "showPrice": true,
      "showImage": true,
      "showAddToCart": true
    }
  }
}
Options:
OptionTypeDescription
showPricebooleanDisplay price
showImagebooleanDisplay product image
showAddToCartbooleanShow add to cart button
Multiple products in a scrollable carousel. 
{
  "displayConfig": {
    "type": "product_carousel",
    "fieldMappings": {
      "title": "$.items[*].name",
      "price": "$.items[*].price",
      "image": "$.items[*].thumbnail",
      "url": "$.items[*].link"
    },
    "options": {
      "showPrice": true,
      "showImage": true,
      "showAddToCart": false
    }
  }
}

​
Table

Structured data in rows and columns. 
{
  "displayConfig": {
    "type": "table",
    "fieldMappings": {
      "data": "$.orders"
    },
    "options": {
      "columns": [
        { "key": "order_id", "label": "Order #", "width": "20%" },
        { "key": "date", "label": "Date", "width": "25%" },
        { "key": "status", "label": "Status", "width": "25%" },
        { "key": "total", "label": "Total", "width": "30%" }
      ]
    }
  }
}
Column Properties:
PropertyTypeDescription
keystringField name in data
labelstringColumn header
widthstringColumn width (%, px)

​
Buttons

Quick action buttons. 
{
  "displayConfig": {
    "type": "buttons",
    "fieldMappings": {
      "buttons": "$.actions"
    },
    "options": {
      "buttonStyle": "primary"
    }
  }
}
Button Styles:
  • primary — Filled, prominent
  • secondary — Subtle background
  • outline — Border only

​
Image

Single image display. 
{
  "displayConfig": {
    "type": "image",
    "fieldMappings": {
      "src": "$.image_url",
      "alt": "$.image_description"
    }
  }
}

​
Custom Template

Fully custom rendering with templates. 
{
  "displayConfig": {
    "type": "custom",
    "options": {
      "template": "<div class='custom-card'><h3>{{title}}</h3><p>{{description}}</p><a href='{{url}}'>Learn more</a></div>"
    },
    "fieldMappings": {
      "title": "$.name",
      "description": "$.summary",
      "url": "$.link"
    }
  }
}

​
Text Fallback

Always provide a text fallback for:
  • Email channel responses
  • Accessibility
  • Failed display rendering
{
  "textFallback": "Here are {{count}} products matching your search: {{products}}"
}
Fallback templates can use:
  • {{count}} — Number of items
  • {{fieldName}} — Any mapped field
  • {{products}} — Formatted list of items

​
Complete Examples

{
  "name": "search_products",
  "description": "Search products when user asks about items or inventory.",
  "executionType": "http",
  "httpUrl": "https://api.store.com/products?q=${query}",
  "httpMethod": "GET",
  "displayConfig": {
    "type": "product_carousel",
    "fieldMappings": {
      "title": "$.results[*].title",
      "price": "$.results[*].price",
      "image": "$.results[*].image",
      "url": "$.results[*].url"
    },
    "options": {
      "showPrice": true,
      "showImage": true,
      "showAddToCart": true
    },
    "textFallback": "Found {{count}} products: {{title}} - ${{price}}"
  }
}

​
Order Status Table

{
  "name": "order_history",
  "description": "Show order history when user asks about past orders.",
  "executionType": "http",
  "httpUrl": "https://api.store.com/orders?email=${email}",
  "httpMethod": "GET",
  "displayConfig": {
    "type": "table",
    "fieldMappings": {
      "data": "$.orders"
    },
    "options": {
      "columns": [
        { "key": "id", "label": "Order #" },
        { "key": "date", "label": "Date" },
        { "key": "items", "label": "Items" },
        { "key": "status", "label": "Status" },
        { "key": "total", "label": "Total" }
      ]
    },
    "textFallback": "You have {{count}} orders: {{data}}"
  }
}

​
Feature Comparison

{
  "name": "compare_plans",
  "description": "Show plan comparison when user asks about pricing or features.",
  "executionType": "mock",
  "mockResponse": "{\"plans\": [{\"name\": \"Starter\", \"price\": \"$29\", \"agents\": \"1\", \"messages\": \"1,000\"}, {\"name\": \"Pro\", \"price\": \"$99\", \"agents\": \"5\", \"messages\": \"10,000\"}]}",
  "displayConfig": {
    "type": "table",
    "fieldMappings": {
      "data": "$.plans"
    },
    "options": {
      "columns": [
        { "key": "name", "label": "Plan" },
        { "key": "price", "label": "Price/mo" },
        { "key": "agents", "label": "Agents" },
        { "key": "messages", "label": "Messages" }
      ]
    }
  }
}

​
Quick Actions

{
  "name": "quick_help",
  "description": "Show help options when user needs assistance.",
  "executionType": "mock",
  "mockResponse": "{\"actions\": [{\"label\": \"Contact Support\", \"action\": \"contact\"}, {\"label\": \"View FAQs\", \"action\": \"faq\"}, {\"label\": \"Schedule Call\", \"action\": \"schedule\"}]}",
  "displayConfig": {
    "type": "buttons",
    "fieldMappings": {
      "buttons": "$.actions"
    },
    "options": {
      "buttonStyle": "primary"
    }
  }
}

​
Best Practices

​
Image Handling

  • Use HTTPS URLs for images
  • Provide fallback for broken images
  • Optimize image sizes for fast loading

​
Responsive Design

  • Display types are mobile-responsive by default
  • Carousels scroll horizontally on mobile
  • Tables may scroll on narrow screens

​
Accessibility

  • Always include textFallback
  • Use descriptive button labels
  • Ensure sufficient color contrast

​
See Also