Alim Talk

API for sending informational messages that can be delivered to users who have not added the KakaoTalk Channel provided by Kakao.

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].

The default encoding for all AlimTalk APIs is UTF-8.

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

Alim 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 at-standard : standard alim talk at-bulk : bulk alim talk at-finance : finance alim talk at-verify : verification alim talk

Kakao Alim talk API

POST https://27ep4ci1w0.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_type*	string	Message type ("AT" | "AI") AT: AlimTalk (for all cases except image type with emphasis)) AI: Image AlimTalk
msg_data*	array	Detailed data of message sending (up to 10 records)
sender_number*	string	Sender's phone number
msg_key*	string	User-managed unique key for the message (automatically assigned if null or blank)
header	string	Title displayed at the top of the message (64 bytes)
msg*	string	Transmitted message (up to 1000 characters including spaces)
receiver_number*	string	Recipient's mobile phone number
title	string	AlimTalk emphasis information (200 bytes)
template_code*	string	AlimTalk template code. (Registration is required in [Service Console / Template Management].)
sender_key*	string	Kakao BizMessage sender profile key (Registration is required in [Service Console / Sender Profile Registration].)
currency_type	string	Currency unit (12 bytes) for price/amount/payment amount included in the message, dedicated for Moment Ad Conversion Optimization. Use international currency codes such as KRW, USD, EUR
price	number	Price information included in the message
attachment	object	Button or image data (Refer to the attachment details)
supplement	object	Direct link connection data (Refer to the supplement details)
echo_to_webhook	string	The string to be received along with the webhook from API PLEX (up to 256 bytes)
failback_data	object
api_unique_id	string	failback service's unique id (required when use failback) (see failback)
secret_key	string	failback service의 sub_account의 secret_key (required when use failback)
	String	payload for failback service request body. fill fileds failback service required. (refer to examplpe)

200: OK Response returned successfully

Attachment 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)
item_highlight	object	N	item highlight
title	string	Y	title (120 byte, Maximum 21 letters if the image exists)
description	string	Y	additional information (76 byte, Maximum 13 letters if the image exists)
item	object	N	Item list and item summary information
list	array	Y	Item list
title	string	Y	title (24 byte)
description	string	Y	price information (92 byte)
summary	object	N	summary information of item
title	string	Y	title (24 byte)
description	string	Y	price information (56 byte)

Supplement details

key	type	required	description
quick_reply	array	N	direct connection info list
name	string	Y	direct connection title (54 byte)
type	string	Y	direct connection type (Refer to the Direct connection type)
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	N	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
chat_extra	string	N	Metadata to be transferred when switching to a bot (200 bytes)
chat_event	string	N	Bot event name to be linked when switching to a bot (200 bytes)

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
DS	-	-	-	Move to the delivery tracking page when the button is clicked
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
AC	-	-	-	Add KakaoTalk channel when the button is clicked
P1	-	-	-	Image security transmission plugin
P2	-	-	-	Personal information usage plugin
P3	-	-	-	One-click payment plugin (Must send oneclick_id or product_id when sending)

Direct connection 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

Request Body example

{
    "msg_type": "AT",
    "msg_data": [
        {
            "msg_key": "user_key_1",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "msg": "기본형 선택안함 TEST 메세지 입니다.",
            "sender_key": "user_sender_key_001",
            "template_code": "user_template_code_001"
        },
        {
            "msg_key": "",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "title": "강조표기 테스트 제목입니다.",
            "msg": "강조표기 테스트 본문입니다.",
            "sender_key": "user_sender_key_001",
            "template_code": "user_template_code_002",
            "attachment": {
                "button": [
                    {
                        "name": "강조표기",
                        "type": "WL",
                        "url_pc": "https://www.apiplex.net",
                        "url_mobile": "https://m.apiplex.net"
                    }
                ]
            },
            "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 본문입니다."
            }
        }
    ]
}

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.)

Success

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

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

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": "0e826855-299f-4328-82a1-d33720dcca23"
        }
    ]
}

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