이 문서는 API Action 기능을 통해 챗봇이 외부 서버로부터 답변에 필요한 구조화된 데이터를 응답으로 받기 위한 JSON 권장 규격을 정의합니다.
외부 서버(사용자 백엔드)는 기존처럼 자유로운 JSON 응답을 반환할 수도 있으며, 반드시 이 규격을 따라야 하는 것은 아닙니다.
다만, 외부 서버가 이 문서의 규격에 맞춰 응답을 반환하면 챗봇이 응답 내용을 더 안정적으로 이해할 수 있어, 답변 정확도와 응답 품질 향상에 도움이 됩니다.
이 규격은 시각적인 카드 표시용(sidetalk.card.v1)이 아닌, 챗봇이 API 응답을 이해하고 자연어 답변을 생성하기 위한 일반 API 결과 포맷입니다.
<aside> 💡
API Action 설정 시, 외부 서버가 반환하는 JSON Response의 포맷입니다.
이 응답은 카드 UI로 직접 표시되지 않으며, 챗봇이 내용을 해석하여 사용자에게 답변을 생성할 때 사용됩니다.
</aside>
응답의 최상위에는 스키마 버전, 성공 여부, 실제 데이터가 포함되어야 합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| schema | String | 예 | 프로토콜 버전을 식별합니다. "sidetalk.api-result.v1" 고정 값을 사용하세요. |
| success | Boolean | 예 | 요청 처리 성공 여부입니다. |
| data | Object | 조건부 | 성공 응답일 때 포함하는 실제 데이터입니다. |
| summary | String | 아니오 | 응답 내용을 한 줄로 요약한 텍스트입니다. 필수는 아니지만, 챗봇이 내용을 더 빠르게 이해하는 데 도움이 됩니다. |
| error | Object | 조건부 | 실패 응답일 때 포함하는 오류 정보입니다. |
| meta | Object | 아니오 | 출처, 페이지 정보, 상태코드 등 부가 정보를 담습니다. |
이 규격은 권장 구조이며, 자유로운 JSON 응답도 사용할 수 있습니다.
다만, 챗봇이 응답을 더 안정적으로 이해할 수 있도록 가능하면 아래 구조를 따르는 것을 권장합니다.
data 내부 구조는 API의 목적에 맞게 자유롭게 설계할 수 있습니다.schema, success 필드를 포함하는 것을 권장합니다.success: true 인 경우 data 필드를 포함하는 것을 권장합니다.success: false 인 경우 error 필드를 포함하는 것을 권장합니다.