도움말 - 챗봇 관리자센터

구 스킬(v1) 대비 달라진 점

  • v1 : 구 스킬(CBT 기간부터 현재까지 카카오가 제공하고 있는 스킬 구현 방식)
  • v2 : 현 스킬(2018. 12. 03 OBT 오픈 후 카카오가 새롭게 제공하고 있는 스킬 구현 방식)

스킬 응답 구조 변경

v1의 구조

{
    "contents": [...],
    "quickReplies": [...]
}
 
 
// 혹은 출력에서 사용하기 위해 data로 이용하는 경우
{
    "customDataField": "customDataValue",
    "customDataField2": "customDataValue2"
}

v2의 구조

  • v1에서 contents와 quickReplies → v2의 template으로 이동
  • data로 이용하는 경우, data에 custom field와 value를 사용
{
    "version": "2.0",
    "template": {...},
    "data": {...},
    "context": {...}
}

{
    "version": "2.0",
    "data": {
        "customDataField": "customDataValue",
        "customDataField2": "customDataValue2"
    }
}

스킬 컴퍼넌트 변경

v1 컴퍼넌트→v2 컴퍼넌트
TextSimpleText
ImageSimpleImage
Card.Text
Card.Image		BasicCard
Card.CommerceCommerceCard
Card.ListListCard
Card.Text(Carousel형)
Card.Image(Carousel형)
Card.Commerce(Carousel형)		Carousel
QuickReply[type=block]QuickReply[action=block]
QuickReply[type=text]QuickReply[action=message]
Button[type=url]Button[action=webLink]
Button[type=linkUrl]Button[action=osLink]
Button[type=phone]Button[action=phone]
Button[action=massage]
Button[action=block]
Button[action=share]


v1 Text → v2 SimpleText

v1 text

{
    "contents": [
        {
            "type": "text",
            "text": "hello, world"
        }
    ]
}

v2 SimpleText

{
    "version": "2.0",
    "template": {
        "outputs": [
            {
                "simpleText": {
                    "text": "hello, world"
                }
            }
        ]
    }
}


v1 Image → v2 SimpleImage

v1 Image

{
    "contents": [
        {
            "type": "image",
            "image": {
                "url": "https://t1.daumcdn.net/friends/prod/category/RYAN_M.jpg"
            }
        }
    ]
}

v2 SimpleImage

{
    "version": "2.0",
    "template": {
        "outputs": [
            {
                "simpleImage": {
                    "imageUrl": "https://t1.daumcdn.net/friends/prod/category/RYAN_M.jpg",
                    "altText": "ryan with hood"
                }
            }
        ]
    }
}
  • v2의 SimpleImage의 경우, altText가 필수입니다. imageUrl에 있는 이미지를 받아올 수 없는 경우, altText의 내용이 말풍선으로 나갈 예정입니다.


v1 card.text → v2 BasicCard

v1 card.text

{
    "contents": [
        {
            "type": "card.text",
            "cards":[
                {
                    "description":"텍스트 카드형입니다",
                    "buttons":[
                        {
                            "type":"url",
                            "label":"링크 버튼",
                            "data":{
                                "url": "https://daum.net"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

v2 basicCard

{
    "version": "2.0",
    "template": {
        "outputs": [
            {
                "basicCard": {
                    "description": "텍스트 카드형입니다",
                    "buttons": [
                        {
                            "action": "webLink",
                            "label": "링크 버튼",
                            "webLinkUrl": "https://daum.net"
                        }
                    ]
                }
            }
        ]
    }
}

  • card 형에서 공통적으로 'cards' 라는 배열 필드가 사라집니다. cards 라는 배열 필드가 있던 이유는 케로셀을 지원하기 위함이었습니다. (cards가 여러 card들을 가질 경우 케로셀에 매칭). 하지만 v2에서 케로셀 타입을 별도로 제공하기 때문에 따로 cards 필드를 유지할 이유가 없어졌습니다.

  • 'description', 'title'은 동일합니다. 'buttons'의 경우, v2의 button 배열로 바뀌었습니다.

v1 card.image → v2 BasicCard

v1 card.image

{
    "contents": [
        {
            "type": "card.image",
            "cards":[
                {
                    "title": "이미지 카드",
                    "description":"이미지 카드형입니다",
                    "linkUrl": {
                        "type": "WEB",
                        "webUrl": "https://kakao.com"
                    },
                    "imageUrl": "https://t1.daumcdn.net/friends/prod/category/RYAN_M.jpg",
                    "buttons":[
                        {
                            "type":"url",
                            "label":"링크 버튼",
                            "data":{
                                "url": "https://daum.net"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

v2 BasicCard

{
    "version": "2.0",
    "template": {
        "outputs": [
            {
                "basicCard": {
                    "title": "이미지 카드",
                    "description": "이미지 카드형입니다",
                    "thumbnail": {
                        "imageUrl": "https://t1.daumcdn.net/friends/prod/category/RYAN_M.jpg",
                        "link": {
                            "web": "https://kakao.com"
                        }
                    },
                    "buttons": [
                        {
                            "action": "webLink",
                            "label": "링크 버튼",
                            "webLinkUrl": "https://daum.net"
                        }
                    ]
                }
            }
        ]
    }
}
  • v1 card.image 의 'imageUrl'과 'linkUrl' -> v2 BasicCard의 'thumbnail' 필드 안으로 작성
  • v1 card.image 는 추가적으로 title을 가질 수 있기 때문에 v2 BasicCard도 이를 지원 그 외에는 card.text와 동일합니다.

v1 card.commerce → v2 CommerceCard

v1 card.commerce

{
   "contents":[
      {
         "type":"card.commerce",
         "cards":[
            {
               "imageUrl": "https://t1.daumcdn.net/friends/prod/category/RYAN_M.jpg",
               "title": "커머스 카드",
               "linkUrl": {
                    "type": "WEB",
                    "webUrl": "https://kakao.com"
               },
               "price": {
                  "regularPrice":10000,
                  "discountPrice":9000,
                  "discountAmount":1000,
                  "isDiscount":true,
                  "discountType":"amount"
               },
               "profile": {
                 "name": "카카오",
                 "imageUrl": "https://t1.kakaocdn.net/kakaocorp/corp_thumbnail/Kakao.png"
               },
               "buttons":[
                    {
                        "type":"url",
                        "label":"링크 버튼",
                        "data":{
                            "url": "https://daum.net"
                        }
                    }
                ]
            }
         ]
      }
   ]
}

v2 CommerceCard

{
    "version": "2.0",
    "template": {
        "outputs": [
            {
                "commerceCard": {
                    "description": "커머스 카드",
                    "thumbnails": [{
                        "imageUrl": "https://t1.daumcdn.net/friends/prod/category/RYAN_M.jpg",
                        "link": {
                            "web": "https://kakao.com"
                        }
                    }],
                    "profile": {
                        "nickname": "카카오",
                        "imageUrl": "https://t1.kakaocdn.net/kakaocorp/corp_thumbnail/Kakao.png"
                    },
                    "currency": "won",
                    "price": 10000,
                    "discount": 1000,
                    "discountPrice": 9000,
                    "buttons": [
                        {
                            "action": "webLink",
                            "label": "링크 버튼",
                            "webLinkUrl": "https://daum.net"
                        }
                    ]
                }
            }
        ]
    }
}
  • v1 card.commerce의 title → v2 CommerceCard의 description
  • v1 card.commerce의 price 필드 → v2 CommerceCard의 price, discount, currency 로 분리
    • v1 price.regularPrice → v2 price
    • v1 price.discountAmount → v2 discount
    • v1 price.discountPrice → v2 discountPrice


v1 card.list → v2 ListCard

v1 card.list

{
    "contents": [  
        {
            "type": "card.list",
            "cards": [
                {
                    "listItems": [
                        {
                            "type": "title",
                            "imageUrl": "http://k.kakaocdn.net/dn/xsBdT/btqqIzbK4Hc/F39JI8XNVDMP9jPvoVdxl1/2x1.jpg",
                            "title": "카카오 i 디벨로퍼스를 소개합니다",
                            "linkUrl": {
                                "type": "WEB",
                                "webUrl": "https://kakao.com"
                            }
                        },
                        {
                            "type": "item",
                            "title": "Kakao i Developers",
                            "description": "새로운 AI의 내일과 일상의 변화",
                            "imageUrl": "http://k.kakaocdn.net/dn/APR96/btqqH7zLanY/kD5mIPX7TdD2NAxgP29cC0/1x1.jpg",
                            "linkUrl": {
                                "type": "WEB",
                                "webUrl": "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)"
                            }
                        },
                        {
                            "type": "item",
                            "title": "챗봇 관리자센터",
                            "description": "카카오톡 채널 챗봇 만들기",
                            "imageUrl": "http://k.kakaocdn.net/dn/N4Epz/btqqHCfF5II/a3kMRckYml1NLPEo7nqTmK/1x1.jpg",
                            "linkUrl": {
                                "type": "WEB",
                                "webUrl": "https://namu.wiki/w/%EB%AC%B4%EC%A7%80(%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%94%84%EB%A0%8C%EC%A6%88)"
                            }
                        },
                        {
                            "type": "item",
                            "title": "Kakao i Voice Service",
                            "description": "보이스봇 / KVS 제휴 신청하기",
                            "imageUrl": "http://k.kakaocdn.net/dn/bE8AKO/btqqFHI6vDQ/mWZGNbLIOlTv3oVF1gzXKK/1x1.jpg",
                            "linkUrl": {
                                "type": "WEB",
                                "webUrl": "https://namu.wiki/w/%EC%96%B4%ED%94%BC%EC%B9%98"
                            }
                        }
                    ],
                    "buttons": [
                        {
                            "label": "구경가기",
                            "type": "url",
                            "data": {
                                "url": "https://namu.wiki/w/%EC%96%B4%ED%94%BC%EC%B9%98"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

v2 ListCard

{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "listCard": {
          "header": {
            "title": "카카오 i 디벨로퍼스를 소개합니다",
            "imageUrl": "http://k.kakaocdn.net/dn/xsBdT/btqqIzbK4Hc/F39JI8XNVDMP9jPvoVdxl1/2x1.jpg",
            "link": {
                "web": "https://kakao.com"
            }  
          },
          "items": [
            {
              "title": "Kakao i Developers",
              "description": "새로운 AI의 내일과 일상의 변화",
              "imageUrl": "http://k.kakaocdn.net/dn/APR96/btqqH7zLanY/kD5mIPX7TdD2NAxgP29cC0/1x1.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": "http://k.kakaocdn.net/dn/N4Epz/btqqHCfF5II/a3kMRckYml1NLPEo7nqTmK/1x1.jpg",
              "link": {
                "web": "https://namu.wiki/w/%EB%AC%B4%EC%A7%80(%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%94%84%EB%A0%8C%EC%A6%88)"
              }
            },
            {
              "title": "Kakao i Voice Service",
              "description": "보이스봇 / KVS 제휴 신청하기",
              "imageUrl": "http://k.kakaocdn.net/dn/bE8AKO/btqqFHI6vDQ/mWZGNbLIOlTv3oVF1gzXKK/1x1.jpg",
              "link": {
                "web": "https://namu.wiki/w/%EC%96%B4%ED%94%BC%EC%B9%98"
              }
            }
          ],
          "buttons": [
            {
              "label": "구경가기",
              "action": "webLink",
              "webLinkUrl": "https://namu.wiki/w/%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%94%84%EB%A0%8C%EC%A6%88"
            }
          ]
        }
      }
    ]
  }
}
  • v2 items는 더 이상 type을 갖지 않습니다. v1에서는 title 타입과 item 타입을 구분하기 위해서 type을 사용했지만 v2에서는 아예 header 와 items로 분리하였습니다.
  • v2 header와 items는 동일한 형태를 갖습니다. 하지만 v2 header는 title을 지원하지 않습니다.

v1 (Carousel형) card.text / card.image / card.commerce → v2 Carousel

  • v2에서 Carousel 타입이 추가되었습니다.
  • v1에서는 cards 필드에 여러 card가 들어가면 케로셀형으로 인식되었습니다. 하지만 v2에서는 조금 더 명시적으로 케로셀형으로 표현해야 합니다.
  • v2 Carousel은 'type' 필드를 갖고 'CommerceCard' 혹은 'BasicCard'를 그 값으로 갖습니다.
  • v2 Carousel의 items에 동일한 타입을 갖는 여러 장의 카드를 추가하여 케로셀을 표현할 수 있습니다.
Last updated on 2023-3-17
← 응답 타입별 JSON 포맷스킬 개발 가이드(v1) →