Sidetalk사용자 가이드
사이드톡 홈페이지 ↗대시보드 열기
가이드 홈사용자 가이드

에이전트 API 액션 응답 포맷 - 카드 형태

5 분 읽기가이드 기준일: 2026. 10. 14.노션 원문 보기 ↗

목적

이 문서는 API Action 기능을 통해 챗봇이 사용자에게 시각적인 카드(텍스트, 이미지, 리스트 등)를 응답으로 보여주기 위한 JSON 규격을 정의합니다.
외부 서버(사용자 백엔드)는 이 규격에 맞춰 응답을 반환해야 합니다.

개요



응답 구조 (Top-level)

응답의 최상위에는 스키마 버전과 카드의 전체적인 표시 방식을 정의하는 필드가 포함되어야 합니다.
필드타입필수설명
schemaString예프로토콜 버전을 식별합니다. "sidetalk.card.v1" 고정 값을 사용하세요.
cardTypeString예템플릿의 종류입니다. ("text" | "image" | "list")
displayModeString예카드를 보여주는 방식입니다. random: items 중 1개를 랜덤 노출 carousel: items 전체를 좌우 스크롤로 노출
itemsArray예실제 카드 데이터 객체들이 담긴 배열입니다.

하위 객체 명세

1. Button 객체 (공통)

모든 카드 타입에서 버튼이 필요할 때 사용하는 공통 객체입니다.
필드타입필수설명
labelString예버튼에 표시될 텍스트입니다.
actionString예버튼 동작 타입입니다. url: 웹 브라우저로 링크 열기
valueString예action에 대응하는 값입니다. (URL 주소 또는 전송할 메시지 텍스트)

2. Item 객체 (카드 타입별)

cardType에 따라 items 배열 안에 들어갈 객체의 구조가 달라집니다.

A) Text Item (cardType: "text")
필드타입필수설명
typeString예"text" 고정
titleString아니오카드의 제목입니다.
descriptionString아니오카드의 본문 내용입니다.
buttonsArray아니오하단 버튼 목록입니다.

B) Image Item (cardType: "image")
필드타입필수설명
typeString예"image" 고정
imageUrlString예표시할 이미지의 URL입니다.
imageRatioNumber아니오이미지 비율 힌트입니다. (예: 1.0, 1.333)
titleString아니오이미지 하단 제목입니다.
descriptionString아니오이미지 하단 설명입니다.
buttonsArray아니오하단 버튼 목록입니다.

C) List Item (cardType: "list")
필드타입필수설명
typeString예"list" 고정
headerTextString아니오리스트 상단 헤더 타이틀입니다.
itemsArray예리스트의 행(Row) 데이터 목록입니다.
buttonsArray아니오리스트 최하단 CTA 버튼 목록입니다.
List Item 내부의 items (Row) 구조
  • title (String, 필수): 행 제목
  • description (String, 선택): 행 설명
  • imageUrl (String, 선택): 좌측 썸네일 URL
  • linkUrl (String, 선택): 클릭 시 이동할 URL

응답 예시 (JSON)


1) 텍스트 + Random (단일 표시)

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) 텍스트 + Carousel (여러 장 슬라이드)

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) 이미지 + 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) 이미지 + 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) 리스트 + 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) 리스트 + Carousel (리스트 묶음 슬라이드)

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": "다른 상품도 추천해줘" }
      ]
    }
  ]
}