카카오톡 공유: 웹훅

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

시작하기 전에

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

카카오톡 공유 웹훅

기본 정보

메서드	URL	필수 응답 규격	인증 방식
GET/POST	[내 애플리케이션] > [메시지] > [카카오톡 공유 웹훅]에 등록한 웹훅 URL	HTTP 상태 코드 2XX (3초 내)	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
-	카카오톡 공유 웹훅	-	-

카카오톡 공유 웹훅은 사용자가 선택한 친구 또는 채팅방으로 카카오톡 공유 메시지가 성공적으로 전달된 경우, 카카오가 해당 사실을 서비스로 전달하는 기능입니다. 웹훅을 수신한 서비스는 HTTP 상태 코드 2XX로 3초 내에 응답해야 합니다.

사전 설정

카카오톡 공유 웹훅은 웹훅 URL과 메서드를 지정해야 사용할 수 있으며, 리다이렉트는 지원하지 않습니다. 설정 방법은 카카오톡 공유 웹훅을 참고합니다.

또한, 카카오톡 공유 전송 시 serverCallbackArgs로 사용자 정의 파라미터를 지정해야 카카오톡 공유 웹훅을 수신할 수 있습니다. 자세한 내용은 아래 플랫폼별 개발 가이드를 참고합니다.

• JavaScript
• Android
• iOS

요청

헤더

이름	타입	설명	필수
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
TEMPLATE_ID	Long	메시지 템플릿으로 카카오톡 공유 메시지를 보낸 경우 사용한 메시지 템플릿의 ID, 메시지 템플릿 ID를 사용해 요청하지 않은 경우 전달되지 않음	X
HASH_CHAT_ID	String	카카오톡 공유 메시지를 수신한 채팅방의 참고용 ID 서비스별로 유일(Unique)한 해시(Hash) 값으로, 같은 채팅방이라도 서비스마다 다른 값 제공 참고: 얼마나 많은 채팅방으로 카카오톡 공유가 발송되었는지 확인 가능	O

응답

• HTTP 상태 코드 2XX (3초 내)

예제

요청: GET 메서드

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"

요청: POST 메서드

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"
        }'