카카오톡 공유하기 API: SDK·템플릿·도메인 설정

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

카카오톡 공유하기는 이용자가 서비스의 콘텐츠를 카카오톡 친구나 대화방에 직접 공유하는 기능입니다. 웹에서는 Kakao JavaScript SDK를 사용하며, 서비스가 먼저 보내는 알림톡과는 다릅니다. 오늘은 도메인 설정과 SDK 초기화, 템플릿과 웹훅을 알아보겠습니다.

카카오톡 공유하기 API는 무엇을 대신해 주나

카카오톡 공유는 사용자가 서비스의 콘텐츠를 자기 카카오톡 친구나 대화방으로 보내는 기능입니다. API를 호출하면 카카오톡이 열리고 사용자가 받을 사람을 고르면 메시지가 나가므로, 친구 선택 화면은 따로 만들 필요가 없습니다.

카카오톡 공유는 REST API를 지원하지 않습니다.

카카오디벨로퍼스 문서 기준 Kakao SDK로만 쓸 수 있고 웹에서는 JavaScript SDK의 Kakao.Share 모듈이 맡습니다.

서비스가 직접 보내는 메시지와는 다른 제품입니다.

서비스가 고객에게 먼저 안내를 보낼 때는 알림톡이나 브랜드 메시지를 씁니다.

카카오 디벨로퍼스 설정, 도메인을 두 곳에 등록합니다

카카오디벨로퍼스는 2025년 12월 3일 콘솔 개편 때 [앱] > [플랫폼] > [사이트 도메인] 한 곳이던 웹 도메인을 목적별로 둘로 나눴습니다.

JavaScript 키는 [앱] > [플랫폼 키]에서 확인합니다.

앱을 만들면 하나가 발급되는데 개편 뒤로는 키 종류별로 최대 5개까지 늘릴 수 있습니다.

SDK를 부를 사이트는 JavaScript SDK 도메인에 넣습니다.

경로는 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]이고 최대 10개까지 넣을 수 있습니다. 여기 없는 도메인에서 온 요청은 거절됩니다.

메시지 속 링크 도메인은 제품 링크 관리에 따로 넣습니다.

[앱] > [제품 링크 관리] > [웹 도메인]에 등록한 도메인만 메시지 링크로 연결되며 처음 넣은 도메인이 기본값이 됩니다.

Kakao SDK 초기화와 sendDefault 호출 순서

SDK 스크립트에는 버전과 integrity 값을 정확히 적습니다.

값은 다운로드 페이지에서 복사하고 초기화는 JavaScript 키로 합니다.

<script src="https://t1.kakaocdn.net/kakao_js_sdk/${VERSION}/kakao.min.js" integrity="${INTEGRITY_VALUE}" crossorigin="anonymous"></script>
<script>
  Kakao.init("${JAVASCRIPT_KEY}");
  console.log(Kakao.isInitialized());
</script>

직접 만든 버튼에는 Kakao.Share.sendDefault를 연결합니다.

SDK가 그려주는 버튼은 createDefaultButton으로 부릅니다. 피드 템플릿의 최소 구성은 이렇습니다.

Kakao.Share.sendDefault({
  objectType: "feed",
  content: {
    title: "봄 시즌 초대 이벤트",
    imageUrl: "https://example.com/event.jpg",
    link: { mobileWebUrl: "https://example.com/event", webUrl: "https://example.com/event" },
  },
});

기본 템플릿과 사용자 정의 템플릿, 무엇을 고를까

문구를 자주 바꾸는 마케팅 팀이라면 사용자 정의 템플릿이 편합니다.

고친 내용이 배포 없이 반영되는 대신, 사용자 인자를 templateArgs로 빠뜨리면 ${KEY}가 메시지에 그대로 찍힙니다.

매장 위치를 담는다면 기본 템플릿의 위치형을 씁니다.

버튼을 누르면 카카오맵으로 장소가 열리니 카카오맵 API 글에서 다룬 지도 화면과도 잘 맞습니다.

공유 이미지·OG 태그·웹훅과 자주 나는 오류

공유 이미지와 OG 태그

이미지는 외부에서 접근할 수 있는 URL로 제공하고, 사용하는 템플릿의 크기·비율·용량 조건을 확인합니다. URL만 넘기는 스크랩 방식은 og:title, og:description, og:image로 메시지를 만드니 OG 태그를 먼저 점검해야 합니다.

발송 결과는 serverCallbackArgs로 받습니다.

발송이 카카오톡 안에서 일어나 서비스는 성공 여부를 알 길이 없습니다. [앱] > [웹훅] > [카카오톡 공유 웹훅]에 URL을 등록해 두어도 이 값을 넣지 않으면 웹훅은 오지 않습니다.

공유 API의 쿼터와 유료 사용 조건

무료 제공량과 초과 요금은 앱의 사용 조건과 현재 쿼터 정책에 따라 확인합니다. 서비스 공개 전 콘솔의 사용량·유료 설정과 정책 변경 공지를 살펴보면 예상 비용을 계산하기 쉽습니다.

domain mismatched는 SDK 도메인, 4002는 링크 도메인부터 봅니다.

호출 사이트가 SDK 도메인에 없으면 domain mismatched, 링크 도메인이 웹 도메인에 없거나 템플릿 ID가 틀리면 4002입니다.

세부 항목과 최신 적용 조건은 카카오톡 공유 JavaScript 가이드를 참고해 보세요.

공유한 콘텐츠가 새로운 방문으로 이어지도록

서비스에 필요한 연동 기능을 하나씩 붙이다 보면 화면뿐 아니라 데이터와 운영 방식도 함께 살펴보게 됩니다. 지금 서비스에 필요한 범위부터 차근차근 정리해볼 수 있습니다.

똑똑한개발자는 UX/UI 디자인과 웹·앱 개발을 함께 진행합니다. 사용자가 이용하는 화면과 운영에 필요한 기능을 연결해 서비스를 만들어가는 과정을 돕습니다.

서비스에 필요한 연동 기능을 준비하면서 궁금한 점이 있다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)