페이지 이동경로
  • 문서>
  • 유용한 참고 정보>
  • 고급: 콜백 알림 받기

유용한 참고 정보

고급: 콜백 알림 받기

이 문서는 사용자가 특정 기능을 수행할 때, 카카오에서 서비스 서버로 보내는 알림인 콜백(Callback)의 처리 방법을 안내합니다.

연결 끊기 알림

연결 끊기 알림은 사용자가 서비스 외부에서 각 서비스 애플리케이션(이하 앱)과의 연결을 해제할 경우, 카카오 서버가 사용자의 연결 끊기 요청을 서비스 서버로 전달하는 기능입니다. 다음과 같은 경우에 연결 끊기 알림이 전달됩니다.

연결 끊기 API

연결 끊기 API를 호출해 서비스가 사용자와의 연결을 끊은 경우에는 연결 끊기 알림이 발송되지 않습니다.

사용자가 연결 끊기를 요청하면 카카오에서는 더 이상 해당 서비스를 사용할 수 없다는 점을 안내합니다. 해당 서비스에서도 서비스 데이터베이스(DB)에서 연결을 끊은 사용자 정보를 처리해야 합니다. 연결 끊기 알림을 설정하면 서비스에게도 특정 사용자가 앱 연결을 끊은 사실을 알리므로, 서비스 자체 정책에 따라 탈퇴 처리할 수 있습니다.

이 기능을 사용하려면 먼저 연결 끊기 알림 설정에서 콜백 URL 및 요청 방법(Method)을 지정해야 합니다. 콜백은 리다이렉트를 지원하지 않습니다.

요청 헤더는 앱 어드민 키를, 바디는 앱 ID(app_id)와 회원번호(user_id), 연결 끊기 요청 경로(referrer_type)를 각각 포함합니다. 앱 어드민 키와 앱 ID로 요청의 유효성을 검증해야 합니다. 아래의 요청 전문 예제를 참고합니다.

이러한 요청을 받으면 특정 사용자가 앱과의 연결을 끊은 것이므로, 서비스 서버에서도 해당 사용자 정보를 삭제하는 등 개인정보 처리방침에 따른 조치를 취한 뒤 카카오 서버에도 응답해야 합니다. 일반적으로 다음과 같이 처리합니다.

  • 카카오 서버가 요청 시 전달한 어드민 키가 올바른 값인지 확인합니다. 어드민 키가 올바르다면, 서비스 서버에서 해당 사용자의 정보를 삭제하고, 함께 필요한 작업이 있다면 수행합니다.
  • 사용자 정보 삭제 및 관련 작업 완료 후 카카오 서버의 요청에 대해 HTTP status "200 OK"로 응답합니다. 카카오 서버는 HTTP status로 성공 여부를 판단하므로 응답 본문(Body)은 필요하지 않습니다.
  • 카카오 서버로의 응답은 3초 이내로 이뤄져야 합니다. 사용자 정보 삭제에 실패한 경우를 제외하고는 모두 성공으로 응답합니다.
주의: 성공 응답을 잊지 마세요!

카카오로부터의 연결 끊기 알림은 해당 사용자의 탈퇴 처리 및 정보 삭제를 요청하는 것이므로, 이미 서비스에서 탈퇴 처리되어 회원 정보에서 조회할 수 없는 사용자를 대상으로 연결 끊기 알림이 온 경우에도 성공 응답을 보내야 합니다. 즉, 사용자 탈퇴 처리 및 정보 삭제에 실패하는 경우를 제외하고 모든 경우에 성공 응답을 보내야 합니다.

URL
Name Description Sample
도메인(Domain) 서비스 서버 도메인 https://api.example.com
API 경로(Path) API 상세 경로 /v1/user/deregister
HTTP method GET 또는 POST GET
Header
Name Description Required
Authorization 사용자 인증 수단, 앱 어드민 키
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
app_id String 사용자가 연결 끊기를 요청한 앱 ID O
user_id String 연결 끊기를 요청한 사용자의 회원번호 O
referrer_type String 연결 끊기 요청 경로
ACCOUNT_DELETE: 카카오계정 탈퇴
UNLINK_FROM_ADMIN: 카카오 관리자로 인한 탈퇴 처리
UNLINK_FROM_APPS: 카카오계정 페이지를 통한 서비스 연결 끊기
INCOMPLETE_SIGN_UP: 가입 미완료 사용자 연결 끊기 처리(공지사항 참고)
O
Sample: 연결 끊기 알림
curl -v -X GET "${YOUR_UNLINK_CALLBACK_URL}?app_id=123456&user_id=1234567890&referrer_type=UNLINK_FROM_APPS" \
    -H "Authorization: KakaoAK ${APP_ADMIN_KEY}"
curl -v -X POST "${YOUR_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"
연결 끊기 알림 설정이 잘 되었는지 테스트하려면?

연결 끊기 알림을 받으려면 사용자가 연결을 끊는 상황을 만들어야 합니다. 카카오계정 페이지 또는 카카오톡의 더보기 탭에 있는 카카오계정 관리 메뉴에서 연결 끊기 기능을 제공합니다. 이 기능을 사용해 연결 끊기 알림 및 서비스 서버의 처리가 정상적으로 이뤄지는지 확인할 수 있습니다.

카카오톡 채널 관계 알림

카카오톡 채널 관계 알림 기능을 적용하면 사용자의 카카오톡 채널 추가 및 삭제 사실을 알림 받아 사용자의 카카오톡 채널 추가 상태를 최신 정보로 갱신할 수 있습니다.

이 기능을 사용하려면 먼저 카카오톡 채널 관계 알림을 참고하여 콜백 URL을 지정해야 합니다. 콜백은 리다이렉트를 지원하지 않습니다.

앱 사용자가 [내 애플리케이션] > [비즈니스] > [연결된 비즈니스 채널]에 해당하는 카카오톡 채널을 추가하거나 삭제할 때, 카카오 서버는 등록된 콜백 URL로 다음과 같은 형태의 알림을 보냅니다. 아래 정보를 참고해 카카오 서버가 보내는 요청을 서비스 서버가 받아 처리하는 기능을 구현해야 합니다.

카카오 서버가 보낸 요청을 받으면 Authorization 헤더 값으로 전달된 앱 어드민 키로 유효한 콜백인지 판단하여 처리합니다. 또한 타임아웃 시간(3초) 이내에 HTTP status "200 OK"로 응답해야 합니다.

URL
Method Request URL
POST [내 애플리케이션] > [카카오톡 채널] > [카카오톡 채널 추가/차단 콜백]에 설정된 URL
Header
Name Type Description Required
Authorization String 유효한 요청인지 판단할 수 있도록 전달하는 앱 어드민 키
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description
event String 사용자와 카카오톡 채널의 관계 변경사항, 추가(added) 또는 차단(blocked)
id String 카카오톡 채널 추가 또는 차단한 사용자 식별자
id_type String 식별자 타입, app_user_id 또는 open_id
app_user_id: 카카오 로그인 동의 항목 중 [카카오톡 채널 추가 상태 및 내역]에 동의한 사용자
open_id: [카카오톡 채널 추가 상태 및 내역]에 동의하지 않은 사용자
channel_public_id String 사용자와 카카오톡 채널의 관계가 변경된 카카오톡 채널의 프로필 ID
채널 URL에서 https://pf.kakao.com/ 부분을 제외한 뒷자리 값
예) 채널 URL이 https://pf.kakao.com/_ZeUTxl인 경우, 카카오톡 채널의 프로필 ID는 _ZeUTxl
channel_uuid String 카카오톡 채널의 검색용 ID
updated_at Datetime 카카오톡 채널 관계가 변경된 시간, UTC*
(RFC3339 internet date/time format)

* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고

* plus_friend_public_id: Deprecated, 카카오톡 채널의 프로필 ID(String), channel_public_id를 사용하도록 변경, 공지 참고

* plus_friend_uuid: Deprecated, 카카오톡 채널의 검색용 ID(String), channel_uuid를 사용하도록 변경, 공지 참고

* timestamp: Deprecated, 카카오톡 채널 관계가 변경된 시간(Long, 단위: ms), updated_at을 사용하도록 변경

Sample
curl -X POST "${YOUR_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":"2019-11-21T10:14:07Z"
    }'

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

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

이 기능을 사용하려면 먼저 카카오톡 공유 전송 성공 알림 설정을 참고하여 콜백 URL과 요청 방법(Method)을 설정해야 합니다. 콜백은 리다이렉트를 지원하지 않습니다.

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

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

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

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

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

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

URL
Method Request URL
GET / POST [내 애플리케이션] > [메시지] > [콜백 URL]에 설정된 URL
Header
Name Type Description Required
Authorization String 유효한 요청인지 판단할 수 있도록 전달하는 앱 어드민 키
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
X-Kakao-Resource-ID String 카카오톡 공유 알림(콜백)별 유니크 ID
(예: Rvy1c2dkzBAZ5hGD3rqYbxvr)
O
User-Agent String 카카오에서 보낸 요청임을 알리기 위한 문자열
KakaoOpenAPI/1.0
O
Parameter
  • 콜백은 아래 파라미터 외에 serverCallbackArgs 파라미터로 전달된 키와 값을 포함합니다.
Name Type Description Required
CHAT_TYPE String 카카오톡 공유 메시지가 전달된 채팅방의 타입
MemoChat: 나와의 채팅방
DirectChat: 다른 사용자와의 1:1 채팅방
MultiChat: 다른 사용자들과의 그룹 채팅방
O
HASH_CHAT_ID String 카카오톡 공유 메시지를 수신한 채팅방의 참고용 ID
서비스별로 유일(Unique)한 해시(Hash) 값으로, 같은 채팅방이라도 서비스마다 다른 값 제공
O
TEMPLATE_ID Long 메시지 템플릿 ID를 사용해 카카오톡 공유 메시지를 보낸 경우 사용된 메시지 템플릿의 ID, 메시지 템플릿 ID를 사용해 요청하지 않은 경우 전달되지 않음 X
Sample
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 ${APP_ADMIN_KEY}" \
    -H "X-Kakao-Resource-ID: ${UNIQUE_ID}" \
    -H "User-Agent: KakaoOpenAPI/1.0"
curl -v POST "${YOUR_KAKAOLINK_CALLBACK_URL}" \
    -H "Authorization: KakaoAK ${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"
        }'