페이지 이동경로
  • 문서>
  • 카카오톡 공유>
  • FAQ

카카오톡 공유

FAQ

이 문서는 카카오톡 공유에 대해 자주 묻는 질문과 답변을 제공합니다.

문제가 발생하는 원인은 상황에 따라 다양합니다. 아래 방법으로도 문제가 해결되지 않으면 데브톡으로 문의합니다.

Q. 사이트 주소 변경 후 발송 오류가 발생합니다.

카카오톡 공유 API를 Kakao SDK for JavaScript로 호출하는 경우, JavaScript SDK 도메인에 등록된 도메인에서만 정상 동작합니다. 카카오톡 공유 내 웹 링크와 앱 링크는 제품 링크 관리에 등록된 웹 도메인과 네이티브 앱 스킴에 해당하는 경우만 연결이 허용됩니다.

Q. 메시지는 어떻게 구성하나요?

메시지 템플릿을 참고합니다.

Q. 카카오톡 공유 API는 무료인가요?

네, 카카오톡 공유 API는 주어진 쿼터 내에서 무료로 사용할 수 있습니다.

기본 제공량 이상 호출하려면 유료 사용 설정 후 필요한 만큼 사용할 수 있습니다.

Q. 4002 에러가 발생해요.

원인
  • 공유한 URL의 도메인이 [앱] > [제품 링크 관리] > [웹 도메인]에 등록되지 않은 경우
  • 요청한 메시지 템플릿의 규격이 맞지 않는 경우
  • 카카오톡 공유 시 사용한 메시지 템플릿 ID가 유효하지 않은 경우
  • SDK 버전이 낮아 카카오톡 공유 기능이 지원되지 않는 경우
해결 방법
  1. 공유한 URL의 도메인이 제품 링크 관리의 웹 도메인에 등록되어 있는지 확인합니다.
  2. 메시지 템플릿을 사용할 때, 올바른 규격에 맞게 API를 호출합니다. (참고: 개발 문서)
  3. 앱에 등록한 메시지 템플릿의 ID가 맞는지 확인한 후, 다시 요청합니다. (참고: 사용자 정의 템플릿)
  4. 최신 버전의 SDK를 사용하도록 수정합니다.

Q. 4019 에러가 발생해요.

invalid android_key_hash or ios_bundle_id or web_site_url

{"error":"misconfigured","error_description":"invalid android_key_hash or ios_bundle_id or web_site_url","error_code":"KOE009"}
원인
  • 앱에서 전달한 키 해시가 등록된 키 해시와 다른 경우
  • 앱에 등록된 번들 ID가 실제 서비스와 다른 경우
  • 앱에 등록한 JavaScript SDK 도메인과 요청에서 전달된 도메인이 다른 경우
해결 방법
  1. 플랫폼 정보가 실제 서비스와 일치하는지 확인합니다. (참고: 플랫폼 키)
  2. [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에서 등록한 도메인 목록에 전달한 도메인(caller 값)이 포함되어 있는지 확인합니다.
  3. 안드로이드의 경우, 앱에서 사용하는 키 해시가 카카오디벨로퍼스에 등록된 키 해시와 일치하는지 확인하고, 필요시 네이티브 앱 키를 참고해 추가 등록합니다.
  4. Google Apps Script 웹 앱을 사용하는 경우, Google Apps Script 웹 앱을 사용하는 경우를 참고하해 도메인을 등록합니다.
  5. App Distribution으로 배포한 앱의 경우, App Distribution으로 배포한 앱의 경우를 참고해 실제 배포 앱의 키 해시를 확인 및 등록합니다.
참고 문서

domain mismatched

[-401] domain mismatched! caller=https://xx. check out registered web domains.
원인
  • 앱에 등록한 도메인과 실제 API 요청에서 전달된 도메인이 일치하지 않은 경우
해결 방법
  1. [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에서 등록한 도메인 목록에 전달한 도메인(caller 값)이 포함되어 있는지 확인합니다.
  2. Google Apps Script 웹 앱을 사용하는 경우, Google Apps Script 웹 앱을 사용하는 경우를 참고해 도메인을 등록합니다.

wrong appKey(null) format

{"name":"KAPIError","msg":"wrong appKey(null) format","code":-401}
원인
  • 도메인을 등록한 앱의 키가 아닌 다른 앱의 키를 사용해 API를 호출한 경우
  • 사용하는 플랫폼에 맞지 않는 앱 키를 사용해 API를 호출한 경우
  • 앱 키 값이 누락되거나 오타가 있는 경우
해결 방법
  1. 카카오디벨로퍼스에서 JavaScript SDK 도메인을 등록한 앱의 JavaScript 키를 사용해 API를 호출했는지 확인합니다.
  2. 사용하려는 플랫폼에 맞는 앱 키를 사용했는지 확인합니다. (참고: 플랫폼 키)
  3. 키 값 전체가 누락 없이 잘 전달되었는지 확인합니다.

Google Apps Script 웹 앱을 사용하는 경우

  1. [JavaScript SDK 도메인]에 전체 URL이 아닌 기본 도메인만 등록되어 있는지 확인합니다.
    • (O) https://script.google.com
    • (X) https://script.google.com/macros/s/AKfycb.../exec
  2. 웹 앱이 iframe 내에서 실행될 경우, iframe이 로드된 실제 도메인을 사이트 도메인으로 등록했는지 확인합니다. GAS 웹 앱의 경우 https://script.google.com/macros/... 패턴의 URL로 제공되지만, 실제 콘텐츠는 iframe으로 로드되므로 도메인 정보가 iframe이 로드한 도메인과 다를 수 있습니다.
  3. URL 단축 서비스(예: bit.ly)를 사용하는 경우, 최종 리다이렉트되는 도메인을 JavaScript SDK 도메인으로 등록합니다. 단축 URL의 경우, 유효한 도메인으로 인식되지 않을 수 있습니다.

App Distribution으로 배포한 앱인 경우

  1. 배포한 앱에서 어떤 키 해시를 사용하는 지 확인하기 위해 앱 내에서 키 해시를 출력해 로깅합니다.
    • Android: Log.d("KakaoSDK", message)
    • iOS: print("KakaoSDK: (message)")
    • JavaScript: console.log("KakaoSDK:", message)
    • Flutter: print(await KakaoSdk.origin)
  2. 로깅된 키 해시와 카카오디벨로퍼스에 등록된 키 해시를 비교합니다. 만약 두 키해시가 일치하지 않는다면, 카카오디벨로퍼스에서 확인한 키 해시를 앱에 추가로 등록합니다.
  3. 그래도 해결되지 않는다면, 앱 서명 키 인증서가 변경될 수 있으므로 구글 플레이 콘솔에서 앱 서명 키 인증서의 SHA-1 지문을 다시 확인하고 키 해시를 재생성합니다. 재생성한 키 해시는 카카오디벨로퍼스에 추가로 등록해야 합니다.

Q. 5001 에러가 발생해요.

원인
  • 파라미터 구성이 잘못된 경우
  • 파라미터로 전달한 이미지 URL이 외부에서 접근 불가(예: 사내망, 방화벽 등)하여 카카오 이미지 스크랩 서버가 접근에 실패한 경우
  • 브라우저에서 쿠키 사용이 제한된 경우 (참고: 쿠키 제한 환경에서 발생하는 오류)
  • 브라우저에서 크롬 확장 프로그램(Extension) 등 외부 요소에 의해 쿠키가 정상적으로 동작하지 않은 경우
해결 방법
  • 카카오톡 공유에 사용된 이미지가 유효한지 확인합니다.
  • 카카오톡 공유에 사용된 이미지가 외부에서 접근 가능한지 확인합니다.
    • 서비스 서버에서 방화벽을 사용하는 경우, 카카오 스크랩 서버의 접근을 차단해 이미지가 표시되지 않을 수 있습니다. 방화벽을 참고해 ACL(Access Control List, 접근 제어 목록)에 카카오 스크랩 서버의 IP를 등록합니다.
  • 브라우저의 쿠키 사용 설정이 꺼져 있지 않은지 확인합니다.
  • 시크릿(시크릿/인프라이빗) 모드에서 카카오톡 공유 기능을 다시 시도해 봅니다. 정상 동작하는 경우, 크롬 등 브라우저에 설치된 확장 프로그램 중 쿠키나 브라우저 동작에 영향을 줄 수 있는 확장 프로그램을 비활성화한 후 다시 시도합니다.
참고: 쿠키 제한 환경에서 발생하는 오류

카카오 로그인과 카카오톡 공유 기능은 Cross-Site Request Forgery(CSRF) 공격을 막기 위해 CSRF 토큰을 검증합니다.

쿠키가 정상적으로 동작하지 않는 환경에서는 정상적인 API 요청도 실패할 수 있습니다. 쿠키 사용이 제한된 브라우저는 서버로 세션 ID를 보내지 못해 서버는 사용자의 세션을 찾지 못하고, 유효한 CSRF 토큰을 확인할 수 없게 됩니다. 결과적으로 요청은 유효하지 않은 토큰으로 간주되어 에러가 발생합니다.

카카오톡 공유> FAQ