This document introduces the callbacks that Kakao sends to your service server when a user performs a specific request.
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. - 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 [General Settings] > [Privacy] > [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 Link 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 Link message is successfully sent to the selected users or chatrooms. This function lets your service know whether users successfully receive a Kakao Link message through Kakao Talk.
Moment | What you must do |
---|---|
Before requesting the Kakao Link API | Register Kakao Link callback in [My Application] > [Message] > [Kakao Link Callback]. |
When requesting the Kakao Link 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 Link success callback is only sent to the specified callback URL of the service server with a GET
or POST
method when a Kakao Link 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. 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 Link success callback that Kakao sends to your service server.
URLMethod | Request URL |
---|---|
GET or POST | Callback URL registered in [My Application] > [Message] > [Kakao Link 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 Link 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 Link 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 Link 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 Link 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 Link success callback function as reference information about the message delivery result, along with the custom parameters. If you send a Kakao Link 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 Link 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.