응답 타입별 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의 key1val1, key2val2를 추가합니다.

  • 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

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

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이 사용자에게 노출

  • discountRatediscountedPrice를 필요로 합니다. discountedPrice가 주어지지 않으면 사용자에게 >discountRate을 노출하지 않습니다.

  • discountRatediscount가 동시에 있는 경우, 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

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

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

X

상단 이미지입니다.

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

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

head

X

헤드 정보입니다.

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

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

profile

X

프로필 정보입니다.

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

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

imageTitle

X

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

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

itemList

Array <itemList>

O

아이템 목록 정보입니다.

  • 좌측 정렬 디폴트

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

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

itemListAlignment

string

X

itemList 및 itemListAlignment 정렬 정보입니다.

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

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

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을 사용하는 경우, 일부 필드만이 공유됩니다.

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

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

예제코드

{
    "version": "2.0",
    "template": {
        "outputs": [
            {
                "itemCard": {
                    "imageTitle": {
                        "title": "DOFQTK",
                        "description": "Boarding Number"
                    },
                    "title": "",