카카오톡 공유: 콜백

이 문서는 카카오톡 공유 관련 콜백 정보를 안내합니다.

시작하기 전에

이용 정책에서 콜백 사용 시 주의사항을 확인해야 합니다.

카카오톡 공유 전송 성공 알림

기본 정보

메서드	URL	인증 방식
GET/POST	[내 애플리케이션] > [메시지] > [카카오톡 공유 콜백]에 설정된 URL (예: https://example.com/kakaolink/callback)	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
-	카카오톡 공유 전송 성공 알림	-	-

카카오톡 공유 전송 성공 알림은 사용자가 선택한 친구나 채팅방으로 카카오톡 공유 메시지가 성공적으로 전달된 경우, 카카오디벨로퍼스에 설정된 콜백 URL로 메시지가 성공적으로 전달되었음을 알려주는 기능입니다.

이 기능을 사용하려면 먼저 설정하기를 참고해 콜백 URL과 요청 방법(Method)을 설정해야 합니다. 콜백은 리다이렉트를 지원하지 않습니다.

또한 카카오톡 공유 메시지 발송 시 serverCallbackArgs 파라미터를 통해 사용자 정의 파라미터를 설정해야 합니다. 자세한 내용은 다음의 플랫폼별 개발 가이드를 참고합니다.

• JavaScript
• Android
• iOS

카카오톡 공유 메시지가 채팅방에 성공적으로 전송된 경우, serverCallbackArgs로 설정한 파라미터를 포함한 알림이 서비스 서버의 카카오톡 공유 콜백 URL로 전달됩니다.

전송 성공 알림은 GET 또는 POST 방식으로 서비스 서버의 카카오톡 공유 콜백 URL에 전달되며, Authorization 헤더 값으로 전달된 앱 어드민 키로 유효한 콜백인지 판단하고 요청을 처리합니다. Kakao SDK를 이용해 설정한 파라미터도 추가 전달됩니다. 링크 콜백은 1회만 전달되며, 실패 시 재전송되지 않습니다.

카카오톡 공유 API 요청 시 발신자 정보를 사용자 정의 파라미터로 전달하면, 메시지를 보낸 사용자와 받은 채팅방의 정보를 모두 받을 수 있습니다. 이를 통해 특정 발신자가 동일한 채팅방에 메시지를 보낸 횟수나 얼마나 많은 채팅방에 메시지를 보냈는지를 파악하는 것이 가능합니다.

카카오에서 보내는 전송 성공 알림의 파라미터는 메시지 전송 결과에 대한 참고 정보로써, 사용자 정의 파라미터와 함께 사용하면 더욱 유용하게 활용할 수 있습니다. 메시지 템플릿 ID를 사용해 카카오톡 공유 메시지를 보낸 경우, TEMPLATE_ID 파라미터로 어떤 메시지가 보내졌는지 확인할 수 있습니다. 이와 함께 HASH_CHAT_ID를 참고하면 특정 메시지 템플릿이 얼마나 많은 채팅방으로 보내졌는지 알 수 있습니다.

카카오에서 서비스 서버로 콜백 요청을 받으면 HTTP 상태 코드 "200 OK"로 응답해야 합니다. 카카오 서버는 응답 본문과 관계없이 HTTP 상태 코드만 보고 성공 여부를 확인하므로 body 정보는 포함하지 않아도 됩니다. 요청에 대한 타임아웃(3초)이 있습니다. 카카오에서 서비스 서버로 보내는 알림의 요청 정보는 아래를 참고합니다.

헤더

이름	타입	설명	필수
Authorization	String	Authorization: KakaoAK ${APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
X-Kakao-Resource-ID	String	카카오톡 공유 알림(콜백)별 유니크 ID (예: Rvy1c2dkzBAZ5hGD3rqYbxvr)	O
User-Agent	String	카카오에서 보낸 요청임을 알리기 위한 문자열 KakaoOpenAPI/1.0	O

파라미터

• 콜백은 아래 파라미터 외에 serverCallbackArgs 파라미터로 전달된 키와 값을 포함합니다.

이름	타입	설명	필수
CHAT_TYPE	String	카카오톡 공유 메시지가 전달된 채팅방의 타입 다음 중 하나: MemoChat: 나와의 채팅방 DirectChat: 다른 사용자와의 1:1 채팅방 MultiChat: 다른 사용자들과의 그룹 채팅방 OpenDirectChat: 1:1 오픈채팅방 OpenMultiChat: 그룹 오픈채팅방	O
HASH_CHAT_ID	String	카카오톡 공유 메시지를 수신한 채팅방의 참고용 ID 서비스별로 유일(Unique)한 해시(Hash) 값으로, 같은 채팅방이라도 서비스마다 다른 값 제공	O
TEMPLATE_ID	Long	메시지 템플릿 ID를 사용해 카카오톡 공유 메시지를 보낸 경우 사용된 메시지 템플릿의 ID, 메시지 템플릿 ID를 사용해 요청하지 않은 경우 전달되지 않음	X

예제

curl -v -G GET "${YOUR_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"

curl -v -X POST "${YOUR_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"
        }'