This document introduces the callbacks that Kakao sends to your service server when a user performs a specific request.
If you use the callback functions explained on this page, you must complete the followings:
To make your service server not block the IP addresses of the Kakao server, you must add the Kakao server IP addresses to the Access Control List (ACL). Here is the list of IP addresses you should allow.
Existing IP address | New IP address* |
---|---|
211.231.105.70 211.231.105.37 211.231.103.2 211.231.103.178 211.231.103.179 211.231.103.213 211.231.103.214 211.231.103.244 211.231.103.245 203.133.163.108 203.133.163.62 203.133.165.5 203.133.165.22 203.133.162.57 203.133.162.2 203.133.162.25 203.133.162.41 203.133.162.56 203.133.162.74 203.133.162.90 203.133.165.27 203.133.162.58 203.133.162.42 10.54.241.125 |
211.249.203.104 211.249.203.105 211.249.203.106 211.249.203.107 211.249.203.108 211.249.203.109 211.249.203.169 211.249.203.170 211.249.203.171 211.249.203.172 211.249.203.173 211.249.203.174 220.64.110.190 220.64.110.222 220.64.111.158 220.64.111.188 220.64.111.219 220.64.111.244 220.64.111.245 220.64.111.246 220.64.109.84 220.64.109.85 220.64.109.86 220.64.109.87 |
* You must allow new IP addresses including the exisiting IP addresses before November 7, 2022. For more details, refer to Notice.
The Unlink callback feature sends you a callback when a user unlinks from a service app. Ensure that you cannot get an unlink callback if you request the Unlink API in your service app to unlink a specific user from your service.
Kakao sends an unlink callback in any of the following cases. To figure out which case a user corresponds to among these, check the value of referrer_type
in the unlink callback request:
When you get an unlink callback from Kakao, you must respond with the HTTP status code "200 OK" in all cases, except for the failure of deleting the account or deleting user data. Unlink callback sent from Kakao indicates that you need to delete the user's account or user information. Thus, even when you get a callback for a user that deleted the account in the service so is not retrieved, you need to send a success response.
Ensure that the other status codes except for "200 OK" are considered as failure. The status codes in the Redirection 3xx class are also not supported. Since the Kakao server determines success or failure with the HTTP status code, the response body in your callback response is ignored.
Here is the detailed information of the unlink callback that Kakao sends to your service server.
URLMethod | Request URL |
---|---|
GET or POST | Callback URL registered in [My Application] > [Kakao Login] > [Unlink]. (Example: https://example.com/unlink/callback ) |
Name | Description | Required |
---|---|---|
Authorization | Admin key used to validate your app. KakaoAK ${APP_ADMIN_KEY} |
O |
Name | Type | Description | Required |
---|---|---|---|
app_id | String |
App ID that a user requests to unlink from. | O |
user_id | String |
Service user ID of a user who requests to unlink. | O |
referrer_type | String |
The route of a user requests to unlink. One of the followings: - ACCOUNT_DELETE : If a user deletes the Kakao Account. - FORCED_ACCOUNT_DELETE : If a user's Kakao Account is deleted through Customer Service or deleted after a four-year dormant state. - UNLINK_FROM_APPS : If a user selects [Disconnect] on 'Manage Connected Services'. - UNLINK_FROM_ADMIN : If a user requests to unlink through the Kakao Customer service. - INCOMPLETE_SIGN_UP : If a user has not completed a signup. (Refer to Notice) |
O |
curl -v -X GET "{UNLINK_CALLBACK_URL}?app_id=123456&user_id=1234567890&referrer_type=UNLINK_FROM_APPS" \
-H "Authorization: KakaoAK ${APP_ADMIN_KEY}"
curl -v -X POST "{UNLINK_CALLBACK_URL}" \
-H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
--data-urlencode "app_id=123456" \
--data-urlencode "user_id=1234567890" \
--data-urlencode "referrer_type=UNLINK_FROM_APPS"
You can test if the unlink callback is working by unlinking an account with the service in [Settings] > [Kakao Account] > [Manage Connected Services] on Kakao Talk application or [Use Your Account] > [Manage Connected Services] on the Kakao Account page.
If you apply the Kakao Talk Channel callback, you can get notified when a user adds or blocks your service's Kakao Talk Channel, and update the user information.
If an app user adds or blocks one of the Kakao Talk Channels on the list of 'Connected business channels', the Kakao server sends a callback to the registered callback URL in the predefined format. Then, you need to implement a function to receive and process the request that the Kakao server has made.
Ensure that the other status codes except for "200 OK" are considered as failure. The status codes in the Redirection 3xx class are also not supported. Since the Kakao server determines success or failure with the HTTP status code, the response body in your callback response is ignored.
Here is the detailed information of the Kakao Talk Channel callback that Kakao sends to your service server.
URLMethod | Request URL |
---|---|
POST | Callback URL registered in 'Callback for adding/blocking Kakao Talk Channel'. (Example: https://example.com/channel/callback ) |
Name | Description | Required |
---|---|---|
Authorization | Admin key used to validate your app. KakaoAK ${APP_ADMIN_KEY} |
O |
Name | Type | Description |
---|---|---|
event | String |
Changed status of the relationship between a user and a Kakao Talk Channel. added or blocked . |
id | String |
Service user ID who added or blocked a Kakao Talk Channel. |
id_type | String |
A type of service user ID. Either app_user_id or open_id .- app_user_id : a user who has agreed to provide 'Kakao Talk Channel addition status and details' among Kakao Login consent items.- open_id : a user who has not agreed to provide 'Kakao Talk Channel addition status and details' among Kakao Login consent items. |
channel_public_id | String |
Kakao Talk Channel ID that a user added or blocked. NOTE: plus_friend_public_id has been deprecated and replaced with channel_public_id . |
channel_uuid | String |
Kakao Talk Channel ID for search purpose. NOTE: plus_friend_uuid has been deprecated and replaced with channel_uuid . |
updated_at | Datetime |
The time when a Kakao Talk Channel is added or blocked in UTC*. NOTE: timestamp (in milliseconds) has been deprecated and replaced with updated_at (in UTC). |
*The time is based on Coordinated Universal Time(UTC), being 9 hours behind Korean Standard Time(KST). For the format of time, refer to RFC3339: Date and Time on the Internet.
From May 24th, 2021, we provide a new API for checking Kakao Talk Channel relationship. The new API has some changes in the URL, request parameters and response fields ('plus_friends' → 'channels'). Along with this change, Kakao Talk Channel callback parameters, 'plus_friend_public_id' and 'plus_friend_uuid', are changed to 'channel_public_id' and 'channel_uuid' respectively. Refer to Notice.
curl -X POST "{KAKAOTALK_CHANNEL_CALLBACK_URL}" \
-H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"event":"added",
"id":"1111",
"id_type":"app_user_id",
"channel_public_id":"_FLX",
"channel_uuid":"@ad",
"updated_at":"2020-01-01T00:00:00Z"
}'
Kakao Talk sharing success callback is a function to send a callback request to the callback URL of your server specified in the Kakao Developers when a Kakao Talk sharing message is successfully sent to the selected users or chatrooms. This function lets your service know whether users successfully receive a Kakao Talk sharing message through Kakao Talk.
Moment | What you must do |
---|---|
Before requesting the Kakao Talk sharing API | Allow Kakao IP addresses. Register Kakao Talk sharing callback in [My Application] > [Message] > [Kakao Talk Sharing Callback]. |
When requesting the Kakao Talk sharing API | Specify a custom parameter by using serverCallbackArgs by referring to the following development documentation:- Android SDK - iOS SDK - JavaScript SDK |
After getting callback | Send a link callback response to the Kakao server within 3 seconds with the HTTP status code "200 OK". |
The Kakao Talk sharing success callback is only sent to the specified callback URL of the service server with a GET
or POST
method when a Kakao Talk sharing message is successfully sent to a chatroom. You can check if the callback is valid by checking the admin key passed as Authorization
in the request header and then process the callback request. The custom parameters set through the Kakao SDK are also passed in the success link callback. The success link callback is sent only once and not re-sent even when it fails.
When you get the success link callback, you must respond back to the request within 3 seconds by sending a link callback response to the Kakao server with the HTTP status code "200 OK". Ensure that the other status codes except for "200 OK" are considered as failure. The status codes in the Redirection 3xx class are also not supported. The response body in your callback response is ignored because the Kakao server determines success or failure with the HTTP status code.
Here is the detailed information of the Kakao Talk sharing success callback that Kakao sends to your service server.
URLMethod | Request URL |
---|---|
GET or POST | Callback URL registered in [My Application] > [Message] > [Kakao Talk Sharing Callback]. (Example: https://example.com/kakaolink/callback ) |
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
The Admin key as a type of user authentication. Authorization: KakaoAK ${APP_ADMIN_KEY} |
O |
X-Kakao-Resource-ID | String |
Unique ID for each Kakao Talk sharing success callback. | O |
User-Agent | String |
String used to identify the request sent from Kakao. Fixed as KakaoOpenAPI/1.0 . |
O |
Name | Type | Description | Required |
---|---|---|---|
CHAT_TYPE | String |
Type of chatroom to which Kakao Talk sharing message is sent. One of the followings: - MemoChat : My Chatroom. - DirectChat : 1:1 chat with other users.- MultiChat : Group chat with other users. |
O |
HASH_CHAT_ID | String |
A reference ID of the chatroom that receives a Kakao Talk sharing message. As a unique hash value for each service, a different ID is assigned for each service, even for the same chatroom. |
O |
TEMPLATE_ID | Long |
The message template ID used when sending a Kakao Talk sharing message using the message template ID. If you do not use the message template ID when requesting, an empty value is returned in the response. |
X |
GET /link/callback?CHAT_TYPE=MemoChat&HASH_CHAT_ID=%227cb74349530306cc59ba8058898b656b%22&TEMPLATE_ID=10000&custom_parameter_key=custom_parameter_value HTTP/1.1
Host: ${YOUR_WEB_DOMAIN}
Authorization: KakaoAK ${APP_ADMIN_KEY}
X-Kakao-Resource-ID: 8WVBcBDqPk6g7CJxR2pLX7W9
User-Agent: KakaoOpenAPI/1.0
POST /link/callback HTTP/1.1
Host: ${YOUR_WEB_DOMAIN}
Authorization: KakaoAK ${APP_ADMIN_KEY}
X-Kakao-Resource-ID: Rvy1c2dkzBAZ5hGD3rqYbxvr
User-Agent: KakaoOpenAPI/1.0
Content-Type: application/json
Content-Length: XX
{"CHAT_TYPE":"MemoChat","HASH_CHAT_ID":"%227cb74349530306cc59ba8058898b656b%22","TEMPLATE_ID":10000,"custom_parameter_key":"custom_parameter_value"}
If you set a custom parameter, you can:
You can leverage the Kakao Talk sharing success callback function as reference information about the message delivery result, along with the custom parameters. If you send a Kakao Talk sharing message using a message template ID, you can figure out which message has been sent through the TEMPLATE_ID
parameter. You can also know how many chatrooms a specific message has been sent to by checking HASH_CHAT_ID
.
In addition, if you pass the sender information through serverCallbackArgs
when requesting the Kakao Talk sharing API, you can get both the information of the message sender and the chatroom that received the message. With the information, you can figure out how many times a specific sender has sent a message to the same chatroom or how many chatrooms the sender has sent a message to.