Kakao Talk Share: Webhook

This document introduces the Kakao Talk Share webhook feature.

Before you begin

This document explains the webhook requests that Kakao sends to your service's endpoint. Note that this specification describes incoming webhook requests from Kakao, not API requests that your service makes to Kakao.

For the overall workflow and detailed implementation guide for webhooks, see Implementation steps.

Required: Custom parameter configuration

When invoking the Kakao Talk Share API via the SDK, you must specify custom parameters using serverCallbackArgs to receive the Kakao Talk Share webhook. For more details, see the development guides as below.

• JavaScript
• Android
• iOS

Kakao Talk Share webhook

Basic information

Method	URL	Required response format	Authentication
GET/POST	Webhook URL registered in [My Applications] > [Messages] > [Kakao Talk Share Webhook]	HTTP status code 2XX (within 3 seconds)	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Set Kakao Talk Share webhook Set custom parameter	-	-

The Kakao Talk Share webhook notifies the service when a Kakao Talk Share message is successfully delivered to the selected friends or chat rooms. Upon receiving the webhook, the service must respond with an HTTP status code 2XX within 3 seconds.

Prerequisites

The Kakao Talk Share webhook requires specifying a webhook URL and method to be used, and redirection is not supported. For configuration details, refer to Set Kakao Talk Share webhook.

Additionally, to receive the Kakao Talk Share webhook, user-defined parameters must be specified with serverCallbackArgs when sending a Kakao Talk Share message. For the details, see the platform-specific development guides below.

• JavaScript
• Android
• iOS

Request

Header

Name	Type	Description	Required
Authorization	String	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} The Admin key as a type of user authentication.	O
X-Kakao-Resource-ID	String	Unique ID for each Kakao Talk Share webhook. (Example: Rvy1c2dkzBAZ5hGD3rqYbxvr)	O
User-Agent	String	String used to identify the request sent from Kakao. Fixed to KakaoOpenAPI/1.0.	O

Parameter

Name	Type	Description	Required
CHAT_TYPE	String	Type of chatroom to which Kakao Talk Share message is sent. One of the followings: MemoChat: My Chatroom DirectChat: 1:1 chat with other users MultiChat: Group chat with other users OpenDirectChat: 1:1 Open Chat OpenMultiChat: Group Open Chat	O
HASH_CHAT_ID	String	A reference ID of the chatroom that receives a Kakao Talk Share message. As a unique hash value for each service, a different ID is assigned for each service, even for the same chatroom.	O
${CUSTOM_KEY}":"${CUSTOM_VALUE}	JSON	Custom parameter defined by a service when calling the Kakao Talk Share API through the SDK. Input the keys and values of serverCallbackArgs parameter in JSON format. (Example: {"user_id":"abcd","product_id":1234})	O
TEMPLATE_ID	Long	The message template ID used when sending a Kakao Talk Share 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

Response

You must respond with HTTP status code 2XX within 3 seconds of receiving the webhook request.

Sample

Theses are examples of the webhook request that Kakao sends to your service when the Kakao Talk message is successfully delivered.

Request: GET method

curl -v -G GET "${KAKAOLINK_CALLBACK_URL}?CHAT_TYPE=MemoChat&HASH_CHAT_ID=${HASH_CHAT_ID}&TEMPLATE_ID=10000&custom_parameter_key=custom_parameter_value" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -H "X-Kakao-Resource-ID: ${UNIQUE_ID}" \
    -H "User-Agent: KakaoOpenAPI/1.0"

Request: POST method

curl -v -X POST "${KAKAOLINK_CALLBACK_URL}" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -H "X-Kakao-Resource-ID: ${UNIQUE_ID}" \
    -H "User-Agent: KakaoOpenAPI/1.0" \
    -H "Content-Type: application/json" \
    -d '{
            "CHAT_TYPE":"MemoChat",
            "HASH_CHAT_ID":"${HASH_CHAT_ID}",
            "TEMPLATE_ID":10000,
            "custom_parameter_key":"custom_parameter_value"
        }'