Concepts

This document introduces message templates.

Overview

A message template is the format of a message sent via Kakao Talk Share and Kakao Talk Message. The service selects the message format from the template types and configures the details through the components of each message template.

Template types

This section introduces the types of message templates provided by Kakao. See the image and description below.

Template	Description
Feed	A basic message format composed of images and text. Offers Feed A type, which consists of an image and text, and Feed B type, which supports a list of image or text items. The Scrap Message is based on the feed template structure and constructs a message format by retrieving webpage information from a requested URL using the Open Graph Protocol. Recommended use: Delivering a single piece of content or sharing a webpage.
List	A message format that displays one or more content items in a vertical list. Each item can be composed of an image and text. Recommended use: Delivering multiple pieces of content in a single message.
Location	A message format that includes location information. Selecting the location button in the message allows users to view detailed place information on Kakao Map. Recommended use: Delivering content that includes location information.
Commerce	A message format that shows detailed product information, including pricing. Recommended use: Delivering product information including price (original price, discounted price, discount rate).
Text	A message format composed of text only. Recommended use: Delivering content composed of text only.
Calendar	A message format that includes public events or subscribed calendar information from Talk Calendar. Only KakaoTalk Channel information connected to the service app can be included. Recommended use: Delivering content that includes service schedule information.

How to use

Message templates can be used in the two ways below.

• Using default template: A method to include component values in the message sending API request in JSON or object format according to the format specified for each template. You can directly specify the message components.
• Using custom template: A method to create and register a template with the desired structure and content in [Tools] > [Message Template Builder], and use it. This is only available for messages that support custom templates, and parts of the message components can be specified through user arguments.

Availability of custom templates

Item	Custom template
Feed	Available.
List	Available.
Location	Not available.
Commerce	Available.
Text	Available. Can be registered by editing a feed template.
Calendar	Not available.
Scrap	Available. Supports default scrap keys for each component (See: Scrap message).

* Using default template is available for all templates.

User argument

This is a feature that allows you to define variables for certain components of a message so that actual values can be inserted at the time of sending, when using custom templates created with the message template tool. See the usage guide below.

1. Set the key in the ${KEY} format at the location where a user argument should be used when registering a custom template.
   • Only English characters, numbers, and underscore(_) are allowed.
2. Pass the value of each key when requesting to send a message. (Example: {"${KEY}":"${VALUE}"})

Components by message type

You can configure the components of a message template to send messages in the desired format.

All message templates include an app launch link at the bottom, and you can optionally add buttons that contain the execution path of a web page or app. Other components must be configured using predefined combinations specific to each message type.

Below is the detailed information on the components of the message template. Class and field names are referenced to the REST API, with the names in the Kakao SDK described separately.

• Feed message
  • Feed A type
  • Feed B type
• List message
• Location message
• Commerce message
• Text message
• Scrape message
• Calendar message
• Common components
  • content
  • social
  • button
  • link

Feed message

The Feed template, provided as the default template, consists of a piece of content and a button as a default. You can add social information or one more button as needed. Configure the default Feed message through template_object.

Feed A type

🅐 Image: You can add an image with a minimum size of 400x400 pixels. If you configure a custom template in the Message template builder, up to three images are allowed. For more details, see Message template builder > Image. 🅑 Text: You can enter up to two lines of title and two lines of description. 🅒 Social: You can register five social information but only up to three items are displayed and sorted with this priority: [Like] > [Comment] > [Share] > [View] > [Subscribe]. 🅓 Button: You can add up to two buttons. 8 characters or less are recommended for the button name.

Feed B type

You can use the extended version of a feed message by adding multiple items and their information. You can use this message type for a receipt, menu, or product description.

To use the Feed B type of a message, add the item_content object inside template_object. The rest components (🅐 to 🅓) are the same as the Feed A type.

🅔 Profile/Header: You can set the profile information with a profile image or only the text without an image. 🅕 Image item: You can add a specific item name with an image and its category information. Only one Image item is allowed. 🅖 Text item: You can add a list of text items that consists of the item's name and description. Up to five items are allowed. 🅗 Summary information: You can add summary information that consists of Name and Description.

template_object (SDK: FeedTemplate)

Name	Type	Description	Area	Required
object_type SDK: objectType	String	Template type. Fixed to feed.	-	O
content	Content	Main content information of the message.	🅐,🅑	O
item_content SDK: itemContent	ItemContent	Components for the extended version of a Feed message. Required if you configure the Feed B type of a message.	🅔,🅕,🅖,🅗	X
social	Social	Social information about the content.	🅒	X
button_title SDK: buttonTitle	String	Used when you want to change the title of the default button ("자세히 보기").	🅓	X
buttons	Buttons[] Android,Flutter: List<Button> iOS: [Button]	List of buttons. Up to two buttons are allowed. Used when you want to change the title and link of a button or add two buttons.	🅓	X

item_content (SDK: ItemContent)

Name	Type	Description	Area	Required
profile_text SDK: profileText	String	Text in the Profile or Header area. If profile_image_url is not set, only text is displayed. Character limits*: 27 in a line (16 in Korean)	🅔	X
profile_image_url SDK: profileImageUrl	String Flutter: Uri iOS: URL	Image in the Profile area.	🅔	X
title_image_text SDK: titleImageText	String	Title of the image item. Character limits*: 40 in two lines. (24 in Korean)	🅕	X
title_image_category SDK: titleImageCategory	String	Category of the image item. Character limits*: 24 in a line (14 in Korean)	🅕	X
title_image_url SDK: titleImageUrl	String Flutter: Uri iOS: URL	URL of the image displayed at the right side of title_image_text. Image size: 98x98 pixels on Android, 108x108 pixels on iOS. If the image is not 1:1 aspect ratio, center-cropped.	🅕	X
items	ItemInfo[] Android,Flutter: List<ItemInfo> iOS: [ItemInfo]	List of the text items that consists of item and item_op. (Example: [{"item": "item1 name", "item_op": "item1 description"}, {"item": "item2 name", "item_op": "item2 description"}]) Up to five items are allowed. See items: Text item information.	🅖	X
sum	String	Name of summary information. Can be used for Total price or amount. (Example: Total) Character limits*: 6 Important: Only displayed when one or more item is set and when both sum and sum_op are set.	🅗	X
sum_op SDK: sumOp	String	Description of summary information. Can be used for the total price or amount. (Example: 999,999 USD, $99.99) Character limits*: 19 in a line (14 in Korean) Recommended characters: numbers, decimal numbers to hundredths, period(.), comma(,), currency unit or currency symbol, white space Important: Only displayed when one or more item is set and when both sum and sum_op are set. Note: Left-aligned by default. If sum and sum_op are set, right-aligned.	🅗	X

*Character limits are calculated on the Android device with resolution 2400 × 1080 pixels (FHD+), and may be different depending on devices.

items: Text item information

Name	Type	Description	Area	Required
item	String	Item name. Character limits*: 6 Important: Only displayed when both item and item_op are set.	🅖	O
item_op SDK: itemOp	String	Item description. Character limits*: 49 in two lines. (25 in Korean) Important: Only displayed when both item and item_op are set. Note: Left-aligned by default. If sum and sum_op are set, right-aligned.	🅖	O

*Character limits are calculated on the Android device with resolution 2400 × 1080 pixels (FHD+), and may be different depending on devices.

List message

The List template consists of a header title displayed at the top of the message, lists, and a button as a default. Configure the default List message through template_object. You can add a link for each header and content and one more button as needed.

🅐 Header 🅑 List: Up to three items are allowed by default. If you use a custom template, up to five lists are allowed. 🅒 Title/description: You can enter up to two lines of title and one line of description. 🅓 Image: You can add a single image on each list. Minimum size: 200x200 pixels. Maximum file size: 5 MB. 🅔 Button: You can add up to two buttons. 8 characters or less are recommended for the button name.

template_object (SDK: ListTemplate)

Name	Type	Description	Area	Required
object_type SDK: objectType	String	Template type. Fixed to list.	-	O
header_title SDK: headerTitle	String	Main title displayed at the top of list. Up to 200 characters are allowed.	🅐	O
header_link SDK: headerLink	Link	Link information corresponding to the content of the title.	🅐	O
contents	Content[] Android,Flutter: List<Content> iOS: [Content]	List of contents displayed on the list. Two or more contents required. Up to three contents are allowed.	🅑	O
button_title SDK: buttonTitle	String	Used when you want to change the title of the default button ("자세히 보기").	🅔	X
buttons	Buttons[] Android,Flutter: List<Button> iOS: [Button]	Button list. Up to two buttons are allowed. Used when you want to change the button title and link or to add two buttons.	🅔	X

Location message

The Location template consists of address information to display the location on a map and the content object describing the location. Configure the Location message through template_object.

The [View Location] button to show a map is added at the bottom right next to the default button. If users click [View Location], they can see the location address on the switched map screen in the Kakao Talk chatroom.

🅐 Image: You can upload only one image. Recommended image size: 800x800 pixels or more. 🅑 Text: You can enter up to two lines of title and two lines of description. 🅒 Social: You can register five kinds of social information but only up to three items are displayed and sorted with this priority: [Like] > [Comment] > [Share] > [View] > [Subscriber]. 🅓 Button: You can add up to two buttons. 8 characters or less are recommended for the button name.

template_object (SDK: LocationTemplate)

Name	Type	Description	Area	Required
object_type SDK: objectType	String	Template type. Fixed to location.	-	O
address	String	Address of location to be shared. (Example: 235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do)	-	O
address_title SDK: addressTitle	String	Title used for Map view in Kakao Talk. (Example: Kakao Pangyo Office)	-	X
content	Content	Content information that describes the location.	🅐,🅑	O
social	Social	Additional social information.	🅒	X
button_title SDK: buttonTitle	String	Used when you want to change the title of the default button ("자세히 보기").	🅓	X
buttons	Buttons[] Android,Flutter: List<Button> iOS: [Button]	Button list. Up to two buttons are allowed. Used when you want to change the button title and link or to add two buttons.	🅓	X

Commerce message

The Commerce messages consist of an image, product information, content, and buttons. With the Commerce template provided as a default, you can contain only one product information with one button. Configure the default Commerce message through template_object. If you want to show multiple product information, you must configure a custom message.

🅐 Image: You can upload only one image with a size of 800x800 pixels or more. 🅑 Product name: Product name. Up to two lines are displayed. 🅒 Product information: Discount price(Possible to change the currency symbol and position), regular price, and discount rate. 🅓 Content: Product description. Up to two lines are displayed. 🅔 Button: You can add up to two buttons. 8 characters or less are recommended for the button name.

template_object (SDK: CommerceTemplate)

Name	Type	Description	Area	Required
object_type SDK: objectType	String	Template type. Fixed to commerce.	-	O
content	Content	Content information of a message.	🅐, 🅓	O
commerce	Commerce	Product name and price information. See Commerce.	🅒	O
button_title SDK: buttonTitle	String	Used when you want to change the title of the default button ("자세히 보기").	🅔	X
buttons	Buttons[] Android,Flutter: List<Button> iOS: [Button]	Button list. Up to two buttons are allowed. Used when you want to change the button title and link or to add two buttons.	🅔	X

Commerce (iOS: CommerceDetail, Android/Flutter: Commerce)

Name	Type	Description	Area	Required
product_name SDK: productName	String	Up to two lines of product name or title are displayed in black above the product price.	🅑	X
regular_price SDK: regularPrice	Int	Regular price.	🅒	O
discount_price SDK: discountPrice	Int	Discount price.	🅒	X
discount_rate SDK: discountRate	Int iOS: NSNumber	Discount rate.	🅒	X
SDK: fixedDiscountPrice	Int	Fixed discount price. You cannot use this with discount rate at the same time.	🅒	X
currency_unit SDK: currencyUnit	String	Currency unit or symbol. (Example: 원, Won, USD, ₩, $) (Default: 원)	🅒	X
currency_unit_position SDK: currencyUnitPosition	Int	Position of currency unit or symbol. 0: Place currency symbol after the price. 1: Place currency symbol before the price. (Default: 0)	-	X

Text message

The Text template, provided as a default template, consists of a text area and a button. Configure the Text message through template_object. You can add one more button as needed.

🅐 Text: Up to 200 characters are displayed. 🅑 Button: You can add up to two buttons. 8 characters or less are recommended for the button name.

template_object (SDK: TextTemplate)

Name	Type	Description	Area	Required
object_type SDK: objectType	String	Template type. Fixed to text.	-	O
text	String	Text information. Up 200 characters are displayed.	🅐	O
link	Link	Link information to be redirected when a content is clicked.	🅐	O
button_title SDK: buttonTitle	String	Used when you want to change the title of the default button ("자세히 보기").	🅑	X
buttons	Buttons[] Android,Flutter: List<Button> iOS: [Button]	Button list. Up to two buttons are allowed. Used when you want to change the button title and link or to add two buttons.	🅑	X

Scrape message

You can configure the content of a website using the images, title, descriptions, and links based on information on the web page and send it simply. When the page is scraped, web page information is collected based on the Open Graph Protocol and used for each component. Therefore, when you request to send a scrape message, you do not need to configure message contents separately, except for the contents to be added to the message template through a user argument.

🅐 Image: A representative image of the scraped web page is displayed. 🅑 Text: The title and description of the scraped web page are displayed. Up to two lines for title and description respectively. 🅒 Button: Button name is displayed as specified for the web page in ${SCRAP_HOST}에서 확인 format. Users are directed to the scraped web page with this button tapped.

Default argument keys used for Scrape message

Because the following argument keys are already assigned for a scrape message, you cannot use these names for an argument key. If the requested web page includes the Open Graph Meta tags, each tag value is applied for each argument key to create a scrape message.

Key	Description	Area
ⓐ ${SCRAP_IMAGE} ${SCRAP_IMAGE_WIDTH} ${SCRAP_IMAGE_HEIGHT}	The representative image of the web page set in og:image. ${SCRAP_IMAGE_WIDTH} is the specified width of og:image, and ${SCRAP_IMAGE_HEIGHT} is the specified height of og:image.	🅐
ⓑ ${SCRAP_IMAGE_DURATION}	The music or video duration set in og:music:duration or og:vedio:duration.	🅐
ⓒ ${SCRAP_TITLE}	The title of the web page set in og:title.	🅑
ⓒ ${SCRAP_DESCRIPTION}	The description of the web page set in og:description.	🅑
ⓓ ${SCRAP_HOST}	The name of the web page set in og:site_name. If not specified, the site domain of the requested web page is displayed.	🅒
ⓓ ${SCRAP_REQUESTED_URL}	The address of the requested web page. If a user clicks any of the message component, the web page opens.	🅐,🅑,🅒

Calendar message

The Calendar template consists of an image, text that describes a public event or a subscribed calendar, and a button. You can send a message to encourage users to add a public event or a subscribed calendar to their calendar by using the Calendar template. For more details, see Talk Calendar > Concepts.

🅐 Image: You can upload only one image. 🅑 Text: The title and description of the calendar or event are displayed. You can enter up to two lines of title and two lines of description. 🅒 Button: You can add up to two buttons, including either [일정 등록하기(Add event)] or [캘린더 구독하기(Subscribe calendar)] button (ⓐ).

template_object (SDK: CalendarTemplate)

Name	Type	Description	Area	Required
object_type	String	Template type. Fixed to calendar.	-	O
id_type	String iOS: IdType	Either event or calendar. Depending on the value of id_type, the button name on a calendar message and how the button works when it is invoked are different.	-	O
id	String	If you set id_type to event, input a public event ID. If you set id_type to calendar, input a subscribed calendar ID in subscribe_{ID} format.	-	O
contents	Content JavaScript: ContentObject	Content information about the public event or subscribed calendar.	🅐, 🅑	O
buttons	Buttons[] JavaScript: Array. Android,Flutter: List<Button> iOS: [Button]	Button list. Used to add one more button (ⓑ), besides [일정 등록하기(Add event)] or [캘린더 구독하기(Subscribe calendar)] button (ⓐ). Note: ⓐ button supports Korean only.	🅒	X

How a button on calendar message works

id_type	id	Button name	Action
event	Public event ID	일정 등록하기(Add event)	If a user selects this button in a mobile environment, the public event is automatically added to the user's calendar under the Talk Calendar category. In the web version of Talk Calendar, the page where a user can add the event is displayed. The user can add the event after logging into Talk Calendar. If reminders are set for the added public event, a notification message is sent from Talk Calendar. You can customize the [공유하기] button (ⓒ) on the notification message by setting EventReminder.
calendar	Subscribed calendar ID	캘린더 구독하기(Subscribe calendar)	If selected, the subscribed calendar is added to a user's calendar under the Subscribed Calendar category, and all events of the subscribed calendar are added. This button only works in a mobile environment.

Common components

content Object (SDK: Content)

Name	Type	Description	Required
title	String	Title of the content.	O*
image_url SDK: imageURL	String Flutter: Uri iOS: URL	Image URL in the content.	O*
image_width SDK: imageWidth	Int	Image width of the content in pixels.	X
image_height SDK: imageHeight	Int	Image height of the content in pixels.	X
description	String	Detailed description of the content. Up to four lines including the content title are displayed.	O*
link	Link	Link information to be redirected to when a a content is clicked.	O

* One of title, image_url, description is required.

The image included in the content area must meet the following conditions, and you must pass the URL for the image when you request to send a message.

• The image URL must comply with RFC2396, RFC1034, and RFC1123. If not, the image is not displayed.
• The image size must be 200x200 pixels or higher.
• The image file size must not exceed 5 MB.

social Object (SDK: Social)

Name	Type	Description	Required
like_count SDK: likeCount	Int	Number of likes for the content.	X
comment_count SDK: commentCount	Int	Number of comments on the content.	X
shared_count SDK: sharedCount	Int	Number of contents shared.	X
view_count SDK: viewCount	Int	Number of content views.	X
subscriber_count SDK: subscriberCount	Int	Number of subscriptions to the content.	X

This object includes social information, such as the number of likes and comments. Only up to three out of five properties are displayed and sorted with the priority: [Like] > [Comment] > [Shared] > [View] > [Subscriber].

button Object (SDK: Button)

Name	Type	Description	Required
title	String	Button title.	O
link	Link	Link information to be redirected to when a button is clicked. (At least one is required.)	O

If the values both for buttonTitle and buttons are given when configuring a message, the value of buttons is applied. When neither value is given, the link information of link on the content object is applied for a button.

link Object (SDK: Link)

Name	Type	Description	Required
web_url SDK: webURL	String Flutter: Uri iOS: URL	The web link URL used in PC version of Kakao Talk. The domain of the URL must match the domain registered on the Kakao developers.	O*
mobile_web_url SDK: mobileWebURL	String Flutter: Uri iOS: URL	The web link URL used in mobile version of Kakao Talk. The domain of URL must match the domain registered on the Kakao Developers.	O*
android_execution_params SDK: androidExecutionParams	String	The parameter used for the app link URL used in Kakao Talk for Android. If not specified, mobile_web_url is applied.	O*
ios_execution_params SDK: iosExecutionParams	String	The parameter used for the app link URL used in Kakao Talk for iOS. If not specified, mobile_web_url is applied.	O*

* One of web_url, mobile_web_url, android_execution_params, ios_execution_params is required.

This object contains link information to redirect users when a button or content in a message is clicked. You can set different links for each environment, and each link is applied according to the user's environment where the Kakao Talk app is running. The Web link is applicable in all environments: PC (+Mac), Android, and iOS. The Android and iOS links are only applied to the corresponding platforms.

To apply a link to a message, you must set at least one of the link fields. If you have not set any link field or have set a link but the link is not available on the user's environment where Kakao Talk runs, the link is not applied, or the button does not appear in the message content area.

How links are applied

This illustration shows which link is applied according to platform or condition.

When users click a button or content on a message, users are directed to each link with the following priorities:

1. Link to launch app: Opens your service app that is allowed to launch through Custom scheme setting.
2. Link to Open market: Directs to Market URL when your app is not installed on a user's device.
3. Link to mobile web: Directs to the URL set as mobile_web_url. If multiple domains are set in the Web platform, the first domain available to land is used as a default among the registered domains.
4. Link to PC web: Directs to the URL set as webURL. If multiple domains are set in the Web platform, the first domain available to land is used as a default among the registered domains.

Here are the examples to show the priorities to work the links:

Example 1

Platform/Parameter settings	Links applied to actual message
Platform registered in Common link settings: Web and Android Message link parameter specified in Button link settings:    android_execution_params	Buttons: Displayed on all PC (+Mac), Android, and iOS devices. Links: Android link is applied for Android devices. Web link is applied for PC (+Mac) and iOS devices (Common link).

Example 2

Platform/Parameter settings	Links applied to actual message
Platform registered in Common link settings: Android and iOS Message link parameter specified in Button link settings:    android_execution_params, ios_execution_params	Buttons: Displayed on Android and iOS devices only. Links: Android link is applied for Android devices. iOS link is applied for iOS devices.

Example 3

Platform/Parameter settings	Links applied to actual message
Platform registered in Common link settings: Web Message link parameter specified in Button link settings:    web_url, mobile_web_url	Buttons: Displayed on all PC(+Mac), Android, and iOS devices. Links: Web link is applied.

Example 4

Platform/Parameter settings	Links applied to actual message
Platform registered in Common link settings: iOS Message link parameter specified in Button link settings:    web_url, mobile_web_url	Buttons: Displayed on all PC(+Mac), Android, and iOS devices. Links: Web link is applied.