kakao developers

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.

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

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"

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.

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

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.

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.