응답 타입별 JSON 포맷

Last updated 1 month ago

스킬을 통해 카카오톡의 유려한 말풍선을 직접 그려내실 수도 있습니다.

빠른 한걸음을 위해 말풍선의 응답 타입별 JSON 포맷을 공유해 드리겠습니다. 여러분의 사용자 응대 시나리오에 맞게 간편하게 수정해서 쓰시면 많은 도움이 될 것입니다. 텍스트형/이미지형/카드형/커머스형/리스트형까지 말풍선을 그리기 위한 JSON 샘플 코드를 빠르게 참고해보세요!

SkillPayload

구성

스킬 payload는 스킬 실행시 봇 시스템이 스킬 서버에게 전달하는 정보입니다. payload는 사용자의 정보, 발화, 실행 블록, 파라미터 등의 정보를 포함합니다.

intent
userRequest
bot
action
flow

intent

발화와 일치하는 블록의 정보를 담고 있는 필드입니다. 발화가 지식+에 일치하는 경우, 일치하는 지식의 목록을 포함합니다.

상세 필드

필드명

타입

설명

String

블록 id입니다.

name

String

블록명이며, 지식의 경우 “지식+”로 노출합니다.

intent.extra.knowledges

상세 필드

필드명

타입

설명

matchedKnowledges

Array<Knowledges>

발화에 일치한 지식 목록입니다.

knowledge

상세 필드

필드명

타입

설명

answer

String

지식의 답변입니다.

question

String

지식의 질문입니다.

예제 코드

{
    "bot": {
        "id": "<봇 id>",
        "name": "<봇 이름>"
    },
    "intent": {
        "id": "<블록 id>",
        "name": "지식+",
        "extra": {
            "reason": {
                "code": 1,
                "message": "OK"
            },
            "knowledge": {
                "responseType": "skill",
                "matchedKnowledges": [
                    {
                        "categories": [
                            "<카테고리 1>",
                            "<카테고리 2>",
                            "<카테고리 3>",
                            "<카테고리 4>"
                        ],
                        "question": "<질문>",
                        "answer": "<답변>",
                        "imageUrl": "<이미지 url>",
                        "landingUrl": "<랜딩 url>"
                    },
                    {
                        "categories": [
                            "<카테고리 1>",
                            "<카테고리 2>",
                            "<카테고리 3>",
                            "<카테고리 4>"
                        ],
                        "question": "<질문>",
                        "answer": "<답변>",
                        "imageUrl": "<이미지 url>",
                        "landingUrl": "<랜딩 url>"
                    }
                ]
            }
        }
    },
    "action": {
        "id": "<액션 id>",
        "name": "<액션 이름>",
        "params": {},
        "detailParams": {},
        "clientExtra": {}
    },
    "userRequest": {
        "block": {
            "id": "<블록 id>",
            "name": "<블록 이름>"
        },
        "user": {
            "id": "<사용자 botUserKey>",
            "type": "botUserKey",
            "properties": {
                "botUserKey": "<사용자 botUserKey>"
            }
        },
        "utterance": "<사용자 발화>",
        "params": {
            "surface": "BuilderBotTest",
            "ignoreMe": "true"
        },
        "lang": "ko",
        "timezone": "Asia/Seoul"
    },
    "contexts": []
}

userRequest

사용자의 정보를 담고 있는 필드입니다. 사용자의 발화와 반응한 블록의 정보를 추가적으로 포함합니다.

상세 필드

필드명

타입

설명

timezone

string

사용자의 시간대를 반환합니다.한국에서 보낸 요청이라면 “Asia/Seoul”를 갖습니다.

block

Block

사용자의 발화에 반응한 블록의 정보입니다.

블록의 id와 name을 포함합니다.

utterance

string

봇 시스템에 전달된 사용자의 발화입니다.

lang

string

사용자의 언어를 반화합니다.

한국에서 보낸 요청이라면 “ko”를 갖습니다.

user

User

사용자의 정보입니다.

bot

사용자의 발화를 받은 봇의 정보를 담고 있는 필드입니다.

상세 필드

필드명

타입

설명

String

봇의 고유한 식별자입니다.

name

String

설정된 봇의 이름입니다.

action

실행되는 스킬의 정보를 담고있는 필드입니다. 사용자의 발화로부터 추출한 엔티티의 값을 추가적으로 포함합니다.

상세 필드

필드명

타입

설명

String

스킬의 고유한 식별자입니다.

name

String

설정된 스킬의 이름입니다.

params

Map<String, String>

사용자의 발화로부터 추출한 파라미터 정보입니다.

엔티티의 이름을 키로, 추출한 정보를 상세 값으로 가집니다.

detailParams

Map<String, DetailParam>

사용자의 발화로부터 추출한 엔티티의 상세 정보입니다.
params 필드와 유사하지만, params에서 제공하지 않은 추가적인 정보들을 제공합니다.

clientExtra

Map<String, Any>

사용자의 발화가 추가적인 정보를 제공하는 경우가 있습니다 (예. 바로가기 응답)
그 값들이 clientExtra 필드를 통해서 스킬 서버에 전달됩니다.

예제 코드

{
 "userRequest": {
    "timezone": "Asia/Seoul",
    "params": {},
    "block": {
      "id": "<블록 id>",
      "name": "<블록 이름>"
    },
    "utterance": "<사용자 발화>",
    "lang": "ko",
    "user": {
      "id": "<사용자 botUserKey>",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "<카카오톡 채널 사용자 id>"
      }
    }
  },
  "contexts": [],
  "bot": {
    "id": "<봇 id>",
    "name": "<봇 이름>"
  },
  "action": {
    "name": "<스킬 이름>",
    "clientExtra": null,
    "params": {},
    "id": "<스킬 id>",
    "detailParams": {}
  }
}

user

상세 필드

Skill Request에서 사용자에 대한 정보를 userRequest.user에 담아서 제공하고 있습니다.

필드

타입

설명

string

사용자를 식별할 수 있는 key로 최대 70자의 값을 가지고 있습니다.
이 값은 특정한 bot에서 사용자를 식별할 때 사용할 수 있습니다.
동일한 사용자더라도, 봇이 다르면 다른 id가 발급됩니다.

type

string

현재는 botUserKey만 제공합니다.

properties

Object

추가적으로 제공하는 사용자의 속성 정보입니다.

user.properties

상세 필드

속성

타입

설명

plusfriendUserKey

string

카카오톡 채널에서 제공하는 사용자 식별키 입니다.
모든 사용자에게 제공되는 값으로, botUserKey와 마찬가지로 봇에서 사용자를 식별하는데 사용할 수 있습니다.

appUserId

string

봇 설정에서 앱키를 설정한 경우에만 제공되는 사용자 정보입니다.
앱키를 설정하기 위해서는 카카오 디벨로퍼스 사이트에서 앱을 생성해야 합니다.
앱 키가 정상적으로 등록된 경우, 카카오 로그인으로 받는 사용자 식별자와 동일한 값을 얻을 수 있습니다.

isFriend

Boolean

사용자가 봇과 연결된 카카오톡 채널을 추가한 경우 제공되는 식별키입니다.
채널을 추가한 경우만 True 값이 전달되며, 채널을 추가하지 않은 경우/차단한 경우에는 값이 전달되지 않습니다.

예제 코드

{
  ...,
  "userRequest": {
    ...
    "user": {
      "id": "<사용자 botUserKey>",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "<카카오톡 채널 사용자 id>",
        "appUserId": "<app user id>",
        "isFriend" : true
      }
    }
  },
  ...
}

DetailParams

블록의 발화에서 설정한 파라미터를 추출하면 추출값 뿐만 아니라 추가적인 정보를 얻을 수 있습니다. 그 예로, 요일을 sys.date 라는 시스템 엔티티로 추출하면 단순히 ‘금요일’ 이라는 요일 뿐만 아니라 구체적인 날짜까지 포함합니다.

파라미터 등록 예제

‘1 금요일 강남’ 이라는 발화를 사용하면 실제로 아래의 params, detailParams 값이 스킬 서버로 전달됩니다.

{
  ...,
  "action": {
    "name": "예제 스킬",
    "id": "...",
    "params": {
      "sys_date": "{\"dateTag\": \"Friday\", \"dateHeadword\": null, \"year\": null, \"month\": null, \"day\": null, \"date\": \"2023-03-31\", \"polynomial\": \"define_weekday({4})\", \"calendar_type\": \"solar\"}",
      "sys_location": "강남",
      "sys_number": "{\"amount\": 1, \"unit\": null}"
    },
    "detailParams": {
      "sys_date": {
        "origin": "금요일",
        "value": "{\"dateTag\": \"Friday\", \"dateHeadword\": null, \"year\": null, \"month\": null, \"day\": null, \"date\": \"2023-03-31\", \"polynomial\": \"define_weekday({4})\", \"calendar_type\": \"solar\"}",
        "groupName": ""
      },
      "sys_location": {
        "origin": "강남",
        "value": "강남",
        "groupName": ""
      },
      "sys_number": {
        "origin": "1",
        "value": "{\"amount\": 1, \"unit\": null}",
        "groupName": ""
      }
    }
  }
}

params은 봇 시스템에서 분석하여 추가적인 정보를 채운 값입니다. detailParams는 봇 시스템에서 분석한 값 뿐만 아니라, 원래 발화에 담겨 있었던 origin을 포함합니다.

flow

사용자와 챗봇의 대화 흐름을 담고 있는 필드로 trigger와 lastBlock으로 구성됩니다. 이 필드는 사용자 발화를 발생시킨 트리거 정보와 직전에 실행된 블록 정보를 포함합니다.

상세 필드

필드명

타입

설명

trigger

Trigger

사용자 발화를 생성시킨 트리거 정보를 담고 있습니다.
발화 입력, 버튼 클릭 등을 구분할 수 있는 Trigger Type과 사용자가 상호작용한 블록 정보가 포함됩니다.

lastBlock

Block

직전에 실행된 블록 정보로 id와 name을 포함합니다.

flow.trigger

사용자 발화를 발생시킨 트리거 정보입니다. type은 블록 호출 유형을 나타내며 referrerBlock은 사용자가 상호작용한 블록의 정보를 포함합니다.

상세 필드

필드명

타입

설명

type

String

사용자 발화를 발생시킨 Trigger Type에 대한 정보입니다.

referrerBlock

Block

사용자 발화가 발생할 때 상호작용이 일어난 블록의 정보로 해당 블록의 id와 name을 포함합니다.

Trigger Type 유형

trigger.type 값은 Output Type과 Action Type의 조합으로 이루어지며 각 상황에 맞는 Trigger Type은 다음과 같습니다.

상세 필드

구분

Trigger Type

Output Type

Action Type

발화 입력

TEXT_INPUT

INPUT

TEXT

일반카드의 버튼-메시지 전송

CARD_BUTTON_MESSAGE

CARD_BUTTON

MESSAGE

일반카드의 버튼-블록 연결

CARD_BUTTON_BLOCK

CARD_BUTTON

BLOCK

리스트 카드의 버튼-메시지

전송

LIST_ITEM_MESSAGE

LIST_ITEM

MESSAGE

리스트 카드의 버튼-블록 연결

LIST_ITEM_BLOCK

LIST_ITEM

BLOCK

리스트 메뉴의 버튼-메시지 전송

LISTMENU_MESSAGE

LISTMENU

MESSAGE

리스트 메뉴의 버튼-블록 연결

LISTMENU_BLOCK

LISTMENU

BLOCK

바로연결의 버튼-블록 연결

QUICKREPLY_BUTTON_MESSAGE

QUICKREPLY

MESSAGE

바로연결의 버튼-메시지 전송

QUICKREPLY_BUTTON_BLOCK

QUICKREPLY

BLOCK

예제 코드

{
    ...,
    "flow": {
        "trigger": {
            "type": "<Trigger Type>",
            "referrerBlock": {
                "id": "<참조 블록 ID>",
                "name": "<참조 블록 이름>"
            }
        },
        "lastBlock": {
            "id": "<이전 블록 ID>",
            "name": "<이전 블록 이름>"
        }
    }
}

SkillResponse

구성

스킬 응답은 크게 version/template/context/data 총 4가지 부분으로 구성됩니다.

Version

스킬 응답의 version을 나타냅니다. <major-version>.<minor-version>의 모습을 갖습니다.
현재 스킬 응답의 version은 2.0만 지원됩니다.

Caution.

version이 없다면 구 버전의 응답으로 간주하기 때문에, 항상 version을 포함해야 합니다.

Template

스킬 응답의 출력 모양을 담고 있는 항목입니다. 출력으로 사용할 요소 그룹, 바로가기 응답 그룹 등을 포함합니다.
자세히 보기
스킬 개발 가이드 > 응답 설정을 스킬로 사용하기

Context Control

블록의 context 설정을 제어할 수 있습니다.
자세히 보기

Data

필요에 따라 커스텀한 데이터를 넣을 수 있는 항목입니다.
스킬 개발 가이드 > 응답 설정을 값으로 사용하기

필드 및 예제

상세 필드

이름

타입

필수 여부

version

string

template

SkillTemplate

context

ContextControl

data

Map<String, Any>

예제 코드

{
  "version": "2.0",
  "template": {
    ...
  },
  "context": {
    ...
  },
  "data": {
    ...
  }
}

SkillTemplate

구성

이름

타입

필수 여부

제한

outputs

Array<Component>

1개 이상 3개 이하

quickReplies

Array<QuickReply>

10개 이하

outputs(출력 그룹)

출력 그룹(outputs)은 여러 종류의 출력 요소(component)를 포함합니다. 이를 통하여 종류가 다르거나 구분해야 할 필요가 있는 콘텐츠를 여러 출력 요소로 나눠서 표현할 수 있습니다. 출력 요소는 텍스트, 음성, 주소, 카드형 등 다양한 모습을 갖습니다.

이름

설명

*캐로셀 가능 여부

simpleText

간단 텍스트

simpleImage

간단 이미지

basicCard

기본 카드

commerceCard

커머스 카드

listCard

리스트 카드

Definition.

케로셀은 여러 개의 출력 요소를 묶어서 제공하는 형태입니다.

quickReplies(바로가기 그룹)

바로가기 그룹(quickReplies)은 여러 개의 바로가기 요소(quickReply)를 포함합니다. 바로가기 응답을 이용하면, 유저는 직접 발화를 텍스트로 입력하지 않더라도 메세지를 출력하거나, 다른 블록을 호출할 수 있습니다.

이를 통해 사용자는 발화를 직접 입력해야 하는 번거로움을 줄이고, 다음 발화에 대한 힌트를 얻을 수 있습니다.

ContextControl

context control 필드는 블록에서 생성한 outputContext의 lifeSpan, params 등을 제어할 수 있습니다.

상세 필드

이름

타입

필수 여부

제한

values

ContextValue

ContextValue 상세 필드

이름

타입

필수 여부

설명

name

string

수정하려는 output 컨텍스트의 이름

lifeSpan

int

수정하려는 ouptut 컨텍스트의 lifeSpan

params

Map <string, string>

output 컨텍스트에 저장하는 추가 데이터

예제 코드

{
  "version": "2.0",
  "context": {