사이드 메뉴
시작하기
로그인
커뮤니케이션
광고
카카오톡 공유
웹훅
이 문서는 카카오톡 공유 관련 웹훅 정보를 안내합니다.
이 문서는 서비스에서 카카오 API를 호출하는 방식이 아닌, 카카오가 서비스의 엔드포인트로 전송하는 웹훅 요청에 대한 명세를 설명합니다.
웹훅 기능의 전체 흐름과 구현 방식은 구현 절차에서 먼저 확인할 수 있습니다.
SDK에서 카카오톡 공유 API 호출 시, serverCallbackArgs로 사용자 정의 파라미터를 지정해야 카카오톡 공유 웹훅을 수신할 수 있습니다. 자세한 내용은 플랫폼별 개발 가이드를 참고합니다.
| 메서드 | URL | 필수 응답 규격 | 인증 방식 |
|---|---|---|---|
GET/POST | 앱 관리 페이지의 [앱] > [웹훅] > [카카오톡 공유 웹훅]에 등록한 웹훅 URL | HTTP 상태 코드 2XX (3초 내) | 대표 어드민 키 |
카카오톡 공유 웹훅은 사용자가 선택한 친구 또는 채팅방으로 카카오톡 공유 메시지가 성공적으로 전달된 경우, 카카오가 해당 사실을 서비스로 전달하는 기능입니다.
웹훅을 수신한 서비스는 HTTP 상태 코드 2XX로 3초 내에 응답해야 합니다.
카카오톡 공유 API의 발송 결과 확인
카카오톡 공유 API는 카카오톡 메시지 API와의 구조적 차이로 인해 웹훅으로만 발송 결과를 확인할 수 있습니다. 두 API의 차이점은 기능 소개를 참고합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| Authorization | String | Authorization: KakaoAK ${PRIMARY_ADMIN_KEY}유효한 웹훅인지 판단할 수 있도록 전달하는 대표 어드민 키 | O |
| X-Kakao-Resource-ID | String | X-Kakao-Resource-ID: ${UNIQUE_ID}각 웹훅의 구분을 위한 고유 ID | O |
| User-Agent | String | User-Agent: KakaoOpenAPI/1.0카카오에서 보낸 웹훅임을 알리기 위한 문자열 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| CHAT_TYPE | String | 카카오톡 공유 메시지가 전달된 채팅방의 타입, 아래 중 하나
| O |
| HASH_CHAT_ID | String | 카카오톡 공유 메시지를 수신한 채팅방의 참고용 ID 서비스별로 유일(Unique)한 해시(Hash) 값으로, 같은 채팅방이라도 서비스마다 다른 값 제공 참고: 얼마나 많은 채팅방으로 카카오톡 공유가 발송되었는지 확인 가능 | O |
${CUSTOM_KEY}":"${CUSTOM_VALUE} | JSON | SDK에서 카카오톡 공유 API 호출 시 서비스에서 직접 정의한 사용자 정의 파라미터serverCallbackArgs 파라미터 키와 값을 JSON 형식으로 입력해야 함(예: {"user_id":"abcd","product_id":1234}) | O |
| TEMPLATE_ID | Long | 메시지 템플릿으로 카카오톡 공유 메시지를 보낸 경우 사용한 메시지 템플릿의 ID, 메시지 템플릿 ID를 사용해 요청하지 않은 경우 전달되지 않음 | X |
| IS_SINGLE_CHATROOM | Boolean | 카카오톡 공유 메시지를 수신한 채팅방이 발신자만 참여 중이거나, 발신자만 남아있는 채팅방인지 여부
CHAT_TYPE이 MultiChat이지만 발신자만 참여 중인 경우 true로 응답)중요: 카카오톡 공유 유료 사용 설정을 활성화한 앱만 전달 | X |
| CHAT_MEMBER_COUNT_RANGE | String | 카카오톡 공유 메시지를 수신한 채팅방의 참여자 수 범위, 아래 중 하나
중요: 카카오톡 공유 유료 사용 설정을 활성화한 앱만 전달 | X |
웹훅 요청을 받은 후 3초 내에 HTTP 상태 코드 2XX로 응답해야 합니다.
아래는 카카오톡 공유 메시지가 사용자에게 성공적으로 전달됐을 때 카카오가 서비스에게 보내는 웹훅 요청 예시입니다.
요청: 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 ${PRIMARY_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 ${PRIMARY_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"}'