Agent API action response format — cards
Purpose
This document defines the JSON format for showing visual cards, including text, image, and list cards, through API Action.
External servers (your backend) must return responses in this format.
Overview
Response structure (top level)
The top level must include the schema version and fields defining the overall card display mode.
| Field | Type | Required | Description |
| schema | String | Yes | Identifies the protocol version. Use the fixed value "sidetalk.card.v1". |
| cardType | String | Yes | The template type. ("text" | "image" | "list") |
| displayMode | String | Yes | How cards are displayed. random: show one random item carousel: show all items with horizontal scrolling |
| items | Array | Yes | The array containing actual card data objects. |
Nested object specifications
1. Button object (common)
A common object used whenever any card type needs buttons.
| Field | Type | Required | Description |
| label | String | Yes | Text displayed on the button. |
| action | String | Yes | The button action type. url: open a link in a web browser |
| value | String | Yes | The value corresponding to action. (A URL or message text to send) |
2. Item object (by card type)
The object structure inside items varies depending on cardType.
A) Text Item (cardType: "text")
| Field | Type | Required | Description |
| type | String | Yes | Fixed as "text" |
| title | String | No | The card title. |
| description | String | No | The card body. |
| buttons | Array | No | The bottom button list. |
B) Image Item (cardType: "image")
| Field | Type | Required | Description |
| type | String | Yes | Fixed as "image" |
| imageUrl | String | Yes | The URL of the image to display. |
| imageRatio | Number | No | An image aspect ratio hint. (Examples: 1.0, 1.333) |
| title | String | No | The title below the image. |
| description | String | No | The description below the image. |
| buttons | Array | No | The bottom button list. |
C) List Item (cardType: "list")
| Field | Type | Required | Description |
| type | String | Yes | Fixed as "list" |
| headerText | String | No | The header title at the top of the list. |
| items | Array | Yes | The list of row data. |
| buttons | Array | No | CTA buttons at the bottom of the list. |
items (rows) inside a list item
- title (String, required): row title
- description (String, optional): row description
- imageUrl (String, optional): left thumbnail URL
- linkUrl (String, optional): URL opened on click
Example responses (JSON)
1) Text + Random (single display)
JSON
{
"schema": "sidetalk.card.v1",
"cardType": "text",
"displayMode": "random",
"items": [
{
"type": "text",
"title": "상품 조회 결과",
"description": "상품명: 보물상자\n가격: 12,000원",
"buttons": [
{ "label": "상품보기", "action": "url", "value": "https://example.com/products/1542" },
{ "label": "장바구니 담기", "action": "message", "value": "보물상자 장바구니 담아줘" }
]
}
]
}2) Text + Carousel (multiple slides)
JSON
{
"schema": "sidetalk.card.v1",
"cardType": "text",
"displayMode": "carousel",
"items": [
{
"type": "text",
"title": "오늘의 요약",
"description": "주문 2건이 처리되었습니다.",
"buttons": [
{ "label": "주문내역 보기", "action": "url", "value": "https://example.com/orders" }
]
},
{
"type": "text",
"title": "배송 안내",
"description": "내일(화) 도착 예정입니다.",
"buttons": [
{ "label": "배송조회", "action": "url", "value": "https://example.com/track/ABC123" }
]
}
]
}3) Image + Random
JSON
{
"schema": "sidetalk.card.v1",
"cardType": "image",
"displayMode": "random",
"items": [
{
"type": "image",
"title": "보물상자 A",
"description": "따끈따끈한 보물 상자",
"imageUrl": "https://example.com/images/treasure-a.jpg",
"imageRatio": 2,
"buttons": [
{ "label": "구매하기", "action": "url", "value": "https://example.com/buy/treasure-a" },
{ "label": "상세보기", "action": "url", "value": "https://example.com/products/treasure-a" }
]
}
]
}4) Image + Carousel
JSON
{
"schema": "sidetalk.card.v1",
"cardType": "image",
"displayMode": "carousel",
"items": [
{
"type": "image",
"title": "보물상자 A",
"description": "가격: 12,000원",
"imageUrl": "https://example.com/images/a.jpg",
"imageRatio": 1.7777778,
"buttons": [
{ "label": "상세보기", "action": "url", "value": "https://example.com/products/a" }
]
},
{
"type": "image",
"title": "보물상자 B",
"description": "가격: 15,000원",
"imageUrl": "https://example.com/images/b.jpg",
"imageRatio": 1.7777778,
"buttons": [
{ "label": "상세보기", "action": "url", "value": "https://example.com/products/b" }
]
}
]
}5) List + Random
JSON
{
"schema": "sidetalk.card.v1",
"cardType": "list",
"displayMode": "random",
"items": [
{
"type": "list",
"headerText": "추천 상품",
"items": [
{
"title": "보물상자 A",
"description": "가격: 12,000원",
"imageUrl": "https://example.com/thumbs/a.jpg",
"linkUrl": "https://example.com/products/a"
},
{
"title": "보물상자 B",
"description": "가격: 15,000원",
"imageUrl": "https://example.com/thumbs/b.jpg",
"linkUrl": "https://example.com/products/b"
}
],
"buttons": [
{ "label": "전체보기", "action": "url", "value": "https://example.com/products" }
]
}
]
}6) List + Carousel (sliding list groups)
JSON
{
"schema": "sidetalk.card.v1",
"cardType": "list",
"displayMode": "carousel",
"items": [
{
"type": "list",
"headerText": "추천 상품 TOP 2",
"items": [
{
"title": "보물상자 A",
"description": "가격: 12,000원",
"imageUrl": "https://example.com/thumbs/a.jpg",
"linkUrl": "https://example.com/products/a"
},
{
"title": "보물상자 B",
"description": "가격: 15,000원",
"imageUrl": "https://example.com/thumbs/b.jpg",
"linkUrl": "https://example.com/products/b"
}
],
"buttons": [
{ "label": "전체보기", "action": "url", "value": "https://example.com/products" }
]
},
{
"type": "list",
"headerText": "최근 본 상품",
"items": [
{
"title": "보물상자 C",
"description": "가격: 18,000원",
"imageUrl": "https://example.com/thumbs/c.jpg",
"linkUrl": "https://example.com/products/c"
},
{
"title": "보물상자 D",
"description": "가격: 22,000원",
"imageUrl": "https://example.com/thumbs/d.jpg",
"linkUrl": "https://example.com/products/d"
}
],
"buttons": [
{ "label": "더 찾아보기", "action": "message", "value": "다른 상품도 추천해줘" }
]
}
]
}