카카오비즈니스 비즈니스관리자

응답 타입별 JSON 포맷

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

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

SkillPayload

구성

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

  • intent

  • userRequest

  • bot

  • action

intent

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

상세 필드

필드명타입설명

id

String

블록 id입니다.

name

String

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

intent.extra.knowledges

상세 필드

필드명타입설명

matchedKnowledges

Array<Knowledges>

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

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

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

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

utterance

string

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

lang

string

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

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

user

User

사용자의 정보입니다.

bot

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

상세 필드

필드명타입설명

id

String

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

name

String

설정된 봇의 이름입니다.

action

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

상세 필드

필드명타입설명

id

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에 담아서 제공하고 있습니다.

필드타입설명

id

string

  • 사용자를 식별할 수 있는 key로 최대 70자의 값을 가지고 있습니다.

  • 이 값은 특정한 bot에서 사용자를 식별할 때 사용할 수 있습니다.

  • 동일한 사용자더라도, 봇이 다르면 다른 id가 발급됩니다.

type

string

현재는 botUserKey만 제공합니다.

properties

Object

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

user.properties

상세 필드

속성타입설명

plusfriendUserKey

string

  • 카카오톡 채널에서 제공하는 사용자 식별키 입니다.

  • 카카오톡 채널의 자동응답 API에서 제공하던 user_key와 같습니다. (https://github.com/plusfriend/auto_reply#specification-1)

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

appUserId

string

  • 봇 설정에서 앱키를 설정한 경우에만 제공되는 사용자 정보입니다.

  • 앱키를 설정하기 위해서는 카카오 디벨로퍼스 사이트에서 앱을 생성해야 합니다.

  • 카카오 디벨로퍼스 앱 생성하기 : (https://developers.kakao.com/docs/latest/ko/getting-started/app)

  • 앱 키가 정상적으로 등록된 경우, 카카오 로그인으로 받는 사용자 식별자와 동일한 값을 얻을 수 있습니다.

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을 포함합니다.

SkillResponse

구성

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

Version

  • 스킬 응답의 version을 나타냅니다. <major-version>.<minor-version>의 모습을 갖습니다.

  • 현재 스킬 응답의 version은 2.0만 지원됩니다.

Caution.

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

Template

Context Control

Data

필드 및 예제

상세 필드

이름타입필수 여부

version

string

O

template

SkillTemplate

응답을 스킬데이터로 사용 체크시 필수 (더 알아보기)

context

ContextControl

X

data

Map<String, Any>

X

예제 코드

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

SkillTemplate

구성

이름타입필수 여부제한

outputs

Array<Component>

y

1개 이상 3개 이하

quickReplies

Array<QuickReply>

n

10개 이하

outputs(출력 그룹)

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

이름설명*캐로셀 가능 여부

simpleText

간단 텍스트

X

simpleImage

간단 이미지

X

basicCard

기본 카드

O

commerceCard

커머스 카드

O

listCard

리스트 카드

X

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

텍스트 카드형 출력 요소입니다. 텍스트 카드는 간단한 텍스트에 버튼을 추가하거나, 텍스트를 케로셀형으로 전달하고자 할 때 사용됩니다.

상세 필드

필드명타입필수 여부설명제한

title

string

title, description 중 최소 하나 필수

카드의 제목입니다.

최대 50자

description

string

title, description 중 최소 하나 필수

카드에 대한 상세 설명입니다.

단일형인 경우, 최대 400자 (title에 따라 달라짐) 케로셀인 경우, 최대 128자

buttons

Array <Button>

X

카드의 버튼들을 포함합니다.

최대 3개

Information.

  • 단일형인 경우, title과 description을 합쳐 최대 400자까지 노출됩니다.

예제 코드

{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "textCard": {
          "title": "챗봇 관리자센터에 오신 것을 환영합니다.",
          "description": "챗봇 관리자센터로 챗봇을 제작해 보세요. \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

카드의 제목입니다.

최대 50자 (케로셀인 경우, 최대 2줄)

description

string

X

카드에 대한 상세 설명입니다.

최대 230자 (케로셀인 경우, 최대 2줄)

thumbnail

Thumbnail

O

카드의 상단 이미지입니다.

buttons

Array <Button>

X

카드의 버튼들을 포함합니다.

최대 3개

Information.

  • 클라이언트에 따라 기준 글자수보다 적게 노출될 수도 있습니다.

예제 코드

{
  "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

  • header에 들어가는 경우, listCard의 제목이 됩니다.

  • items에 들어가는 경우, 해당 항목의 제목이 됩니다.

description

string

X

  • header에 들어가는 경우, 아무런 작동을 하지 않습니다.

  • items에 들어가는 경우, 해당 항목의 설명이 됩니다.

imageUrl

string

X

  • header에 들어가는 경우, 아무런 작동을 하지 않습니다.

  • items에 들어가는 경우, 해당 항목의 우측 안내 사진이 됩니다.

link

Link

X

클릭시 작동하는 링크입니다.

action

string

X

클릭시 수행될 작업입니다.

  • action 종류: block or message

blockId

string

action: block

  • blockId를 갖는 블록을 호출합니다. (바로가기 응답의 블록 연결 기능과 동일)

  • items의 title이 사용자의 발화로 나가게 됩니다.

messageText

string

action: message

  • 사용자의 발화로 messageText를 내보냅니다. (바로가기 응답의 메세지 연결 기능과 동일)

extra

Map<String, Any>

X

  • block이나 message action으로 블록 호출시, 스킬 서버에 추가적으로 제공하는 정보

예제 코드

{
  "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

상단 이미지입니다.

  • 단일형: 이미지 비율 2:1 (800*400), 1:1 (800*800)사용 가능

  • 케로셀형: 이미지 비율 2:1 (800*400)만 사용 가능

head

head

X

헤드 정보입니다.

  • head와 profile 두 필드를 동시에 노출할 수 없음

  • 케로셀형: 카드별로 head와 profile을 섞어서 사용할 수 없음

profile

profile

X

프로필 정보입니다.

  • head와 profile 두 필드를 동시에 노출할 수 없음

  • 케로셀형: 카드별로 head와 profile을 섞어서 사용할 수 없음

imageTitle

imageTitle

X

이미지를 동반하는 제목 및 설명 정보입니다.

  • 이미지 우측 정렬 고정 (위치 변경 불가)

itemList

Array <itemList>

O

아이템 목록 정보입니다.

  • 좌측 정렬 디폴트

  • 단일형: 최대 10개까지 사용 가능

  • 케로셀형: 최대 5개까지 사용 가능

itemListAlignment

string

X

itemList 및 itemListAlignment 정렬 정보입니다.

  • "left" 혹은 "right"만 입력 가능

itemListSummary

itemListSummary

X

아이템 가격 정보입니다.

  • itemListSummary 사용 시 itemListAlignment 우측 정렬을 권장

title

string

X

타이틀 정보입니다.

  • title과 description 합쳐서 글자수 제한

- 단일형: 최대 200자&12줄

- 케로셀형: 최대 100자&12줄

  • description을 넣는 경우, title이 필수 항목

description

string

X

설명 정보입니다.

  • title과 description 합쳐서 글자수 제한

- 단일형: 최대 200자&12줄

- 케로셀형: 최대 100자&12줄

  • description을 넣는 경우, title이 필수 항목

buttons

Array< Button>

X

다양한 액션을 수행할 수 있는 버튼 정보입니다.

  • 단일형: 최대 3개까지 사용 가능

  • 케로셀형: 최대 2개까지 사용 가능

buttonLayout

string

X

버튼 정렬 정보입니다.

  • "vertical" (세로배치) 혹은 "horizontal" (가로배치) 만 입력 가능

  • 단일형만 buttonLayout 설정 가능, 케로셀형은 가로배치 고정

  • 단일형에서 별도 지정하지 않는 경우 버튼 개수에 따라 배치모양이 결정됨

- 2개 이하: 가로배치

- 3개: 세로 배치

thumbnail 상세 필드

필드명타입필수 여부설명제한

imageUrl

string

O

이미지의 url 정보입니다.

URL 형식

width

int

X

이미지의 넓이 정보입니다.

설정하지 않은 경우 이미지가 1:1 비율로 노출됩니다.

  1. 단일형: 이미지 비율 2:1 (800*400), 1:1 (800*800)사용 가능

  2. 케로셀형: 이미지 비율 2:1 (800*400)만 사용 가능

height

int

X

이미지의 높이 정보입니다.

설정하지 않은 경우 이미지가 1:1 비율로 노출됩니다.

  1. 단일형: 이미지 비율 2:1 (800*400), 1:1 (800*800)사용 가능

  2. 케로셀형: 이미지 비율 2:1 (800*400)만 사용 가능

link

Link

X

이미지 클릭 시 작동하는 link입니다.

head 상세 필드

필드명타입필수 여부설명제한

title

string

O

헤드의 타이틀 정보입니다.

  • 최대 1 줄 (한 줄에 들어갈 수 있는 글자수는 기기 별로 상이)

profile 상세 필드

필드명타입필수 여부설명제한

imageUrl

string

X

프로필 이미지 정보입니다.

  • URL 형식

width

int

X

프로필 이미지의 넓이 정보입니다.

  • 1:1 비율에 맞게 입력 필요

  • 실제 이미지 사이즈와 다른 값일 경우 원본 이미지와 다르게 표현될 수 있음

height

int

X

프로필 이미지의 높이 정보입니다.

  • 1:1 비율에 맞게 입력 필요

  • 실제 이미지 사이즈와 다른 값일 경우 원본 이미지와 다르게 표현될 수 있음

title

string

O

프로필 타이틀 정보입니다.

  • 최대 15글자

imageTitle 상세 필드

필드명타입필수 여부설명제한

title

string

O

이미지타이틀의 제목 정보입니다.

  • 최대 2줄 (한 줄에 들어갈 수 있는 글자수는 기기 별로 상이)

description

string

X

이미지타이틀의 설명 정보입니다.

  • 최대 1줄 (한 줄에 들어갈 수 있는 글자수는 기기 별로 상이)

imageUrl

string

X

이미지타이틀의 이미지 URL입니다.

  • URL 형식

  • 최적이미지 사이즈 iOS 108 x 108, 안드로이드 98 x 98 (맞지 않는 경우 센터크롭됨)

itemList 상세 필드

필드명타입필수 여부설명제한

title

string

O

아이템 제목 정보입니다.

  • 최대 6자

description

string

O

아이템 설명 정보입니다.

  • 최대 2줄 (한 줄에 들어갈 수 있는 글자수는 기기 별로 상이)

itemListSummary 상세 필드

필드명타입필수 여부설명제한

title

string

O

아이템리스트 전체에 대한 제목 정보입니다.

  • 최대 6자

description

string

O

아이템리스트 전체에 대한 설명 정보입니다.

  • 최대 14자 (통화기호/문자, 숫자, 콤마, 소수점, 띄어쓰기 포함)

- 문자는 통화 문자만 사용 가능

- 소수점 두자리까지 사용 가능

ItemCard 유의사항

※ 도움말에서 제공하는 제한 및 유의사항을 확인 및 준수하여 말풍선을 구성해주시길 바랍니다. 이에 맞지 않게 말풍선을 사용하는 경우, 말풍선이 정상적으로 발송되지 않거나 챗봇 이용제한이 이루어질 수 있습니다.

* ItemCard 케로셀형에서는 thumbnail, head, profile, imageTitle 필드에 한해 몇몇 케로셀 카드에만 필드를 선택 적용하는 것이 불가능하며 일괄 적용해야 합니다. 다음 이미지를 참고해주세요.

* itemCard에서 share action을 사용하는 경우, 일부 필드만이 공유됩니다.

- head와 itemList 필드는 전달되지 않습니다. - imageTitle 필드와 title 및 description 필드는 동시에 공유될 수 없습니다. 두 필드가 함께 존재하는 경우에는 title 및 description 필드가 공유됩니다.

- imageTitle 필드가 공유되는 경우, imageTitle 내 thumbnail은 공유되지 않습니다.

예제코드

{
    "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는 케로셀헤더를 지원하지 않습니다.

※ 카드별 자세한 제한사항은 각 카드 설명 내 제한/ 유의사항을 확인해주세요. 제한 및 유의사항을 따르지 않는 경우, 말풍선이 정상적으로 동작하지 않을 수 있습니다.

예제 코드

{
  "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

  • true: 이미지 영역을 1:1 비율로 두고 이미지의 원본 비율을 유지합니다. 이미지가 없는 영역은 흰색으로 노출합니다.

  • false: 이미지 영역을 2:1 비율로 두고 이미지의 가운데를 크롭하여 노출합니다.

기본값: false ※ 케로셀 내에서는 모든 이미지가 정사각형 (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

  • message: 사용자의 발화로 messageText를 내보냅니다. (바로가기 응답의 메세지 연결 기능과 동일)

  • 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은 특히 케로셀을 공유해야 하는 경우 유용합니다.

  • operator : 상담직원 연결 기능을 제공합니다.

    링크: 상담직원 연결 플러그인

Forwardable

필드명타입필수 여부설명제한

forwardable

boolean

X

말풍선에 전달하기 아이콘을 노출합니다.

전달하기 아이콘다음 조건에서는 전달하기 아이콘이 노출되지 않습니다.

-케로셀인 경우

-버튼이 포함된 경우

-listCard의 Listitem에 link 또는 action을 사용한 경우

예제 코드

{
  "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로 해당 값을 확인할 수 있습니다. 다만 바로연결 버튼을 통해 입력된 발화에서 별도로 엔티티를 추출하여 파라미터로 전달하지는 않습니다.

이름타입설명제한

label

String

사용자에게 노출될 바로가기 응답의 표시

action

String

바로가기 응답의 기능

‘Message’ 혹은 ‘block’

messageText

String

사용자 측으로 노출될 발화

blockId

String

바로가기 응답이 ‘블록연결’ 기능일 때, 연결될 블록의 id

Action이 ‘block’ 일 때, 필수값

extra

Any

블록을 호출 시 추가적으로 제공하는 정보

Previous플러그인에 스킬 적용하기Next스킬 오류 내역 확인하기

Last updated