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

카카오톡 공유

FAQ

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

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

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

카카오톡 공유 API는 앱의 플랫폼 설정에 등록된 도메인에서만 정상 동작합니다. 이용 시 웹, Android, iOS 중 서비스에서 사용 중인 플랫폼을 반드시 등록해야 하며, 사이트 주소 변경 시 바뀐 도메인을 플랫폼 정보에 추가해야 합니다. 메시지에 포함된 버튼과 링크는 앱 설정을 바탕으로 설정되며, 등록되지 않은 도메인 주소는 메시지 링크에 사용할 수 없습니다.

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

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

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

네, 카카오톡 공유 API는 무료입니다.

다만, 사용량 제한이 있습니다. 자세한 정보는 쿼터를 참고합니다.

기본 제공량 이상 호출하려면 쿼터 상향을 신청합니다.

Q. 카카오톡 공유 쿼터 상향 기간 중 추가 쿼터 사용이 필요할 경우 어떻게 하면 되나요?

쿼터 상향이 승인된 기간 동안은 시스템상 추가적으로 쿼터 신청을 할 수 없습니다. 사용량 변화로 추가 쿼터 상향이 필요할 경우, 데브톡으로 문의합니다.

Q. 쿼터 상향 심사 기간은 얼마나 걸리나요?

카카오톡 공유 쿼터 상향 심사는 영업일 기준 약 3~5일이 소요됩니다. 안정적인 서비스 운영을 위해, 쿼터 상향이 필요한 시작일보다 충분히 여유를 두고 미리 신청해 주시기 바랍니다.

심사 결과가 지연되거나 반려된 경우에는 데브톡으로 문의합니다.

Q. 개발 운영 대행사에서 카카오톡 공유 쿼터 상향 신청을 대신 할 수 있나요?

카카오톡 공유 쿼터 상향은 신청하려는 앱의 오너 또는 에디터로 등록된 계정만 신청할 수 있습니다.

추가 기능 신청 페이지에서 [신청] 버튼이 비활성화된 경우, 서비스의 앱 관리자에게 개발 운영 행사의 카카오디벨로퍼스 계정을 멤버로 추가해 달라고 요청합니다.

해당 앱의 신청 권한을 오너로 부터 부여 받아 진행해 주시기 바랍니다.

Q. 4002 에러가 발생해요.

원인
  • 공유한 URL의 도메인이 앱의 Web 플랫폼에 등록되지 않은 경우
  • 요청한 메시지 템플릿의 규격이 맞지 않는 경우
  • 카카오톡 공유 시 사용한 메시지 템플릿 ID가 유효하지 않은 경우
  • SDK 버전이 낮아 카카오톡 공유 기능이 지원되지 않는 경우
해결 방법
  1. 공유한 URL의 도메인이 카카오디벨로퍼스 앱의 Web 플랫폼에 등록되어 있는지 확인합니다. (참고 플랫폼)
  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가 실제 서비스와 다른 경우
  • 앱에 등록한 도메인과 요청에서 전달된 도메인이 다른 경우
해결 방법
  1. Web, Android, iOS 플랫폼 정보가 실제 서비스와 일치하는지 확인합니다. (참고: 플랫폼)
  2. [앱] > [일반] > [플랫폼] > [Web]에서 등록한 도메인 목록에 요청에서 전달된 도메인(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. [앱] > [일반] > [플랫폼] > [Web]에서 등록한 도메인 목록에 요청에서 전달된 도메인(caller 값)이 포함되어 있는지 확인합니다.
  2. Google Apps Script 웹 앱을 사용하는 경우, Google Apps Script 웹 앱을 사용하는 경우를 참고해 도메인을 등록합니다.

wrong appKey(null) format

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

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

  1. Web 플랫폼 정보에 전체 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)를 사용하는 경우, 최종 리다이렉트되는 도메인을 사이트 도메인으로 등록합니다. 단축 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