응답 타입별 JSON 포맷
스킬을 통해 카카오톡의 유려한 말풍선을 직접 그려내실 수도 있습니다.
빠른 한걸음을 위해 말풍선의 응답 타입별 JSON 포맷을 공유해 드리겠습니다. 여러분의 사용자 응대 시나리오에 맞게 간편하게 수정해서 쓰시면 많은 도움이 될 것입니다. 텍스트형/이미지형/카드형/커머스형/리스트형까지 말풍선을 그리기 위한 JSON 샘플 코드를 빠르게 참고해보세요!!
SkillPayload
구성
스킬 payload는 스킬 실행시 봇 시스템이 스킬 서버에게 전달하는 정보입니다. Payload는 사용자의 정보, 발화, 실행 블록, 파라미터 등의 정보를 포함합니다.
- intent
- userRequest
- bot
- action
intent
발화와 일치하는 블록의 정보를 담고 있는 필드입니다. 발화가 지식+에 일치하는 경우, 일치하는 지식의 목록을 포함합니다.
상세 필드
필드명 | 타입 | 설명 |
---|---|---|
id | String | 블록 id입니다. |
name | String | 블록명이며, 지식의 경우 "지식+"로 노출합니다. |
intent.extra.knowledges
상세 필드
필드명 | 타입 | 설명 |
---|---|---|
matchedKnowledges | Array<Knowledge> | 발화에 일치한 지식 목록입니다. |
knowledge
상세 필드
필드명 | 타입 | 설명 |
---|---|---|
answer | String | 지식의 답변입니다. |
question | String | 지식의 질문입니다. |
categories | Array<String> | QA의 카테고리입니다. |
landingUrl | String | 지식 답변에서 링크 더보기입니다. |
imageUrl | 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 |
|
utterance | string | 봇 시스템에 전달된 사용자의 발화입니다. |
lang | string |
|
user | User | 사용자의 정보입니다. |
bot
사용자의 발화를 받은 봇의 정보를 담고 있는 필드입니다.
상세 필드
필드명 | 타입 | 설명 |
---|---|---|
id | String | 봇의 고유한 식별자입니다. |
name | String | 설정된 봇의 이름입니다. |
action
실행되는 스킬의 정보를 담고있는 필드입니다. 사용자의 발화로부터 추출한 엔티티의 값을 추가적으로 포함합니다.
상세 필드
필드명 | 타입 | 설명 |
---|---|---|
id | String | 스킬의 고유한 식별자입니다. |
name | String | 설정된 스킬의 이름입니다. |
params | Map<String, String> |
|
detailParams | Map<String, DetailParam> |
|
clientExtra | Map<String, Any> |
|
예제 코드
{
"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에 담아서 제공하고 있습니다.
필드 | 타입 | 설명 |
---|---|---|
id | string |
|
type | string | 현재는 botUserKey만 제공합니다. |
properties | Object | 추가적으로 제공하는 사용자의 속성 정보입니다. |
user.properties
상세 필드
속성 | 타입 | 설명 |
---|---|---|
plusfriendUserKey | string |
|
appUserId | string |
|
isFriend | Boolean |
|
예제 코드
{
...,
"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을 포함합니다.
SkillResponse
구성
스킬 응답은 크게 version/template/context/data 총 4가지 부분으로 구성됩니다.
Version
- 스킬 응답의 version을 나타냅니다.
- <major-version>.<minor-version>의 모습을 갖습니다. 따라서 2.0, 2.1, 3.0과 같은 모습을 갖습니다.
Caution.
version이 없다면 구 버전의 응답으로 간주하기 때문에, 항상 version을 포함해야 합니다.
Template
- 스킬 응답의 출력 모양을 담고 있는 항목입니다. 출력으로 사용할 요소 그룹, 바로가기 응답 그룹 등을 포함합니다.
- 자세히 보기
- 스킬 개발 가이드 > 응답 설정을 스킬로 사용하기
Context Control
- 블록의 context 설정을 제어할 수 있습니다.
- 자세히 보기
Data
- 필요에 따라 커스텀한 데이터를 넣을 수 있는 항목입니다.
- 스킬 개발 가이드 > 응답 설정을 값으로 사용하기
필드 및 예제
상세 필드
이름 | 타입 | 필수 여부 |
---|---|---|
version | string | O |
template | SkillTemplate | 응답을 스킬데이터로 사용 체크시 필수(더 알아보기) |
context | ContextControl | X |
data | Map<String, Any> | X |
예제 코드
{
"version": "2.0",
"template": {
...
},
"context": {
...
},
"data": {
...
}
}
SkillTemplate
구성
outputs (출력 그룹)
출력 그룹(outputs)은 여러 종류의 출력 요소(component)를 포함합니다. 이를 통하여 종류가 다르거나 구분해야 할 필요가 있는 콘텐츠를 여러 출력 요소로 나눠서 표현할 수 있습니다. 출력 요소는 텍스트, 음성, 주소, 카드형 등 다양한 모습을 갖습니다.
Definition.
케로셀은 여러 개의 출력 요소를 묶어서 제공하는 형태입니다.
기본 카드형 케로셀 예제
quickReplies (바로가기 그룹)
바로가기 그룹(quickReplies)은 여러 개의 바로가기 요소(quickReply)를 포함합니다. 바로가기 응답을 이용하면, 유저는 직접 발화를 텍스트로 입력하지 않더라도 메세지를 출력하거나, 다른 블록을 호출할 수 있습니다.
이를 통해 사용자는 발화를 직접 입력해야 하는 번거로움을 줄이고, 다음 발화에 대한 힌트를 얻을 수 있습니다.
ContextControl
context control 필드는 블록에서 생성한 outputContext의 lifeSpan, params 등을 제어할 수 있습니다.
상세 필드
이름 | 타입 | 필수 여부 | 제한 |
---|---|---|---|
values | ContextValue | O |
ContextValue 상세 필드
이름 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
name | string | O | 수정하려는 output 컨텍스트의 이름 |
lifeSpan | int | O | 수정하려는 ouptut 컨텍스트의 lifeSpan |
params | Map <string, string> | X | output 컨텍스트에 저장하는 추가 데이터 |
예제 코드
{
"version": "2.0",
"context": {
"values": [
{
"name": "abc",
"lifeSpan": 10,
"ttl": 60,
"params": {
"key1": "val1",
"key2": "val2"
}
},
{
"name": "def",
"lifeSpan": 5,
"params": {
"key3": "1",
"key4": "true",
"key5": "{\"jsonKey\": \"jsonVal\"}"
}
},
{
"name": "ghi",
"lifeSpan": 0
}
]
}
}
abc
output 컨텍스트의 lifeSpan을 10, ttl을 60로, params의key1
에val1
,key2
에val2
를 추가합니다.def
name을 갖는 ContextValue의 param처럼, 다른 타입들 또한 stringify 하여 저장할 수 있습니다.ghi
name을 갖는 ContextValue처럼, lifeSpan을 0으로 바꿔서 삭제할 수 있습니다.
SimpleText
간단한 텍스트형 출력 요소입니다.
상세 필드
이름 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
text | string | O | 전달하고자 하는 텍스트입니다 | 1000자 |
- text가 500자가 넘는 경우, 500자 이후의 글자는 생략되고
전체 보기
버튼을 통해서 전체 내용을 확인할 수 있습니다.
예제 코드
{
"version": "2.0",
"template": {
"outputs": [
{
"simpleText": {
"text": "간단한 텍스트 요소입니다."
}
}
]
}
}
SimpleImage
간단한 이미지형 출력 요소입니다. 이미지 링크 주소를 포함하면 이를 스크랩하여 사용자에게 전달합니다. 이미지 링크 주소가 유효하지 않을 수 있기 때문에, 대체 텍스트를 꼭 포함해야 합니다.
상세 필드
이름 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
imageUrl | string | O | 전달하고자 하는 이미지의 url입니다 | URL 형식 |
altText | string | O | url이 유효하지 않은 경우, 전달되는 텍스트입니다 | 최대 1000자 |
예제 코드
{
"version": "2.0",
"template": {
"outputs": [
{
"simpleImage": {
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg",
"altText": "보물상자입니다"
}
}
]
}
}
TextCard
텍스트 카드형 출력 요소입니다. 텍스트 카드는 간단한 텍스트에 버튼을 추가하거나, 텍스트를 케로셀형으로 전달하고자 할 때 사용됩니다.
상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
text | string | O | 전달하고자 하는 텍스트입니다. | 최대 400자 (케로셀 128자) |
buttons | Array <Button> | X | 카드의 버튼들을 포함합니다. | 최대 3개 |
예제 코드
{
"version": "2.0",
"template": {
"outputs": [
{
"textCard": {
"text": "챗봇 관리자센터에 오신 것을 환영합니다 🙂\n\n챗봇 관리자센터로 챗봇을 제작해 보세요. \n카카오톡 채널과 연결하여, 이용자에게 챗봇 서비스를 제공할 수 있습니다.",
"buttons": [
{
"action": "webLink",
"label": "소개 보러가기",
"webLinkUrl": "https://chatbot.kakao.com/docs/getting-started-overview/"
},
{
"action": "webLink",
"label": "챗봇 만들러 가기",
"webLinkUrl": "https://chatbot.kakao.com/"
}
]
}
}
]
}
}
BasicCard
기본 카드형 출력 요소입니다. 기본 카드는 소셜, 썸네일, 프로필 등을 통해서 사진이나 글, 인물 정보 등을 공유할 수 있습니다. 기본 카드는 제목과 설명 외에 썸네일 그룹, 프로필, 버튼 그룹, 소셜 정보를 추가로 포함합니다.
상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
title | string | X | 카드의 제목입니다. | 최대 2줄 |
description | string | X | 카드에 대한 상세 설명입니다. | 최대 230자 |
thumbnail | Thumbnail | O | 카드의 상단 이미지입니다. | |
profile | Profile | X | 카드의 프로필 정보입니다. | |
social | Social | X | 카드의 소셜 정보입니다. | |
buttons | Array <Button> | X | 카드의 버튼들을 포함합니다. | 최대 3개 |
* social과 profile은 현재 미지원 상태입니다.
Information. description 필드
- 케로셀 타입에서 description은 최대 76자까지 가능합니다.
- 케로셀의 경우 2줄, 일반 카드의 경우 4줄까지 노출됩니다.
- 클라이언트에 따라서 230자, 76자보다 적게 노출될 수도 있습니다.
예제 코드
{
"version": "2.0",
"template": {
"outputs": [
{
"basicCard": {
"title": "보물상자",
"description": "보물상자 안에는 뭐가 있을까",
"thumbnail": {
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg"
},
"buttons": [
{
"action": "message",
"label": "열어보기",
"messageText": "짜잔! 우리가 찾던 보물입니다"
},
{
"action": "webLink",
"label": "구경하기",
"webLinkUrl": "https://e.kakao.com/t/hello-ryan"
}
]
}
}
]
}
}
CommerceCard
커머스 카드형 출력 요소입니다. 커머스 카드는 제품에 대한 소개, 구매 안내 등을 사용자에게 전달할 수 있습니다. 커머스 카드는 제목과 설명 외에 썸네일 그룹, 프로필, 버튼 그룹, 가격 정보를 추가로 포함합니다.
상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
title | string | X | 제품의 이름입니다. | 최대 30자 |
description | string | X | 제품에 대한 상세 설명입니다. | 최대 40자 |
price | int | O | 제품의 가격입니다. | |
currency | string | X | 제품의 가격에 대한 통화입니다. | 현재 won 만 가능 |
discount | int | X | 제품의 가격에 대한 할인할 금액입니다. | |
discountRate | int | X | 제품의 가격에 대한 할인율입니다. | |
dicountedPrice | int | X (discountRate을 쓰는 경우 필수) | 제품의 가격에 대한 할인가(할인된 가격)입니다. | |
thumbnails | Array <Thumbnail> | O | 제품에 대한 사진입니다. | 현재 1개만 가능 |
profile | Profile | X | 제품을 판매하는 프로필 정보입니다. | |
buttons | Array <Button> | X | 다양한 액션을 수행할 수 있는 버튼입니다. | 1개 이상, 3개 이하 |
Information. price, discount, discountedPrice 의 동작 방식
discountedPrice
가 존재하면price
,discount
,discountRate
과 관계 없이 무조건 해당 값이 사용자에게 노출됩니다.
- 예)
price
: 10000,discount
: 7000,discountedPrice
: 2000 인 경우, 3000 (10000 - 7000)이 아닌 2000이 사용자에게 노출- 위의 예에서
discountedPrice
가 없는 경우, 3000이 사용자에게 노출- 예)
price
: 10000,discountRate
: 70,discountedPrice
: 2000 인 경우, 3000 (10000 * 0.3)이 아닌 2000이 사용자에게 노출discountRate
은discountedPrice
를 필요로 합니다.discountedPrice
가 주어지지 않으면 사용자에게 >discountRate
을 노출하지 않습니다.discountRate
과discount
가 동시에 있는 경우,discountRate
을 우선적으로 노출합니다.
예제 코드
{
"version": "2.0",
"template": {
"outputs": [
{
"commerceCard": {
"title": "빈티지 목재 보물 상자 (Medium size)",
"description": "이 보물 상자 안에는 무엇이 들어있을까요?",
"price": 10000,
"discount": 1000,
"currency": "won",
"thumbnails": [
{
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg",
"link": {
"web": "https://store.kakaofriends.com/kr/products/1542"
}
}
],
"profile": {
"imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcT4BJ9LU4Ikr_EvZLmijfcjzQKMRCJ2bO3A8SVKNuQ78zu2KOqM",
"nickname": "라이언 스토어"
},
"buttons": [
{
"label": "구매하기",
"action": "webLink",
"webLinkUrl": "https://store.kakaofriends.com/kr/products/1542"
},
{
"label": "전화하기",
"action": "phone",
"phoneNumber": "354-86-00070"
},
{
"label": "공유하기",
"action": "share"
}
]
}
}
]
}
}
Tip.
- '전화하기' 버튼은 PC 톡에서는 보이지 않습니다.
- 모든 말풍선을 제대로 확인하기 위해서는 모바일에서 확인하길 권장합니다.
ListCard
리스트 카드형 출력 요소입니다. 리스트 카드는 표현하고자 하는 대상이 다수일 때, 이를 효과적으로 전달할 수 있습니다. 헤더와 아이템을 포함하며, 헤더는 리스트 카드의 상단에 위치합니다. 리스트 상의 아이템은 각각의 구체적인 형태를 보여주며, 제목과 썸네일, 상세 설명을 포함합니다.
상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
header | ListItem | O | 카드의 상단 항목 | |
items | Array <ListItem> | O | 카드의 각각 아이템 | 최대 5개 케로셀형 : 최대 4개 |
buttons | Array <Button> | X | 최대 2개 |
ListItem 상세 필드
필드명 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
title | string | O |
|
description | string | X |
|
imageUrl | string | X |
|
link | Link | X | 클릭시 작동하는 링크입니다. |
action | string | X | 클릭시 수행될 작업입니다.
|
blockId | string | action: block |
|
messageText | string | action: message |
|
extra | Map<String, Any> | X |
|
예제 코드
{
"version": "2.0",
"template": {
"outputs": [
{
"listCard": {
"header": {
"title": "챗봇 관리자센터를 소개합니다."
},
"items": [
{
"title": "챗봇 관리자센터",
"description": "새로운 AI의 내일과 일상의 변화",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/img_001.jpg",
"link": {
"web": "https://namu.wiki/w/%EB%9D%BC%EC%9D%B4%EC%96%B8(%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%94%84%EB%A0%8C%EC%A6%88)"
}
},
{
"title": "챗봇 관리자센터",
"description": "카카오톡 채널 챗봇 만들기",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/img_002.jpg",
"action": "block",
"blockId": "62654c249ac8ed78441532de",
"extra": {
"key1": "value1",
"key2": "value2"
}
},
{
"title": "Kakao i Voice Service",
"description": "보이스봇 / KVS 제휴 신청하기",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/img_003.jpg",
"action": "message",
"messageText": "Kakao i Voice Service",
"extra": {
"key1": "value1",
"key2": "value2"
}
}
],
"buttons": [
{
"label": "구경가기",
"action": "block",
"blockId": "62654c249ac8ed78441532de",
"extra": {
"key1": "value1",
"key2": "value2"
}
}
]
}
}
]
}
}
ItemCard
itemCard (아이템 말풍선)는 메시지 목적에 따른 유관 정보들을 (가격 정보 포함) 사용자에게 일목요연한 리스트 형태로 전달할 수 있습니다. itemCard는 아이템리스트, 제목, 설명 외에 썸네일, 프로필, 헤드, 이미지타이틀, 버튼 그룹을 추가로 포함합니다.
케로셀 형태로 itemCard를 구현하기 위해서는 Carousel 도움말을 함께 참조해주세요.
상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
thumbnail | thumbnail | X | 상단 이미지입니다. |
|
head | head | X | 헤드 정보입니다. |
|
profile | profile | X | 프로필 정보입니다. | |
imageTitle | imageTitle | X | 이미지를 동반하는 제목 및 설명 정보입니다. |
|
itemList | Array <itemList> | O | 아이템 목록 정보입니다. |
|
itemListAlignment | string | X | itemList 및 itemListAlignment 정렬 정보입니다. |
|
itemListSummary | itemListSummary | X | 아이템 가격 정보입니다. |
|
title | string | X | 타이틀 정보입니다. |
|
description | string | X | 설명 정보입니다. | |
buttons | Array <Button> | X | 다양한 액션을 수행할 수 있는 버튼 정보입니다. |
|
buttonLayout | string | X | 버튼 정렬 정보입니다. |
|
thumbnail 상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
imageUrl | string | O | 이미지의 url 정보입니다. | URL 형식 |
width | int | X | 이미지의 넓이 정보입니다. | 설정하지 않은 경우 이미지가 1:1 비율로 노출됩니다.
|
height | int | X | 이미지의 높이 정보입니다. | |
link | Link | X | 이미지 클릭 시 작동하는 link입니다. |
head 상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
title | string | O | 헤드의 타이틀 정보입니다. |
|
profile 상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
imageUrl | string | X | 프로필 이미지 정보입니다. |
|
width | int | X | 프로필 이미지의 넓이 정보입니다. |
|
height | int | X | 프로필 이미지의 높이 정보입니다. | |
title | string | O | 프로필 타이틀 정보입니다. |
|
imageTitle 상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
title | string | O | 이미지타이틀의 제목 정보입니다. |
|
description | string | X | 이미지타이틀의 설명 정보입니다. |
|
imageUrl | string | X | 이미지타이틀의 이미지 URL입니다. |
|
itemList 상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
title | string | O | 아이템 제목 정보입니다. |
|
description | string | O | 아이템 설명 정보입니다. |
|
itemListSummary 상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
title | string | O | 아이템리스트 전체에 대한 제목 정보입니다. |
|
description | string | O | 아이템리스트 전체에 대한 설명 정보입니다. |
|
유의사항
※ 도움말에서 제공하는 제한 및 유의사항을 확인 및 준수하여 말풍선을 구성해주시길 바랍니다. 이에 맞지 않게 말풍선을 사용하는 경우, 말풍선이 정상적으로 발송되지 않거나 챗봇 이용제한이 이루어질 수 있습니다.
- itemCard에서 itemList는 필수 항목입니다.
- itemCard는 Event API 광고성 메시지로 사용 가능하며, 기존 광고성 말풍선 제한사항을 동일하게 준수하는 경우 정상적으로 발송됩니다.
- itemCard 케로셀형은 최대 10개의 카드를 구성할 수 있습니다.
- itenCard 케로셀형에서는 thumbnail, head, profile, imageTitle 필드에 한해 몇몇 케로셀 카드에만 필드를 선택 적용하는 것이 불가능하며 일괄 적용해야 합니다. 다음 이미지를 참고해주세요.
- itemCard는 케로셀의 share action을 지원하지 않습니다.
예제코드
아이템 단일형 말풍선 예제
{
"version": "2.0",
"template": {
"outputs": [
{
"itemCard": {
"imageTitle": {
"title": "DOFQTK",
"description": "Boarding Number"
},
"title": "",
"description": "",
"thumbnail": {
"imageUrl": "http://dev-mk.kakao.com/dn/bot/scripts/with_barcode_blue_1x1.png",
"width": 800,
"height": 800
},
"profile": {
"title": "AA Airline",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/aaairline.jpg"
},
"itemList": [
{
"title": "Flight",
"description": "KE0605"
},
{
"title": "Boards",
"description": "8:50 AM"
},
{
"title": "Departs",
"description": "9:50 AM"
},
{
"title": "Terminal",
"description": "1"
},
{
"title": "Gate",
"description": "C24"
}
],
"itemListAlignment" : "right",
"itemListSummary": {
"title": "Total",
"description": "$4,032.54"
},
"buttons": [
{
"label": "View Boarding Pass",
"action": "webLink",
"webLinkUrl": "https://namu.wiki/w/%EB%82%98%EC%97%B0(TWICE)"
}
],
"buttonLayout" : "vertical"
}
}
]
}
}
Carousel
케로셀은 여러 장의 카드를 하나의 메세지에 일렬로 포함하는 타입입니다.
※ 하나의 케로셀 내에서는 모든 이미지를 동일 크기로 설정해야 합니다. 즉, 케로셀 내 모든 이미지가 정사각형 (1:1) 혹은 모든 이미지가 와이드형 (2:1)으로 통일되어야 합니다.
상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
type | string | O | 케로셀의 타입입니다. | basicCard 혹은 commerceCard, listCard, itemCard |
items | Array <TextCard>, Array <BasicCard>, Array <CommerceCard>, Array<ListCard>, Array<itemCard> | O | 케로셀 아이템입니다. | 최대 10개 *ListCard는 최대 5개 |
header | CarouselHeader | X | 케로셀의 커버를 제공합니다. | *TextCard 및 ListCard는 케로셀헤더를 지원하지 않습니다. |
※ 카드별 자세한 제한사항은 각 카드 설명 내 제한/ 유의사항을 확인해주세요. 제한 및 유의사항을 따르지 않는 경우, 말풍선이 정상적으로 동작하지 않을 수 있습니다.
- TextCard
- BasicCard
- CommerceCard
- ListCard
- itemCard (itemCard는 케로셀의 share action을 지원하지 않습니다.)
예제코드
기본 카드형 케로셀 예제
{
"version": "2.0",
"template": {
"outputs": [
{
"carousel": {
"type": "basicCard",
"items": [
{
"title": "보물상자",
"description": "보물상자 안에는 뭐가 있을까",
"thumbnail": {
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg"
},
"buttons": [
{
"action": "message",
"label": "열어보기",
"messageText": "짜잔! 우리가 찾던 보물입니다"
},
{
"action": "webLink",
"label": "구경하기",
"webLinkUrl": "https://e.kakao.com/t/hello-ryan"
}
]
},
{
"title": "보물상자2",
"description": "보물상자2 안에는 뭐가 있을까",
"thumbnail": {
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg"
},
"buttons": [
{
"action": "message",
"label": "열어보기",
"messageText": "짜잔! 우리가 찾던 보물입니다"
},
{
"action": "webLink",
"label": "구경하기",
"webLinkUrl": "https://e.kakao.com/t/hello-ryan"
}
]
},
{
"title": "보물상자3",
"description": "보물상자3 안에는 뭐가 있을까",
"thumbnail": {
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg"
},
"buttons": [
{
"action": "message",
"label": "열어보기",
"messageText": "짜잔! 우리가 찾던 보물입니다"
},
{
"action": "webLink",
"label": "구경하기",
"webLinkUrl": "https://e.kakao.com/t/hello-ryan"
}
]
}
]
}
}
]
}
}
리스트형 케로셀 예제
{
"version": "2.0",
"template": {
"outputs": [
{
"carousel": {
"type": "listCard",
"items": [
{
"header": {
"title": "샌드위치"
},
"items": [
{
"title": "햄치즈",
"description": "4,500원",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/02_img_01.jpg"
},
{
"title": "베이컨 아보카도",
"description": "5,500원",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/02_img_02.jpg"
},
{
"title": "에그 포테이토",
"description": "5,300원",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/02_img_03.jpg"
},
{
"title": "갈릭 베이컨 토마토",
"description": "5,800원",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/02_img_04.jpg"
}
],
"buttons": [
{
"label": "더보기",
"action": "message",
"messageText" : "샌드위치 더보기"
}
]
},
{
"header": {
"title": "커피"
},
"items": [
{
"title": "아메리카노",
"description": "1,800원",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/02_img_05.jpg"
},
{
"title": "카페라떼",
"description": "2,000원",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/02_img_06.jpg"
},
{
"title": "카페모카",
"description": "2,500원",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/02_img_07.jpg"
},
{
"title": "소이라떼",
"description": "2,200원",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/02_img_08.jpg"
}
],
"buttons": [
{
"label": "더보기",
"action": "message",
"messageText" : "커피 더보기"
}
]
}
]
}
}
],
"quickReplies": [
{
"messageText": "인기 메뉴",
"action": "message",
"label": "인기 메뉴"
},
{
"messageText": "최근 주문",
"action": "message",
"label": "최근 주문"
},
{
"messageText": "장바구니",
"action": "message",
"label": "장바구니"
}
]
}
}
아이템형 케로셀 예제
{
"version": "2.0",
"template": {
"outputs": [
{
"simpleText": {
"text": "총 2개의 예약 내역이 있습니다. 취소할 예약을 선택해 주세요."
}
},
{
"carousel": {
"type": "itemCard",
"items": [
{
"imageTitle": {
"title": "예약 완료",
"imageUrl" : "https://t1.kakaocdn.net/openbuilder/docs_image/wine.jpg"
},
"itemList": [
{
"title": "매장명",
"description": "판교 A스퀘어점"
},
{
"title": "예약 일시",
"description": "2022.12.25, 19:30"
},
{
"title" : "예약 인원",
"description" : "4명"
},
{
"title" : "예약금",
"description" : "40,000원 (결제 완료)"
}
],
"itemListAlignment": "left",
"buttons": [
{
"label": "예약 정보",
"action": "message",
"messageText" : "예약 정보"
},
{
"label": "예약 취소",
"action": "message",
"messageText": "예약 취소"
}
]
},
{
"imageTitle": {
"title": "결제 대기",
"imageUrl": "https://t1.kakaocdn.net/openbuilder/docs_image/pizza.jpg"
},
"itemList": [
{
"title": "매장명",
"description": "정자역점"
},
{
"title": "예약 일시",
"description": "2022.12.25, 19:25"
},
{
"title" : "예약 인원",
"description" : "3명"
},
{
"title" : "예약금",
"description" : "30,000원 (결제 대기)"
}
],
"itemListAlignment": "left",
"buttons": [
{
"label": "예약 취소",
"action": "message",
"messageText" : "예약 취소"
},
{
"label": "결제",
"action": "message",
"messageText": "결제"
}
]
}
]
}
}
],
"quickReplies": [
{
"messageText": "인기 메뉴",
"action": "message",
"label": "인기 메뉴"
},
{
"messageText": "최근 주문",
"action": "message",
"label": "최근 주문"
},
{
"messageText": "장바구니",
"action": "message",
"label": "장바구니"
}
]
}
}
공통
Thumbnail
필드명 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
imageUrl | string | O | 이미지의 url입니다. |
link | Link | X | 이미지 클릭시 작동하는 link입니다. |
fixedRatio | boolean | X |
※ 케로셀 내에서는 모든 이미지가 정사각형 (1:1) 혹은 모든 이미지가 와이드형 (2:1)으로 통일되어야 합니다. ※ BasicCard 또는 CommerceCard에서 true 설정 시, 버튼이 가로로 배열되며 최대 2개로 제한됩니다. |
Button
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
label | string | O | 버튼에 적히는 문구입니다. | 버튼 14자(가로배열 2개 8자) * 썸네일이 1:1이면 버튼이 가로배열 됩니다. |
action | string | O | 버튼 클릭시 수행될 작업입니다. | |
webLinkUrl | string | action: webLink | 웹 브라우저를 열고 webLinkUrl 의 주소로 이동합니다. | URL |
messageText | string | action: message or block |
| |
phoneNumber | string | action: phone | phoneNumber에 있는 번호로 전화를 겁니다. | 전화번호 |
blockId | string | action: block | blockId를 갖는 블록을 호출합니다. (바로가기 응답의 블록 연결 기능과 동일) | 존재하는 블록 id |
extra | Map<String, Any> | block 이나 message action으로 블록 호출시, 스킬 서버에 추가적으로 제공하는 정보 |
Information. action 종류
webLink
: 웹 브라우저를 열고 webLinkUrl 의 주소로 이동합니다.message
: 사용자의 발화로 messageText를 실행합니다. (바로가기 응답의 메세지 연결 기능과 동일)phone
: phoneNumber에 있는 번호로 전화를 겁니다.block
: blockId를 갖는 블록을 호출합니다. (바로가기 응답의 블록 연결 기능과 동일)
- messageText가 있다면, 해당 messageText가 사용자의 발화로 나가게 됩니다.
- messageText가 없다면, button의 label이 사용자의 발화로 나가게 됩니다.
share
: 말풍선을 다른 유저에게 공유합니다. share action은 특히 케로셀을 공유해야 하는 경우 유용합니다.itemCard는 케로셀의 share action을 지원하지 않습니다.
operator
: 상담직원 연결 기능을 제공합니다.
- 링크: 상담직원 연결 플러그인
Forwardable
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
forwardable | boolean | X | 말풍선에 전달하기 아이콘을 노출합니다. | 전달하기 아이콘을 스킬을 통해 출력하기 위해서는 말풍선이 단일형이면서 버튼이 포함되지 않은 경우에만 설정 가능합니다. |
예제 코드
{
"version": "2.0",
"template": {
"outputs": [
{
"basicCard": {
"title": "보물상자",
"description": "보물상자 안에는 뭐가 있을까",
"thumbnail": {
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg"
},
"profile": {
"imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcT4BJ9LU4Ikr_EvZLmijfcjzQKMRCJ2bO3A8SVKNuQ78zu2KOqM",
"nickname": "보물상자"
},
"forwardable": true
}
}
]
}
}
Link
필드명 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
pc | string | X | pc의 웹을 실행하는 link입니다. |
mobile | string | X | mobile의 웹을 실행하는 link입니다. |
web | string | X | 모든 기기에서 웹을 실행하는 link입니다. |
Information. 링크 우선순위 링크는 다음과 같은 우선순위를 갖습니다.
- pc: pc < web
- 모바일: mobile < web
예를 들면, pc에 대하여 링크 값이 webURL, pcURL를 가지면 위 규칙에 따라 webURL이 노출됩니다.
모바일 기기에 대하여 Link의 값이 webURL, mobileURL를 가지면 위 규칙에 따라 webURL이 노출됩니다.
CarouselHeader
상세 필드
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
title | string | O | 케로셀 헤드 제목 | 최대 2줄 (한 줄에 들어갈 수 있는 글자 수는 기기에 따라 달라집니다.) |
description | string | O | 케로셀 헤드 설명 | 최대 3줄 (한 줄에 들어갈 수 있는 글자 수는 기기에 따라 달라집니다.) |
thumbnail | Thumbnail | O | 케로셀 헤드 배경 이미지 | 현재 imageUrl 값만 지원합니다. |
예제 코드
{
"version": "2.0",
"template": {
"outputs": [
{
"carousel": {
"type": "commerceCard",
"header": {
"title": "커머스 카드\n케로셀 헤드 예제",
"description": "케로셀 헤드 예제입니다.",
"thumbnail": {
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg"
}
},
"items": [
{
"description": "따끈따끈한 보물 상자 팝니다",
"price": 10000,
"discount": 1000,
"currency": "won",
"thumbnails": [
{
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg",
"link": {
"web": "https://store.kakaofriends.com/kr/products/1542"
}
}
],
"profile": {
"imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcT4BJ9LU4Ikr_EvZLmijfcjzQKMRCJ2bO3A8SVKNuQ78zu2KOqM",
"nickname": "보물상자 팝니다"
},
"buttons": [
{
"label": "구매하기",
"action": "webLink",
"webLinkUrl": "https://store.kakaofriends.com/kr/products/1542"
},
{
"label": "전화하기",
"action": "phone",
"phoneNumber": "354-86-00070"
},
{
"label": "공유하기",
"action": "share"
}
]
},
{
"description": "따끈따끈한 보물 상자 팝니다",
"price": 10000,
"discount": 1000,
"currency": "won",
"thumbnails": [
{
"imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg",
"link": {
"web": "https://store.kakaofriends.com/kr/products/1542"
}
}
],
"profile": {
"imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcT4BJ9LU4Ikr_EvZLmijfcjzQKMRCJ2bO3A8SVKNuQ78zu2KOqM",
"nickname": "보물상자 팝니다"
},
"buttons": [
{
"label": "구매하기",
"action": "webLink",
"webLinkUrl": "https://store.kakaofriends.com/kr/products/1542"
},
{
"label": "전화하기",
"action": "phone",
"phoneNumber": "354-86-00070"
},
{
"label": "공유하기",
"action": "share"
}
]
}
]
}
}
]
}
}
Profile
필드명 | 타입 | 필수 여부 | 설명 | 제한 |
---|---|---|---|---|
nickname | string | O | 프로필 이름 | |
imageUrl | string | X | 프로필 이미지 |
TIP!
이미지 사이즈는 180px X 180px 추천합니다.
QuickReplies
바로가기 응답은 발화와 동일합니다. 대신, 사용자가 직접 발화를 입력하지 않아도 선택을 통해서 발화를 전달하거나 다른 블록을 호출할 수 있습니다.
바로가기 응답 예시
제한적 선택지를 가진 응답이거나, 다음 발화에 대한 힌트를 줄 필요가 있을 때 바로가기 응답을 사용하면 유용합니다.
종류
바로가기 응답은 현재 두 가지 기능을 제공합니다.
메시지 연결 기능
바로가기 응답에서 메시지 연결 기능은 발화를 입력하는 것과 동일합니다.
바로가기 응답(메시지 기능)을 이용한 간단한 메시지형 응답
라이언 ‘바로가기 응답’은 버튼 위에 ‘라이언’이라는 문자가 적혀있지만, 실제 클릭시 ‘라이언 알아보기’라는 발화로 대화창에 나가게 됩니다.
바로가기 응답을 이용하여 블록을 호출한 경우
바로가기 응답을 사용하지 않고 사용자가 직접 ‘라이언 알아보기’를 입력해도, 해당 발화를 인식하는 블록이 실제로 존재하기 때문에 동일한 출력이 노출됩니다.
사용자가 직접 타이핑한 발화를 이용하여 블록을 호출한 경우
봇 사용자는 바로가기 응답 ‘라이언’을 눌렀을 때, ‘라이언 알아보기’ 발화가 전송되고 연결된 블록의 출력 값이 어떻게 나오는지 경험하게 됩니다. 이를 바탕으로 앞으로 발화 ‘라이언 알아보기’를 입력 전송하면 바로가기 응답을 눌렀을 때와 동일한 응답을 받을 수 있다는 것을 예측할 수 있습니다. 그러므로 메시지 연결 기능을 가진 바로가기 응답은 사용자에게 더욱 직관적인 흐름을 제공합니다.
블록 연결 기능
두 번째는 블록 연결 기능입니다. 블록을 연결하면 사용자 측에서 나가는 발화와 상관없이 blockId로 명시된 블록을 무조건 호출하게 됩니다.
바로가기 응답(블록 연결 기능)을 이용한 간단한 메시지형 응답
블록 연결 기능도 외형은 메시지 연결과 상당히 유사합니다.
사용자가 직접 ‘반응할 수 없는 발화’를 입력하여 전송한 경우
‘라이언’이라는 바로가기 응답을 선택하면, ‘반응할 수 없는 발화’ 라는 발화가 사용자 측에서 노출됩니다. 그리고 연결한 블록이 발화와 상관없이 강제로 실행됩니다. 따라서 그 이후에 동일한 발화를 입력하더라도, ‘반응할 수 없는 발화’를 발화로 등록한 블록이 없기 때문에 폴백 블록이 실행됩니다.
Caution.
메시지 기능을 사용한 바로가기 응답의 경우, 그 흐름이 매우 직관적이라 언급했습니다. 손수 발화를 입력하지 않고, 클릭을 통해서 선택지 중 하나를 골랐다는 차이만 있기 때문입니다. 봇 사용자는 추후에도 노출 되었던 발화를 직접 입력하여 전송하여도, 같은 응답을 받을 수 있다는 보장을 받습니다.
하지만 블록 연결 기능을 사용한 바로가기 응답의 경우, 어떠한 발화가 사용자 측에 노출되어도 결국 호출되는 블록은 동일합니다. 추후에 사용자가 동일한 발화를 다시 동일하게 입력해도 해당 블록이 노출되지 않을 수 있습니다. 그렇기 때문에 바로가기 응답에서 블록 연결 기능을 사용할 때는 봇 사용자의 직관적인 흐름을 훼손하지 않도록 주의하여야 합니다.
상세 필드
바로연결 버튼의 extra 필드 하위로 원하는 파라미터를 입력하는 경우 연결된 다음 블록에서 페이로드의 client Extra로 해당 값을 확인할 수 있습니다.
다만 바로연결 버튼을 통해 입력된 발화에서 별도로 엔티티를 추출하여 파라미터로 전달하지는 않습니다.