페이지 이동경로
  • Docs>
  • Reference Information>
  • Advanced: Callback

Reference Information

Advanced: Callback

This document introduces the callbacks that Kakao sends to your service server when a user performs a specific request.

Prerequisites

If you use the callback functions explained on this page, you must complete the followings:

Allow Kakao IP addresses

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.

Unlink callback

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:

  • If a user deletes the Kakao Account.
  • If a user's Kakao Account is deleted through Customer Service or deleted four years after the account has been switched to a dormant state.
  • If a user selects [Disconnect] on the 'Manage Connected Services' page.
  • If a user requests to unlink through the Kakao Customer service.
  • If a user has not completed a signup.
What you must do
  1. Allow Kakao IP addresses.
  2. Set an unlink callback in [My Application] > [Kakao Login] > [Unlink].
  3. Implement a function to receive and process the callback request that the Kakao server has made. For example, first check if the Admin key in the callback request sent from the Kakao server is correct. If so, delete or disable the user information from the service server, and proceed other jobs that need to go with the process.
  4. When you get an unlink callback, you must respond back to the request within 3 seconds with the HTTP status code "200 OK" by sending a callback response to the Kakao server.
  5. Process the user data stored in the service DB, such as deleting or disabling the account according to your service policy. After the unlink process, users cannot use the service anymore with the Kakao Accounts.

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.

URL
Method Request URL
GET or POST Callback URL registered in [My Application] > [Kakao Login] > [Unlink].
(Example: https://example.com/unlink/callback)
Header
Name Description Required
Authorization Admin key used to validate your app.
KakaoAK ${APP_ADMIN_KEY}
O
Parameter
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
Callback Request Sample
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"
How do I check if the unlink callback is set successfully?

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.

Kakao Talk Channel callback

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.

What you must do
  1. Allow Kakao IP addresses.
  2. Set a Kakao Talk Channel callback in [My Application] > [Kakao Talk Channel] > [Callback for adding/blocking Kakao Talk Channel].
  3. Implement a function to receive and process the callback request that the Kakao server has made.
  4. When you get the Kakao Talk Channel callback, you must respond back to the request within 3 seconds with the HTTP status code "200 OK" by sending a callback response to the Kakao server.

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.

URL
Method Request URL
POST Callback URL registered in 'Callback for adding/blocking Kakao Talk Channel'.
(Example: https://example.com/channel/callback)
Header
Name Description Required
Authorization Admin key used to validate your app.
KakaoAK ${APP_ADMIN_KEY}
O
Parameter
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.

NOTE: Providing a new API

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.

Callback Request Sample
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

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.

What you must do
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.

URL
Method Request URL
GET or POST Callback URL registered in [My Application] > [Message] > [Kakao Talk Sharing Callback].
(Example: https://example.com/kakaolink/callback)
Header
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
Parameter
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
Callback Request Sample
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"}

Best practices

If you set a custom parameter, you can:

  • Get callback only for the desired messages because the Kakao server sends a callback only for the Kakao Talk sharing API calls that include the custom parameter. If you do want to get a callback for a specific message, do not include the custom parameter when calling the Kakao Talk sharing API.
  • Figure out which message is successfully sent. The Kakao server sends a callback along with the custom parameter as you specified, so you can check additional message information, such as the sender or the shared contents.

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.