도움말 - 챗봇 관리자센터

응답 타입별 JSON 포맷

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

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

SkillPayload

구성

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

  • intent
  • userRequest
  • bot
  • action


intent

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

상세 필드

필드명타입설명
idString블록 id입니다.
nameString블록명이며, 지식의 경우 "지식+"로 노출합니다.


intent.extra.knowledges

상세 필드

필드명타입설명
matchedKnowledgesArray<Knowledge>발화에 일치한 지식 목록입니다.

knowledge

상세 필드

필드명타입설명
answerString지식의 답변입니다.
questionString지식의 질문입니다.
categoriesArray<String>QA의 카테고리입니다.
landingUrlString지식 답변에서 링크 더보기입니다.
imageUrlString지식 답변에서 썸네일 이미지입니다.

예제 코드

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

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

상세 필드

필드명타입설명
timezonestring사용자의 시간대를 반환합니다.한국에서 보낸 요청이라면 “Asia/Seoul”를 갖습니다.
blockBlock
  • 사용자의 발화에 반응한 블록의 정보입니다.
  • 블록의 id와 name을 포함합니다.
utterancestring봇 시스템에 전달된 사용자의 발화입니다.
langstring
  • 사용자의 언어를 반환합니다.
  • 한국에서 보낸 요청이라면 “ko”를 갖습니다.
userUser사용자의 정보입니다.

bot

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

상세 필드

필드명타입설명
idString봇의 고유한 식별자입니다.
nameString설정된 봇의 이름입니다.

action

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

상세 필드

필드명타입설명
idString스킬의 고유한 식별자입니다.
nameString설정된 스킬의 이름입니다.
paramsMap<String, String>
  • 사용자의 발화로부터 추출한 파라미터 정보입니다.
  • 엔티티의 이름을 키로, 추출한 정보를 상세 값으로 가집니다.
detailParamsMap<String, DetailParam>
  • 사용자의 발화로부터 추출한 엔티티의 상세 정보입니다.
  • params 필드와 유사하지만, params에서 제공하지 않은 추가적인 정보들을 제공합니다.
clientExtraMap<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에 담아서 제공하고 있습니다.

필드타입설명
idstring
  • 사용자를 식별할 수 있는 key로 최대 70자의 값을 가지고 있습니다.
  • 이 값은 특정한 bot에서 사용자를 식별할 때 사용할 수 있습니다.
  • 동일한 사용자더라도, 봇이 다르면 다른 id가 발급됩니다.
typestring현재는 botUserKey만 제공합니다.
propertiesObject추가적으로 제공하는 사용자의 속성 정보입니다.

user.properties

상세 필드

속성타입설명
plusfriendUserKeystring
  • 카카오톡 채널에서 제공하는 사용자 식별키 입니다.
  • 카카오톡 채널의 자동응답 API에서 제공하던 user_key와 같습니다. (https://github.com/plusfriend/auto_reply#specification-1)
  • 모든 사용자에게 제공되는 값으로, botUserKey와 마찬가지로 봇에서 사용자를 식별하는데 사용할 수 있습니다.
appUserIdstring
  • 봇 설정에서 앱키를 설정한 경우에만 제공되는 사용자 정보입니다.
  • 앱키를 설정하기 위해서는 카카오 디벨로퍼스 사이트에서 앱을 생성해야 합니다.
  • 카카오 디벨로퍼스 앱 생성하기 : (https://developers.kakao.com/docs/latest/ko/getting-started/app)
  • 앱 키가 정상적으로 등록된 경우, 카카오 로그인으로 받는 사용자 식별자와 동일한 값을 얻을 수 있습니다.
isFriendBoolean
  • 사용자가 봇과 연결된 카카오톡 채널을 추가한 경우 제공되는 식별키입니다.
  • 채널을 추가한 경우만 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>의 모습을 갖습니다. 따라서 2.0, 2.1, 3.0과 같은 모습을 갖습니다.

Caution.

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

Template

Context Control

Data

필드 및 예제

상세 필드

이름타입필수 여부
versionstringO
templateSkillTemplate응답을 스킬데이터로 사용 체크시 필수
(더 알아보기)
contextContextControlX
dataMap<String, Any>X

예제 코드

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

SkillTemplate

구성

outputs (출력 그룹)

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

Definition.

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

기본 카드형 케로셀 예제

quickReplies (바로가기 그룹)

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

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

ContextControl

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

상세 필드

이름타입필수 여부제한
valuesContextValueO

ContextValue 상세 필드

이름타입필수 여부설명
namestringO수정하려는 output 컨텍스트의 이름
lifeSpanintO수정하려는 ouptut 컨텍스트의 lifeSpan
paramsMap <string, string>Xoutput 컨텍스트에 저장하는 추가 데이터

예제 코드

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

간단한 텍스트형 출력 요소입니다.

상세 필드

이름타입필수 여부설명제한
textstringO전달하고자 하는 텍스트입니다1000자
  • text가 500자가 넘는 경우, 500자 이후의 글자는 생략되고 전체 보기 버튼을 통해서 전체 내용을 확인할 수 있습니다.

예제 코드

{
    "version": "2.0",
    "template": {
        "outputs": [
            {
                "simpleText": {
                    "text": "간단한 텍스트 요소입니다."
                }
            }
        ]
    }
}

SimpleImage

간단한 이미지형 출력 요소입니다. 이미지 링크 주소를 포함하면 이를 스크랩하여 사용자에게 전달합니다. 이미지 링크 주소가 유효하지 않을 수 있기 때문에, 대체 텍스트를 꼭 포함해야 합니다.

상세 필드

이름타입필수 여부설명제한
imageUrlstringO전달하고자 하는 이미지의 url입니다URL 형식
altTextstringOurl이 유효하지 않은 경우, 전달되는 텍스트입니다최대 1000자

예제 코드

{
    "version": "2.0",
    "template": {
        "outputs": [
            {
                "simpleImage": {
                    "imageUrl": "https://t1.kakaocdn.net/openbuilder/sample/lj3JUcmrzC53YIjNDkqbWK.jpg",
                    "altText": "보물상자입니다"
                }
            }
        ]
    }
}

TextCard

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

상세 필드

필드명타입필수 여부설명제한
textstringO전달하고자 하는 텍스트입니다.최대 400자 (케로셀 128자)
buttonsArray
<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

기본 카드형 출력 요소입니다. 기본 카드는 소셜, 썸네일, 프로필 등을 통해서 사진이나 글, 인물 정보 등을 공유할 수 있습니다. 기본 카드는 제목과 설명 외에 썸네일 그룹, 프로필, 버튼 그룹, 소셜 정보를 추가로 포함합니다.

상세 필드

필드명타입필수 여부설명제한
titlestringX카드의 제목입니다.최대 2줄
descriptionstringX카드에 대한 상세 설명입니다.최대 230자
thumbnailThumbnailO카드의 상단 이미지입니다.
profileProfileX카드의 프로필 정보입니다.
socialSocialX카드의 소셜 정보입니다.
buttonsArray
<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

커머스 카드형 출력 요소입니다. 커머스 카드는 제품에 대한 소개, 구매 안내 등을 사용자에게 전달할 수 있습니다. 커머스 카드는 제목과 설명 외에 썸네일 그룹, 프로필, 버튼 그룹, 가격 정보를 추가로 포함합니다.

상세 필드

필드명타입필수 여부설명제한
titlestringX제품의 이름입니다.최대 30자
descriptionstringX제품에 대한 상세 설명입니다.최대 40자
priceintO제품의 가격입니다.
currencystringX제품의 가격에 대한 통화입니다.현재 won만 가능
discountintX제품의 가격에 대한 할인할 금액입니다.
discountRateintX제품의 가격에 대한 할인율입니다.
dicountedPriceintX (discountRate을 쓰는 경우 필수)제품의 가격에 대한 할인가(할인된 가격)입니다.
thumbnailsArray
<Thumbnail>		O제품에 대한 사진입니다.현재 1개만 가능
profileProfileX제품을 판매하는 프로필 정보입니다.
buttonsArray
<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

리스트 카드형 출력 요소입니다. 리스트 카드는 표현하고자 하는 대상이 다수일 때, 이를 효과적으로 전달할 수 있습니다. 헤더와 아이템을 포함하며, 헤더는 리스트 카드의 상단에 위치합니다. 리스트 상의 아이템은 각각의 구체적인 형태를 보여주며, 제목과 썸네일, 상세 설명을 포함합니다.

상세 필드

필드명타입필수 여부설명제한
headerListItemO카드의 상단 항목
itemsArray
<ListItem>		O카드의 각각 아이템최대 5개
케로셀형 : 최대 4개
buttonsArray
<Button>		X최대 2개

ListItem 상세 필드

필드명타입필수 여부설명
titlestringO
  • header에 들어가는 경우, listCard의 제목이 됩니다.
  • items에 들어가는 경우, 해당 항목의 제목이 됩니다.
descriptionstringX
  • header에 들어가는 경우, 아무런 작동을 하지 않습니다.
  • items에 들어가는 경우, 해당 항목의 설명이 됩니다.
imageUrlstringX
  • header에 들어가는 경우, 아무런 작동을 하지 않습니다.
  • items에 들어가는 경우, 해당 항목의 우측 안내 사진이 됩니다.
linkLinkX클릭시 작동하는 링크입니다.
actionstringX클릭시 수행될 작업입니다.
  • action 종류: block or message
blockIdstringaction: block
  • blockId를 갖는 블록을 호출합니다. (바로가기 응답의 블록 연결 기능과 동일)
  • items의 title이 사용자의 발화로 나가게 됩니다.
messageTextstringaction: message
  • 사용자의 발화로 messageText를 내보냅니다. (바로가기 응답의 메세지 연결 기능과 동일)
extraMap<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 프로필 정보입니다.
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 설명 정보입니다.
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 이미지의 높이 정보입니다.
link Link X 이미지 클릭 시 작동하는 link입니다.

head 상세 필드

필드명타입필수 여부설명제한
titlestringO헤드의 타이틀 정보입니다.
  • 최대 1 줄 (한 줄에 들어갈 수 있는 글자수는 기기 별로 상이)

profile 상세 필드

필드명 타입 필수 여부 설명 제한
imageUrl string X 프로필 이미지 정보입니다.
  • URL 형식
width int X 프로필 이미지의 넓이 정보입니다.
  • 1:1 비율에 맞게 입력 필요
  • 실제 이미지 사이즈와 다른 값일 경우 원본 이미지와 다르게 표현될 수 있음
height int X 프로필 이미지의 높이 정보입니다.
title string O 프로필 타이틀 정보입니다.
  • 최대 15글자

imageTitle 상세 필드

필드명타입필수 여부설명제한
titlestringO이미지타이틀의 제목 정보입니다.
  • 최대 2줄 (한 줄에 들어갈 수 있는 글자수는 기기 별로 상이)
descriptionstringX이미지타이틀의 설명 정보입니다.
  • 최대 1줄 (한 줄에 들어갈 수 있는 글자수는 기기 별로 상이)
imageUrlstringX이미지타이틀의 이미지 URL입니다.
  • URL 형식
  • 최적이미지 사이즈 iOS 108 x 108, 안드로이드 98 x 98 (맞지 않는 경우 센터크롭됨)

itemList 상세 필드

필드명타입필수 여부설명제한
titlestringO아이템 제목 정보입니다.
  • 최대 6자
descriptionstringO아이템 설명 정보입니다.
  • 최대 2줄 (한 줄에 들어갈 수 있는 글자수는 기기 별로 상이)

itemListSummary 상세 필드

필드명타입필수 여부설명제한
titlestringO아이템리스트 전체에 대한 제목 정보입니다.
  • 최대 6자
descriptionstringO아이템리스트 전체에 대한 설명 정보입니다.
  • 최대 14자 (통화기호/문자, 숫자, 콤마, 소수점, 띄어쓰기 포함)
    • 문자는 통화 문자만 사용 가능
    • 소수점 두자리까지 사용 가능

유의사항

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

  1. itemCard에서 itemList는 필수 항목입니다.
  2. itemCard는 Event API 광고성 메시지로 사용 가능하며, 기존 광고성 말풍선 제한사항을 동일하게 준수하는 경우 정상적으로 발송됩니다.
  3. itemCard 케로셀형은 최대 10개의 카드를 구성할 수 있습니다.
  4. itenCard 케로셀형에서는 thumbnail, head, profile, imageTitle 필드에 한해 몇몇 케로셀 카드에만 필드를 선택 적용하는 것이 불가능하며 일괄 적용해야 합니다. 다음 이미지를 참고해주세요.
  5. 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)으로 통일되어야 합니다.

상세 필드

필드명타입필수 여부설명제한
typestringO케로셀의 타입입니다.basicCard 혹은 commerceCard, listCard, itemCard
itemsArray
<TextCard>, Array
<BasicCard>, Array
<CommerceCard>, Array<ListCard>, Array<itemCard>		O케로셀 아이템입니다.최대 10개
*ListCard는 최대 5개
headerCarouselHeaderX케로셀의 커버를 제공합니다.*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

필드명타입필수 여부설명
imageUrlstringO이미지의 url입니다.
linkLinkX이미지 클릭시 작동하는 link입니다.
fixedRatiobooleanX
  • true: 이미지 영역을 1:1 비율로 두고 이미지의 원본 비율을 유지합니다. 이미지가 없는 영역은 흰색으로 노출합니다.
  • false: 이미지 영역을 2:1 비율로 두고 이미지의 가운데를 크롭하여 노출합니다.
기본값: false

※ 케로셀 내에서는 모든 이미지가 정사각형 (1:1) 혹은 모든 이미지가 와이드형 (2:1)으로 통일되어야 합니다.
※ BasicCard 또는 CommerceCard에서 true 설정 시, 버튼이 가로로 배열되며 최대 2개로 제한됩니다.

Button

필드명타입필수 여부설명제한
labelstringO버튼에 적히는 문구입니다.버튼 14자(가로배열 2개 8자)
* 썸네일이 1:1이면 버튼이 가로배열 됩니다.
actionstringO버튼 클릭시 수행될 작업입니다.
webLinkUrlstringaction: webLink웹 브라우저를 열고 webLinkUrl 의 주소로 이동합니다.URL
messageTextstringaction: message or block
  • message: 사용자의 발화로 messageText를 내보냅니다. (바로가기 응답의 메세지 연결 기능과 동일)
  • block: 블록 연결시 사용자의 발화로 노출됩니다.
phoneNumberstringaction: phonephoneNumber에 있는 번호로 전화를 겁니다.전화번호
blockIdstringaction: blockblockId를 갖는 블록을 호출합니다. (바로가기 응답의 블록 연결 기능과 동일)존재하는 블록 id
extraMap<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

필드명타입필수 여부설명제한
forwardablebooleanX말풍선에 전달하기 아이콘을 노출합니다.전달하기 아이콘을 스킬을 통해 출력하기 위해서는 말풍선이 단일형이면서 버튼이 포함되지 않은 경우에만 설정 가능합니다.

예제 코드

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

필드명타입필수 여부설명
pcstringXpc의 웹을 실행하는 link입니다.
mobilestringXmobile의 웹을 실행하는 link입니다.
webstringX모든 기기에서 웹을 실행하는 link입니다.

Information. 링크 우선순위 링크는 다음과 같은 우선순위를 갖습니다.

  • pc: pc < web
  • 모바일: mobile < web

예를 들면, pc에 대하여 링크 값이 webURL, pcURL를 가지면 위 규칙에 따라 webURL이 노출됩니다.
모바일 기기에 대하여 Link의 값이 webURL, mobileURL를 가지면 위 규칙에 따라 webURL이 노출됩니다.

CarouselHeader

상세 필드

필드명타입필수 여부설명제한
titlestringO케로셀 헤드 제목최대 2줄
(한 줄에 들어갈 수 있는 글자 수는 기기에 따라 달라집니다.)
descriptionstringO케로셀 헤드 설명최대 3줄
(한 줄에 들어갈 수 있는 글자 수는 기기에 따라 달라집니다.)
thumbnailThumbnailO케로셀 헤드 배경 이미지현재 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

필드명타입필수 여부설명제한
nicknamestringO프로필 이름
imageUrlstringX프로필 이미지

TIP!

이미지 사이즈는 180px X 180px 추천합니다.

QuickReplies

바로가기 응답은 발화와 동일합니다. 대신, 사용자가 직접 발화를 입력하지 않아도 선택을 통해서 발화를 전달하거나 다른 블록을 호출할 수 있습니다.

바로가기 응답 예시

제한적 선택지를 가진 응답이거나, 다음 발화에 대한 힌트를 줄 필요가 있을 때 바로가기 응답을 사용하면 유용합니다.

종류

바로가기 응답은 현재 두 가지 기능을 제공합니다.

메시지 연결 기능

바로가기 응답에서 메시지 연결 기능은 발화를 입력하는 것과 동일합니다.

바로가기 응답(메시지 기능)을 이용한 간단한 메시지형 응답


라이언 ‘바로가기 응답’은 버튼 위에 ‘라이언’이라는 문자가 적혀있지만, 실제 클릭시 ‘라이언 알아보기’라는 발화로 대화창에 나가게 됩니다.

바로가기 응답을 이용하여 블록을 호출한 경우


바로가기 응답을 사용하지 않고 사용자가 직접 ‘라이언 알아보기’를 입력해도, 해당 발화를 인식하는 블록이 실제로 존재하기 때문에 동일한 출력이 노출됩니다.

사용자가 직접 타이핑한 발화를 이용하여 블록을 호출한 경우


봇 사용자는 바로가기 응답 ‘라이언’을 눌렀을 때, ‘라이언 알아보기’ 발화가 전송되고 연결된 블록의 출력 값이 어떻게 나오는지 경험하게 됩니다. 이를 바탕으로 앞으로 발화 ‘라이언 알아보기’를 입력 전송하면 바로가기 응답을 눌렀을 때와 동일한 응답을 받을 수 있다는 것을 예측할 수 있습니다. 그러므로 메시지 연결 기능을 가진 바로가기 응답은 사용자에게 더욱 직관적인 흐름을 제공합니다.

블록 연결 기능

두 번째는 블록 연결 기능입니다. 블록을 연결하면 사용자 측에서 나가는 발화와 상관없이 blockId로 명시된 블록을 무조건 호출하게 됩니다.

바로가기 응답(블록 연결 기능)을 이용한 간단한 메시지형 응답


블록 연결 기능도 외형은 메시지 연결과 상당히 유사합니다.

사용자가 직접 ‘반응할 수 없는 발화’를 입력하여 전송한 경우


‘라이언’이라는 바로가기 응답을 선택하면, ‘반응할 수 없는 발화’ 라는 발화가 사용자 측에서 노출됩니다. 그리고 연결한 블록이 발화와 상관없이 강제로 실행됩니다. 따라서 그 이후에 동일한 발화를 입력하더라도, ‘반응할 수 없는 발화’를 발화로 등록한 블록이 없기 때문에 폴백 블록이 실행됩니다.

Caution.

메시지 기능을 사용한 바로가기 응답의 경우, 그 흐름이 매우 직관적이라 언급했습니다. 손수 발화를 입력하지 않고, 클릭을 통해서 선택지 중 하나를 골랐다는 차이만 있기 때문입니다. 봇 사용자는 추후에도 노출 되었던 발화를 직접 입력하여 전송하여도, 같은 응답을 받을 수 있다는 보장을 받습니다.

하지만 블록 연결 기능을 사용한 바로가기 응답의 경우, 어떠한 발화가 사용자 측에 노출되어도 결국 호출되는 블록은 동일합니다. 추후에 사용자가 동일한 발화를 다시 동일하게 입력해도 해당 블록이 노출되지 않을 수 있습니다. 그렇기 때문에 바로가기 응답에서 블록 연결 기능을 사용할 때는 봇 사용자의 직관적인 흐름을 훼손하지 않도록 주의하여야 합니다.

상세 필드

바로연결 버튼의 extra 필드 하위로 원하는 파라미터를 입력하는 경우 연결된 다음 블록에서 페이로드의 client Extra로 해당 값을 확인할 수 있습니다.
다만 바로연결 버튼을 통해 입력된 발화에서 별도로 엔티티를 추출하여 파라미터로 전달하지는 않습니다.

Last updated on 2023-9-25
← 플러그인에 스킬 적용하기스킬 오류 내역 확인하기 →