목적

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

외부 서버(사용자 백엔드)는 이 규격에 맞춰 응답을 반환해야 합니다.

개요

<aside> 💡

API Action 설정 시, 외부 서버가 반환하는 JSON Response의 포맷입니다.

</aside>

응답 구조 (Top-level)

응답의 최상위에는 스키마 버전과 카드의 전체적인 표시 방식을 정의하는 필드가 포함되어야 합니다.

필드 타입 필수 설명
schema String 예 프로토콜 버전을 식별합니다. "sidetalk.card.v1" 고정 값을 사용하세요.
cardType String 예 템플릿의 종류입니다. ("text"
displayMode String 예 카드를 보여주는 방식입니다.
random: items 중 1개를 랜덤 노출
carousel: items 전체를 좌우 스크롤로 노출
items Array 예 실제 카드 데이터 객체들이 담긴 배열입니다.

하위 객체 명세

1. Button 객체 (공통)

모든 카드 타입에서 버튼이 필요할 때 사용하는 공통 객체입니다.

필드 타입 필수 설명
label String 예 버튼에 표시될 텍스트입니다.
action String 예 버튼 동작 타입입니다.
url: 웹 브라우저로 링크 열기
value String 예 action에 대응하는 값입니다.
(URL 주소 또는 전송할 메시지 텍스트)

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

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

A) Text Item (cardType: "text")