Migrate Kakao Chingu API to Brand Message API

Use this page to migrate from the Kakao Chingu API to the Brand Message API. It explains the key technical differences, validation rules, and required changes you must implement before moving to production.

This page is intended for users that already use Kakao Chingu messaging. It does not cover first-time Kakao onboarding.

Important: Conduct thorough end-to-end testing of the Brand Message API before moving the migration into production.

For detailed usage, constraints, and the latest updates, refer to the Kakao Brand Message API documentation (opens in a new tab).

Kakao Chingu message types

Kakao Chingu supports two main message types:

1. Standard Chingu messages: Basic message formats without targeting options.
2. Brand Message free-form messages: Enhanced, dynamic messages that require explicit targeting and support additional features.

Targeting

Targeting defines the recipient eligibility for a message. When you send a Brand Message free-form message, you must declare which users Kakao is permitted to deliver the message to.

Kakao distinguishes between two user groups:

1. Channel friends
2. Channel subscribers

Targeting specifies which of these user groups the message is allowed to reach. Kakao enforces targeting at delivery time and blocks message delivery to users who do not match the specified targeting.

Example: If targeting is set to channel friends, a user who is only a subscriber will not receive the message. If targeting is missing, the message is rejected.

Brand Message free-form targeting

Brand Message free-form messages require targeting with one of the following values:

• ALL_CONSENT
• TARGETED_FRIENDS, or specific codes (M, N, I,).

Kakao Chingu and Brand Message button types and validation

Standard Chingu messages support four button types:

1. URL
2. APP_LINK
3. BOT_KEYWORD
4. MESSAGE_DELIVERY

Brand Message messages support the Standard Chingu message button types and two additional button types:

1. BUSINESS_FORM (requires pre-registration)
2. ADD_CHANNEL (for channel subscription)

Coupons

Coupons are supported across all Brand Message free-form message types with type-specific limits.

Character limits and content structure

The table below compares character limits and content structure for Standard Chingu and Brand Message free-form message types in Kakao Chingu.

Message type	Main text limit	Targeting required	Coupon support	Button limit	Button text limit	Content order rules
TEXT (Standard)	1,000	Not supported	Optional (Standard Coupon)	Up to 5	14 characters	No restrictions
TEXT_FREE_FORM	1,300	Required	Optional (Standard Coupon)	Up to 5 (4 with coupon)	14 characters	When both ADD_CHANNEL and BUSINESS_FORM buttons are included, ADD_CHANNEL must be first. Otherwise, BUSINESS_FORM must be first.
IMAGE (Standard)	1,000	Optional	Optional (Standard Coupon)	Up to 5	14 characters	No restrictions
IMAGE_FREE_FORM	1,300	Required	Optional (Standard Coupon)	Up to 5 (4 with coupon)	14 characters	BUSINESS_FORM must be first. Otherwise, if ADD_CHANNEL is listed, ADD_CHANNEL must be first.
IMAGE_WIDE (Standard)	1,000	Optional	Optional (Standard Coupon)	Up to 5	14 characters	No restrictions
IMAGE_WIDE_FREE_FORM	76	Required	Optional (ImageWideFreeFormCoupon, 18 character limit)	Up to 2	8 characters	BUSINESS_FORM must be last. Otherwise, if ADD_CHANNEL is listed, ADD_CHANNEL must be last.
ITEM_LIST (Standard)	Not applicable (header + items)	Optional	Optional (Standard Coupon)	Up to 2	14 characters	No restrictions
ITEM_LIST_FREE_FORM	Not applicable (header max 20 + items)	Required	Optional (ItemListFreeFormCoupon, 18 character limit)	Up to 2	8 characters	BUSINESS_FORM must be last. Otherwise, if ADD_CHANNEL is listed, ADD_CHANNEL must be last.

Message content model differences

This section provides differences and validation changes for each content type when migrating from Standard Kakao Chingu messages to Brand Message free-form messages.

Content model changes by message type (Standard → free-form)

Message type	Change category	Standard Chingu	Brand Message free-form	Migration impact
Carousel	Element capacity	Up to 10 elements	Up to 6 elements	Reduce element count
	Head element	Not supported	Optional head supported	Update payload structure
	Text field name	text	message	Rename field
	Button model	Text buttons	Rich content buttons	Replace button type
	ADD_CHANNEL usage	Multiple allowed	Only one across carousel	Enforce cross-element validation
Commerce	Title requirement	Optional	Required	Ensure title is always present
	Discount minimum	Minimum 1	Minimum 0	Adjust validation logic
	Coupon description	No limit	Max 12 characters	Shorten coupon content
	Button ordering	Not enforced	Strictly enforced	Apply ordering validation
Carousel Commerce	Element capacity	Up to 10 elements	Up to 6 elements	Reduce element count
	Button model	Text buttons	Rich content buttons	Replace button type
	ADD_CHANNEL usage	Multiple allowed	Only one across all elements	Enforce global constraint
Premium Video	Text field name	text	content	Rename field
	Video model	Video	FreeFormVideo	Update video payload
	Button structure	List (size = 1)	Single button object	Refactor structure
	Coupon description	No limit	Max 18 characters	Shorten coupon content
Buttons (global)	Button model	TextButton	RichContentFreeFormButton	Replace button classes
	Button types	4 types	6 types	Support new buttons
	New buttons	Not available	BUSINESS_FORM, ADD_CHANNEL	Add support
	Ordering	Not enforced	Strict validation applied	Enforce ordering rules
Coupons (global)	Description limits	No limits	Type-specific limits	Validate by message type
	Commerce coupon	Unlimited	12 characters max	Adjust content
	Premium Video coupon	Unlimited	18 characters max	Adjust content

Brand messaging end-to-end migration validation

Before moving Brand Message free-form messages into production, validate your migration end to end to ensure compatibility and avoid message rejection or delivery issues.

Step	Validation area	What to verify	Pass criteria
1	Targeting	Every free-form message includes targeting	ALL_CONSENT, TARGETED_FRIENDS, or M/N/I/F present
2	Required fields	Required fields included per message type	IMAGE_FREE_FORM / IMAGE_WIDE_FREE_FORM include image
3	Character limits	Text length within limits	IMAGE_WIDE_FREE_FORM ≤ 76 characters
4	Button limits	Button count and label length enforced	Button count and label length valid per type
5	Button ordering	Ordering rules applied	BUSINESS_FORM / ADD_CHANNEL correctly ordered
6	Coupon validation	Coupon type and length valid	Coupon matches message type and length limits
7	Carousel constraints	Element and ADD_CHANNEL limits enforced	Max 6 elements, single ADD_CHANNEL
8	Premium Video constraints	Structure and button rules enforced	Single button, correct fields used
9	Delivery testing	Messages render correctly in KakaoTalk	Text, images, buttons, coupons display correctly
10	Production readiness	No legacy usage remains	Only free-form APIs used before December 31, 2025

Key migration takeaways

• Targeting is mandatory for all Brand Message free-form messages.
• Character limits vary, notably for IMAGE_WIDE_FREE_FORM (only 76 characters allowed).
• The image field is mandatory in Brand Message free-form IMAGE and IMAGE_WIDE messages.
• Button types are extended with BUSINESS_FORM and ADD_CHANNEL, but button name length may be reduced.
• Button ordering rules must be followed strictly in Brand Message free-form messages.
• Coupon types and description limits differ and require adjustments in coupon content.
• Button count limits are stricter in some Brand Message free-form message types (for example, IMAGE_WIDE_FREE_FORM allows only two buttons).

For authoritative schema definitions, validation rules, and the most up-to-date information, refer to the Kakao Brand Message API documentation (opens in a new tab).