메시지 템플릿

기본 템플릿

이 문서는 카카오톡 메시지 API와 카카오톡 공유 API로 보낼 메시지를 사전 정의(Predefined)된 기본 템플릿으로 구성하는 방법을 안내합니다.

기본 템플릿은 정해진 형식에 따라 메시지를 객체 형태로 작성하는 템플릿입니다. 자세한 내용은 이해하기에서 확인할 수 있습니다.

사용 방법

템플릿 종류를 참고하여 어떤 메시지 템플릿을 사용할지 결정 후, 아래 원하는 템플릿의 정의된 형식에 맞게 템플릿 객체를 구성합니다.
기본 템플릿으로 발송한 메시지의 웹 링크와 앱 링크는 앱 관리 페이지의 [제품 링크 관리]에 등록된 아래 도메인과 스킴만 연결이 허용됩니다. 자세한 내용은 각 문서 내용을 참고합니다.
- 웹 링크: 웹 도메인 중 하나 지정
- 앱 링크: 기본 네이티브 앱 스킴으로 고정
카카오톡 메시지 API 또는 카카오톡 공유 API 호출 시, 구성한 템플릿 객체를 각 언어별 지정된 파라미터 이름에 맞게 전달해야 합니다. 각 항목의 예제와 플랫폼별 개발 문서를 참고합니다.

기본 네이티브 앱 스킴 변경 시 기본 템플릿 링크 설정

기본 네이티브 앱 스킴을 변경하면, 기본 템플릿의 앱 링크 연결을 허용할 스킴도 함께 변경됩니다. 이 경우 메시지의 링크 연결이 불가능한 오류가 발생할 수 있으므로, 변경 전 영향 범위 확인 및 사전 조치가 필요합니다.

피드 템플릿

피드 템플릿을 사용하려면 아래와 같이 객체를 구성해야 합니다.

이름	타입	설명	필수
object_type	`String`	`feed`로 고정	O
content	`Content`	메시지의 메인 콘텐츠 정보	O
item_content	`ItemContent`	아이템 영역에 포함할 콘텐츠 피드 B형으로 구성할 경우 사용	X
social	`Social`	콘텐츠에 대한 소셜 정보	X
button_title	`String`	기본 버튼 타이틀("자세히 보기")을 변경하고 싶을 때 설정	X
buttons	`Buttons[]`	버튼 목록, 최대 2개 버튼 타이틀과 링크를 변경하고 싶을 때, 버튼 두 개를 넣고 싶을 때 사용	X

// 피드 템플릿 메시지 구성을 위한 template_object 구성 예시
{
        "object_type": "feed",
        "content": {
            "title": "오늘의 디저트",
            "description": "아메리카노, 빵, 케익",
            "image_url": "https://mud-kage.kakao.com/dn/NTmhS/btqfEUdFAUf/FjKzkZsnoeE4o19klTOVI1/openlink_640x640s.jpg",
            "image_width": 640,
            "image_height": 640,
            "link": {
                "web_url": "http://www.daum.net",
                "mobile_web_url": "http://m.daum.net",
                "android_execution_params": "contentId=100",
                "ios_execution_params": "contentId=100"
            }
        },
        "item_content" : {
            "profile_text" :"Kakao",
            "profile_image_url" :"https://mud-kage.kakao.com/dn/Q2iNx/btqgeRgV54P/VLdBs9cvyn8BJXB3o7N8UK/kakaolink40_original.png",
            "title_image_url" : "https://mud-kage.kakao.com/dn/Q2iNx/btqgeRgV54P/VLdBs9cvyn8BJXB3o7N8UK/kakaolink40_original.png",
            "title_image_text" :"Cheese cake",
            "title_image_category" : "Cake",
            "items" : [
                {
                    "item" :"Cake1",
                    "item_op" : "1000원"
                },
                {
                    "item" :"Cake2",
                    "item_op" : "2000원"
                },
                {
                    "item" :"Cake3",
                    "item_op" : "3000원"
                },
                {
                    "item" :"Cake4",
                    "item_op" : "4000원"
                },
                {
                    "item" :"Cake5",
                    "item_op" : "5000원"
                }
            ],
            "sum" :"Total",
            "sum_op" : "15000원"
        },
        "social": {
            "like_count": 100,
            "comment_count": 200,
            "shared_count": 300,
            "view_count": 400,
            "subscriber_count": 500
        },
        "buttons": [
            {
                "title": "웹으로 이동",
                "link": {
                    "web_url": "http://www.daum.net",
                    "mobile_web_url": "http://m.daum.net"
                }
            },
            {
                "title": "앱으로 이동",
                "link": {
                    "android_execution_params": "contentId=100",
                    "ios_execution_params": "contentId=100"
                }
            }
        ]
    }'

리스트 템플릿

리스트 템플릿을 사용하려면 아래와 같이 객체를 구성해야 합니다.

이름	타입	설명	필수
object_type	`String`	`list`로 고정	O
header_title	`String`	리스트 상단에 노출되는 메인 타이틀, 최대 200자	O
header_link	`Link`	헤더 타이틀 내용에 해당하는 링크 정보	O
contents	`Content[]`	리스트에 노출되는 콘텐츠 목록, 2개 이상 필수, 최대 3개	O
button_title	`String`	기본 버튼 타이틀("자세히 보기")을 변경하고 싶을 때 설정	X
buttons	`Buttons[]`	버튼 목록, 최대 2개 버튼 타이틀과 링크를 변경하고 싶을 때, 버튼 두 개를 넣고 싶을 때 사용	X

// 리스트 템플릿 메시지의 template_object 구성 예시
    {
        "object_type": "list",
        "header_title": "WEEKELY MAGAZINE",
        "header_link": {
            "web_url": "http://www.daum.net",
            "mobile_web_url": "http://m.daum.net",
            "android_execution_params": "main",
            "ios_execution_params": "main"
        },
        "contents": [
            {
                "title": "자전거 라이더를 위한 공간",
                "description": "매거진",
                "image_url": "https://mud-kage.kakao.com/dn/QNvGY/btqfD0SKT9m/k4KUlb1m0dKPHxGV8WbIK1/openlink_640x640s.jpg",
                "image_width": 640,
                "image_height": 640,
                "link": {
                    "web_url": "http://www.daum.net/contents/1",
                    "mobile_web_url": "http://m.daum.net/contents/1",
                    "android_execution_params": "/contents/1",
                    "ios_execution_params": "/contents/1"
                }
            },
            {
                "title": "비쥬얼이 끝내주는 오레오 카푸치노",
                "description": "매거진",
                "image_url": "https://mud-kage.kakao.com/dn/boVWEm/btqfFGlOpJB/mKsq9z6U2Xpms3NztZgiD1/openlink_640x640s.jpg",
                "image_width": 640,
                "image_height": 640,
                "link": {
                    "web_url": "http://www.daum.net/contents/2",
                    "mobile_web_url": "http://m.daum.net/contents/2",
                    "android_execution_params": "/contents/2",
                    "ios_execution_params": "/contents/2"
                }
            },
            {
                "title": "감성이 가득한 분위기",
                "description": "매거진",
                "image_url": "https://mud-kage.kakao.com/dn/NTmhS/btqfEUdFAUf/FjKzkZsnoeE4o19klTOVI1/openlink_640x640s.jpg",
                "image_width": 640,
                "image_height": 640,
                "link": {
                    "web_url": "http://www.daum.net/contents/3",
                    "mobile_web_url": "http://m.daum.net/contents/3",
                    "android_execution_params": "/contents/3",
                    "ios_execution_params": "/contents/3"
                }
            }
        ],
        "buttons": [
            {
                "title": "웹으로 이동",
                "link": {
                    "web_url": "http://www.daum.net",
                    "mobile_web_url": "http://m.daum.net"
                }
            },
            {
                "title": "앱으로 이동",
                "link": {
                    "android_execution_params": "main",
                    "ios_execution_params": "main"
                }
            }
        ]
    }'

* header_image_url, header_image_width, header_image_height: Deprecated, 헤더 영역 배경 이미지, 공지 참고

커머스 템플릿

커머스 템플릿을 사용하려면 아래와 같이 객체를 구성해야 합니다.

이름	타입	설명	필수
object_type	`String`	`commerce`로 고정	O
content	`Content`	메시지의 콘텐츠 정보	O
commerce	`Commerce`	상품 이름 및 가격 정보	O
button_title	`String`	기본 버튼 타이틀("자세히 보기")을 변경하고 싶을 때 설정	X
buttons	`Buttons[]`	버튼 목록, 최대 2개 버튼 타이틀과 링크를 변경하고 싶을 때, 버튼 두 개를 넣고 싶을 때 사용	X

// 커머스 템플릿 메시지 구성을 위한 template_object 구성 예시
{
  "object_type": "commerce",
  "content": {
    "title": "Ivory long dress (4 Color)",
    "image_url": "https://mud-kage.kakao.com/dn/RY8ZN/btqgOGzITp3/uCM1x2xu7GNfr7NS9QvEs0/kakaolink40_original.png",
    "image_width": 640,
    "image_height": 640,
    "link": {
      "web_url": "https://style.kakao.com/main/women/contentId=100",
      "mobile_web_url": "https://style.kakao.com/main/women/contentId=100",
      "android_execution_params": "contentId=100",
      "ios_execution_params": "contentId=100"
    }
  },
  "commerce": {
    "regular_price": 208800,
    "discount_price": 146160,
    "discount_rate": 30
  },
  "buttons": [
    {
      "title": "구매하기",
      "link": {
        "web_url": "https://style.kakao.com/main/women/contentId=100/buy",
        "mobile_web_url": "https://style.kakao.com/main/women/contentId=100/buy",
        "android_execution_params": "contentId=100&buy=true",
        "ios_execution_params": "contentId=100&buy=true"
      }
    },
    {
      "title": "공유하기",
      "link": {
        "web_url": "https://style.kakao.com/main/women/contentId=100/share",
        "mobile_web_url": "https://style.kakao.com/main/women/contentId=100/share",
        "android_execution_params": "contentId=100&share=true",
        "ios_execution_params": "contentId=100&share=true"
      }
    }
  ]
}

위치 템플릿

위치 템플릿을 사용하려면 아래와 같이 객체를 구성해야 합니다.

이름	타입	설명	필수
object_type	`String`	`location`로 고정	O
address	`String`	공유할 위치의 주소 (예: 경기 성남시 분당구 판교역로 235)	O
address_title	`String`	카카오톡 내의 지도 뷰에서 사용되는 타이틀 (예: 카카오판교오피스)	X
content	`Content`	위치에 대해 설명하는 콘텐츠 정보	O
social	`Social`	부가적인 소셜 정보	X
button_title	`String`	기본 버튼 타이틀("자세히 보기")을 변경하고 싶을 때 설정	X
buttons	`Buttons[]`	버튼 목록, 최대 2개 버튼 타이틀과 링크를 변경하고 싶을 때, 버튼 두 개를 넣고 싶을 때 사용	X

// 위치 템플릿 메시지 구성을 위한 template_object 구성 예시
{
  "object_type": "location",
  "content": {
    "title": "카카오 판교오피스",
    "description": "카카오 판교오피스 위치입니다.",
    "image_url": "https://mud-kage.kakao.com/dn/drTdbB/bWYf06POFPf/owUHIt7K7NoGD0hrzFLeW0/kakaolink40_original.png",
    "image_width": 800,
    "image_height": 800,
    "link": {
      "web_url": "https://developers.kakao.com",
      "mobile_web_url": "https://developers.kakao.com/mobile",
      "android_execution_params": "platform=android",
      "ios_execution_params": "platform=ios"
    }
  },
  "buttons": [
    {
      "title": "웹으로 보기",
      "link": {
        "web_url": "https://developers.kakao.com",
        "mobile_web_url": "https://developers.kakao.com/mobile"
      }
    }
  ],
  "address": "경기 성남시 분당구 판교역로 235 에이치스퀘어 N동 7층",
  "address_title": "카카오 판교오피스"
}

텍스트 템플릿

텍스트 템플릿을 사용하려면 아래와 같이 객체를 구성해야 합니다.

이름	타입	설명	필수
object_type	`String`	`text`로 고정	O
text	`String`	텍스트 정보, 최대 200자	O
link	`Link`	콘텐츠 클릭 시 이동할 링크 정보	O
button_title	`String`	기본 버튼 타이틀("자세히 보기")을 변경하고 싶을 때 설정	X
buttons	`Buttons[]`	버튼 목록, 최대 2개 버튼 타이틀과 링크를 변경하고 싶을 때, 버튼 두 개를 넣고 싶을 때 사용	X

// 텍스트 템플릿 메시지 구성을 위한 template_object 구성 예시
{
  "object_type": "text",
  "text": "텍스트 영역입니다. 최대 200자 표시 가능합니다.",
  "link": {
    "web_url": "https://developers.kakao.com",
    "mobile_web_url": "https://developers.kakao.com"
  },
  "button_title": "바로 확인"
}

캘린더 템플릿

캘린더 템플릿을 사용하려면 아래와 같이 객체를 구성해야 합니다.

이름	타입	설명	필수
object_type	`String`	`calendar`로 고정	O
id_type	`String`	`id`의 타입, `event`(공개 일정) 또는 `calendar`(구독 캘린더) 중 하나 중요: `id_type`에 따라 기본 버튼이 아래의 지정된 문구로 출력됨 공개 일정 ID: [일정 등록 하기] 구독 캘린더 ID: [캘린더 구독하기]	O
id	`String`	공개 일정 또는 구독 캘린더 ID	O
content	`Content`	일정 제목과 설명	O
buttons	`Buttons[]`	사용자 정의 버튼 정보, 최대 1개의 버튼 정보만 사용됨 캘린더 메시지는 기본적으로 공개 일정 추가 또는 구독 캘린더 구독을 위한 기본 버튼을 제공하고, 1개의 사용자 정의 버튼을 선택적으로 추가 가능	X

// 캘린더 템플릿 메시지 구성을 위한 template_object 구성 예시
{
  "object_type": "calendar",
  "content": {
    "title": "일정 제목",
    "description": "일정 설명",
    "image_url": "https://developers.kakao.com/static/images/pc/txt_visual1.png",
    "link": {
      "web_url": "https://kakao.com"
    }
  },
  "buttons": [
    {
      "title": "일정 정보 보기",
      "link": {
        "web_url": "https://developers.kakao.com",
        "mobile_web_url": "https://developers.kakao.com/mobile"
      }
    }
  ],
  "id_type": "event",
  "id": "6351f57c7ec8e318d0b809a0"
}

공통 구성 요소

메시지 템플릿을 구성하는 공통 요소를 설명합니다.

Content

메시지 제목, 본문, 이미지 정보와 같은 메시지의 기본 콘텐츠 정보를 담는 객체입니다.

이미지의 경우, URL로 전달해야 하며, RFC2396, RFC1034, RFC1123를 준수해야 합니다. 규격에 맞지 않는 이미지 URL은 이미지가 보이지 않습니다.

이름	타입	설명	필수
title	`String`	콘텐츠의 타이틀	O*
image_url	`String`	콘텐츠의 이미지 URL	O*
image_width	`Int`	콘텐츠의 이미지 너비, 픽셀 단위	X
image_height	`Int`	콘텐츠의 이미지 높이, 픽셀 단위	X
description	`String`	콘텐츠의 상세 설명, title과 합쳐 최대 4줄 표시	O*
link	`Link`	콘텐츠 클릭 시 이동할 링크 정보	O

* title, image_url, description 중 하나 필수

Button

메시지에 포함되는 버튼의 정보를 담는 객체입니다. 버튼의 텍스트와 클릭 시 동작을 정의합니다.

메시지 구성 시 buttonTitle, buttons 모두 주어졌다면 buttons를 우선 사용합니다. 둘 다 주어지지 않았을 때에는 기본 타이틀과 content에 있는 link 정보로 버튼 하나가 구성됩니다.

이름	타입	설명	필수
title	`String`	버튼의 타이틀	O
link	`Link`	버튼 클릭 시 이동할 링크 정보(하나는 필수로 존재해야 함)	O

Link

메시지에서 콘텐츠 영역이나 버튼 선택 시 이동할 링크 정보를 담은 객체입니다.

기본 템플릿의 웹 링크와 앱 링크는 앱 관리 페이지의 [앱] > [제품 링크 관리]에 설정된 기본 웹 도메인과 기본 네이티브 앱 스킴이 적용됩니다. 자세한 내용은 해당 항목의 내용을 확인합니다.

링크는 플랫폼별로 각각 설정할 수 있으며, 사용자의 카카오톡 실행 환경에 따라 적합한 링크가 적용됩니다. 웹 링크는 PC/Mac, Android, iOS 모두 지원하며, Android와 iOS 앱 링크는 해당 플랫폼에서만 버튼에 적용됩니다. 자세한 사항은 링크 동작 방식을 참고합니다.

메시지에 링크를 적용하려면 link의 필드 중 최소 하나 이상 설정 필수이며, 링크 설정이 없거나 사용자의 카카오톡 실행 환경에서 사용할 수 있는 링크 설정이 없다면 메시지 콘텐츠 영역에 링크가 적용되지 않거나 버튼이 나타나지 않습니다.

이름	타입	설명	필수
web_url	`String`	PC버전 카카오톡에서 사용하는 웹 링크 URL 도메인은 앱 관리 페이지의 [앱] > [제품 링크 관리] > [웹 도메인]에 등록한 도메인 중 하나와 일치해야 함	O*
mobile_web_url	`String`	모바일 카카오톡에서 사용하는 웹 링크 URL 도메인은 앱 관리 페이지의 [앱] > [제품 링크 관리] > [웹 도메인]에 등록한 도메인 중 하나와 일치해야 함	O*
android_execution_params	`String`	안드로이드 카카오톡에서 사용하는 앱 링크 URL에 사용될 파라미터 해당 값이 없을 경우 mobile_web_url 이용	O*
ios_execution_params	`String`	iOS 카카오톡에서 사용하는 앱 링크 URL에 사용될 파라미터 해당 값이 없을 경우 mobile_web_url 이용	O*

* web_url, mobile_web_url, android_execution_params, ios_execution_params 중 하나 필수

Social

콘텐츠의 좋아요, 댓글, 공유, 조회, 구독 수 등 소셜 지표를 표시하는 영역을 표시하기 위한 객체입니다.

이름	타입	설명	필수
like_count	`Int`	콘텐츠의 좋아요 수	X
comment_count	`Int`	콘텐츠의 댓글 수	X
shared_count	`Int`	콘텐츠의 공유 수	X
view_count	`Int`	콘텐츠의 조회 수	X
subscriber_count	`Int`	콘텐츠의 구독 수	X

ItemContent

피드 B형 템플릿에서 사용할 수 있는 텍스트 아이템 정보입니다.

이름	타입	설명	필수
profile_text	`String`	헤더 또는 프로필 영역에 출력될 텍스트 `profile_image_url` 값이 없을 경우, 볼드(Bold)체로 된 제목만 담은 헤더 형태로 출력됨 최대 16자까지 출력	X
profile_image_url	`String`	프로필 영역에 출력될 이미지 작은 원형의 프로필 사진 형태로 출력됨	X
title_image_text	`String`	이미지 아이템의 제목 최대 2줄, 최대 24자까지 출력	X
title_image_url	`String`	이미지 아이템의 이미지 URL 이미지 사이즈: iOS: 108x108 Android: 98x98 1:1 비율이 아닌 이미지는 센터 크롭(Center crop) 방식으로 재조정됨	X
title_image_category	`String`	이미지 아이템의 제목 아래에 회색 글씨로 출력되는 카테고리 정보 최대 한 줄, 최대 14자까지 출력	X
items	`ItemInfo[]`	각 텍스트 아이템 정보 아이템 이름과 가격에 해당하는 `item`, `item_op`를 포함한 `JSON` 배열, 최대 5개의 아이템 지원 (예: `[{"item": "item1 name", "item_op": "item1_description"}, {"item": "item2 name", "item_op": "item2_description"}]`) 참고: 피드 B형 템플릿 [G] 영역	X
sum	`String`	주문금액, 결제금액 등 아이템 영역의 요약 정보 제목 텍스트 아이템 영역 아래에 최대 6자까지 출력 참고: 피드 B형 템플릿 [H] 영역	X
sum_op	`String`	아이템 영역의 가격 합산 정보 텍스트 아이템 영역 아래에 볼드체로 최대 11자까지 출력 참고: 피드 B형 템플릿 [H] 영역	X

ItemInfo

텍스트 아이템 목록 중 하나의 텍스트 아이템에 대한 정보입니다.

이름	타입	설명	필수
item	`String`	아이템 이름 최대 6자까지 출력	O
item_op	`String`	아이템 가격 사용 가능한 문자: 숫자, 통화기호, 쉼표(,), 마침표(.), 띄어쓰기 소수 단위 금액을 포함한 경우, 소수점 아래 2자리까지만 사용 권장 최대 2줄, 1줄인 경우 최대 14자, 2줄인 경우 최대 25자까지 출력	O

Commerce

상품 정보를 나타낼수 있는 텍스트 아이템 정보입니다.

이름	타입	설명	필수
product_name	`String`	상품 이름 및 제목, 최대 2줄 출력 상품 가격보다 위에 검은 글씨로 출력	X
regular_price	`Int`	정상 가격	O
discount_price	`Int`	할인된 가격	X
discount_rate	`Int`	할인률	X
fixed_discount_price	`Int`	정액 할인 가격, 할인율과 동시 사용 불가	X
currency_unit	`String`	통화 단위 또는 기호 (예: 원, USD, ₩, $ 등) (기본값: 원)	X
currency_unit_position	`Int`	통화 단위 표시 위치 `0`: 가격 뒤에 표시 `1`: 가격 앞에 표시 (기본값: `0`)	X

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기