Friend Talk

API that allows messaging only to users who have connected with the KakaoTalk channel but can send both informational and promotional messages.

To use the service, you need to register the sender number in [Service Console / Sender Number].

To use the service, you need to perform a new registration in [Service Console / Template Management].

Message sending is restricted between 20:50 and 08:00 (KST).

To include images in KakaoTalk Friend Talk or KakaoTalk Wide, it is essential to use the image upload API beforehand.

The default encoding for all KakaoTalk Friend Talk APIs is UTF-8.

This API can deliver the message sending results through a WebHook.

Friend Talk API

Path variable

Please refer to the following information to ensure that path variables (enclosed in curly braces {}) within each URI are not omitted when making calls.

code	description
service_id	service id ft-text : friend talk text ft-image : friend talk image ft-wide : friend talk wide ft-wide-item-list: friend talk wide item list ft-carousel-feed: friend talk carousel feed

Kakao Friend Talk API

POST https://9tpssuhbpx.apigw.ntruss.com/{service_id}/v2/send

Headers

Name	Type	Description
Authorization*	string	userID;secret_key
Content-Type*	string	application/json;charset=utf-8

Request Body

Name	Type	Description
msg_data*	array	Detailed data of messages (up to 10 records)
sender_key*	string	Kakao BizMessage sender profile key. (Registration is required in [Service Console / Sender Profile Registration].)
header	string	Wide item list header (32 byte) (Requied when use Wide item list)
msg*	string	Transmitted message (up to 1000 characters including spaces)
receiver_number*	string	Recipient's mobile phone number
sender_number*	string	Sender's phone number
msg_key*	string	Unique key for the message managed by the user (automatically assigned if null or blank)
echo_to_webhook	string	The string to be received along with the webhook from API PLEX by the user (up to 256 bytes)
attachment	object	Button or image data (refer to attachment details)
ad_flag	string	Display mandatory information for promotional messages (default value: Y)
carousel	object	carousel data (refer to carousel detailes)
failback_data	object	failback data
secret_key	string	failback service's sub_account's secret_key (required when use failback)
api_unique_id	string	failback service's unique id (required when use failback) (see failback)
	String	payload for failback service request body. fill fileds failback service required. (refer to example)

200: OK Response returned successfully

Attachement details

key	type	required	description
button	array	N	Button attribute data (up to 5)
name	string	Y	Button title (112 byte)
type	string	Y	Button type (Refer to the button type)
url_pc	string	N	URL to move to when the button is clicked in a PC environment
url_mobile	string	N	URL to move to when the button is clicked in a mobile environment
scheme_android	string	N	Custom scheme of the application to be executed when the button is clicked in a mobile Android environment
scheme_ios	string	N	Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment
chat_extra	string	N	Metadata to be transferred when switching to a bot (50 bytes)
chat_event	string	N	Bot event name to be linked when switching to a bot (50 bytes)
image	object	N	Used for images in KakaoTalk Friend Talk or KakaoTalk Wide
img_url	string	N	Image path URL
img_link	string	N	URL to go to when click image if not set, use kakao talk inner image viewer
item	object	N	friend talk wide item list information
list	array	N	wide item list (minimum: 3, maximum: 4)
title	string	Y	The first item is limited to 25 characters, and the 2nd to 4th items are limited to 30 characters each
img_url	string	Y	image URL
scheme_android	string	N	Custom scheme of the application to be executed when the button is clicked in a mobile Android environment
scheme_ios	string	N	Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment
url_mobile	string	Y	URL to move to when the button is clicked in a mobile environment
url_pc	string	N	URL to move to when the button is clicked in a PC environment

Carousel details

key	type	required	description
list	array		carousel list (minimum: 2, maximum: 6)
header	string	Y	carousel item title (20 byte)
message	string	Y	carousel item message (180 byte)
attachment	object
button	array
name	string	Y	button title (8 byte)
type	string	Y	button type (refer to button type)
scheme_android	string		Custom scheme of the application to be executed when the button is clicked in a mobile Android environment
scheme_ios	string		Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment
url_mobile	string		URL to move to when the button is clicked in a mobile environment
url_pc	string		URL to move to when the button is clicked in a PC environment
image	object		carousel thumnail image
img_url	string	Y	carousel thumnail image URL
img_link	string		carousel thumnail image link URL
coupon	object		coupon at the bottom of the carousel
title	string		coupon name
description	string		coupon description (12자)
scheme_android	string		Custom scheme of the application to be executed when the button is clicked in a mobile Android environment
scheme_ios	string		Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment
url_mobile	string		URL to move to when the button is clicked in a mobile environment
url_pc	string		URL to move to when the button is clicked in a PC environment
tail	object		"more" button information
scheme_android	string		Custom scheme of the application to be executed when the button is clicked in a mobile Android environment
scheme_ios	string		Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment
url_mobile	string		URL to move to when the button is clicked in a mobile environment
url_pc	string		URL to move to when the button is clicked in a PC environment

Button Type

button type	attribute	type	required	description
WL	url_mobile	string	Y	[Web link] Web URL to move to when clicked for direct connection, depending on the PC/mobile environment
	url_pc	string	N	Same as above
AL	scheme_android	string	Y	[App link] Either scheme_ios, scheme_android, or url_mobile is required Custom scheme of the application to be executed when the button is clicked in a mobile Android environment Custom scheme for mobile iOS URL to move to when the button is clicked in a mobile environment
	scheme_ios	string	Y	Same as above
	url_mobile	string	Y	Same as above
	url_pc	string	-	URL to move to when the button is clicked in a PC environment
BK	-	-	-	Send the corresponding button text
MD	-	-	-	Send both the corresponding button text and the message body
BC	-	-	-	Available only for KakaoTalk channels using Consultation Talk
	chat_extra	string	N	Metadata to be transferred when switching to Consultation Talk
BT	-	-	-	Available only for KakaoTalk channels using Kakao | Open Builder chatbots
	chat_extra	string	N	Metadata to be transferred when switching to a bot
	chat_event	string	N	Bot event name to be linked when switching to a bot
BF	biz_form_key	string	Y	BizForm key obtained through BizForm upload

Length limit for button names by message sending type

Sending Type	limitation(Maximum)
friend talk text(ft-text)	14 letters
friend talk image(ft-image)	14 letters
friend talk wide(ft-wide)	8 letters
friend talk wide item list(ft-wide-item-list)	8 letters
friend talk carousel feed(ft-carousel-feed)	8 letters

Request Body Example

{
    "msg_data": [
        {
            "msg_key": "user_key_1",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "msg": "ft-text test",
            "ad_flag": "N",
            "sender_key": "user_sender_key_001",
            "echo_to_webhook": "echo test",
            "failback_data": {
                "api_unique_id": "sms-standard",
                "secret_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "sender_number": "010xxxxxxxx",
                "receiver_number": "010xxxxxxxx",
                "origin_cid": "0123456789",
                "msg": "failback 본문입니다."
            }
        },
        {
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "msg": "ft-text and button test",
            "ad_flag": "N",
            "attachment": {
                "button": [
                    {
                        "name": "button1",
                        "type": "WL",
                        "url_pc": "https://www.apiplex.net",
                        "url_mobile": "https://m.apiplex.net"
                    },
                    {
                        "name": "button2",
                        "type": "WL",
                        "url_pc": "https://www.apiplex.net",
                        "url_mobile": "https://m.apiplex.net"
                    }
                ]
            },
            "sender_key": “user_sender_key_001”
        }
    ]
}

Response Body

Even if the response HTTP status returns as 200, it does not necessarily mean the successful acceptance of all requests. (You can check the acceptance status of each transmission by the response code field.)

key		type	description
results		array	Received message data
	msg_key	string	Unique key for the message
	code	string	Acceptance result code (Refer to API PLEX response codes)
	desc	string	Detailed acceptance result code

Success

{
    "results": [
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "user_key_1"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "11520199-f289-4681-b0e3-354393a4b041"
        }
    ]
}

Invalid request or error

{
    "code": "C400_2",
    "name": "Invalid Parameter",
    "description": "사용자 인증 실패"
}

Invalid request within the list

{
    "results": [
        {
            "code": "G141",
            "desc": "수신번호 예외",
            "msg_key": "user_key_101"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "22c35870-d4a5-46e3-9d64-17f42c1e3248"
        }
    ]
}

API PLEX Response Code

code	title	description
C100	Success
C400_1	Invalid data type	Refer to the description in the response body
C400_2	Invalid request parameter	Refer to the description in the response body
C400_3	Missing required parameters	Refer to the description in the response body
C404_1	Unable to find the data	Refer to the description in the response body
C500_1	Internal server error	Refer to the description in the response body
G110	API UNIQUE ID exception (Invalid URL)
G140	Sender number exception
G141	Recipient number exception
G142	Invalid echo_to_webhook value	Exceed 256 byte or type error
G150	Insufficient credit
G160	Exceeded the maximum number of transmissions per session