kakao developers

이해하기

이 문서는 메시지 API를 소개합니다.

기능 소개

메시지 API는 사용자가 카카오톡 친구에게 카카오톡 메시지를 보내는 기능을 제공합니다. 이 API는 메시지를 통한 정보 공유 및 서비스 재방문 효과에 초점을 두고 만들어졌습니다. 메시지 API로 보낸 메시지는 카카오디벨로퍼스(Kakao Developers, 이하 개발자 웹사이트)에 등록된 애플리케이션(이하 앱) 정보를 담고 있어, 사용자가 메시지를 통해 서비스 웹사이트나 앱을 방문할 수 있습니다.

메시지 API로 보낼 카카오톡 메시지는 공유할 정보의 특징이나 메시지의 성격에 따라 적합한 템플릿을 선택하여 구성할 수 있습니다. 지원하는 메시지의 종류와 만드는 방법은 메시지 템플릿을 참고합니다.

메시지를 보내는 방법은 크게 두 가지로, 카카오톡 공유 API를 사용하는 방법과 카카오톡 메시지 API를 사용하는 방법이 있습니다.

두 API의 차이점은 다음과 같습니다.

설명	카카오톡 공유 API	카카오톡 메시지 API
카카오톡 친구 목록 페이지	카카오톡 앱에서 카카오톡 친구 목록 이용	친구 목록 가져오기 API를 사용해 자체 구현
메시지 전송이 가능한 친구의 범위	카카오톡의 모든 친구	친구 목록 가져오기 API의 정보 제공 조건에 맞는 친구
카카오톡 앱으로 이동해 메시지 전송	O	X
메시지 전송 요청 실행	카카오톡	서비스 클라이언트 또는 서버
사용 신청 및 검수	X	O
REST API 지원	X	O
메시지 전송 성공 여부 확인	카카오톡 공유 전송 성공 알림 받기 기능을 사용해 자체 구현	API 응답으로 확인

카카오톡 공유 API는 서비스 클라이언트에서 카카오톡 앱을 실행시켜 카카오톡 메시지를 보내는 반면, 카카오톡 메시지 API는 카카오톡 앱을 실행시키지 않고 서비스 클라이언트나 서버를 통해 카카오톡 친구에게 메시지를 보낼 수 있도록 합니다. 대신, 두 가지 API 모두 카카오톡 메시지를 전송하므로 사용자 카카오계정에 연결된 카카오톡이 없는 상태, 즉 카카오톡 미사용자라면 메시지 보내기 요청 시 에러가 발생합니다.

카카오톡 공유 API는 카카오가 제공하는 카카오톡 친구 또는 대화 목록 페이지를 띄워 사용자가 메시지를 보낼 수 있도록 합니다. 따라서 서비스가 카카오톡 친구 정보를 출력하는 페이지를 직접 만들 필요가 없고, 모든 카카오톡 친구가 목록에 포함됩니다. 대신, 카카오톡 친구 정보를 데이터로 제공하지 않습니다. 카카오톡 공유 API는 웹 페이지 소스코드에 공유할 내용을 정의하는 등 상대적으로 간단하게 기능을 구현할 수 있습니다.

반면, 카카오톡 메시지 API는 친구 목록 가져오기 API를 통해 받은 친구 정보 중 지정한 친구에게 메시지를 보내는 기능을 제공합니다. 카카오톡 친구 정보를 데이터로 제공하지만 카카오톡 친구 목록 페이지를 띄워주지 않습니다. 따라서 서비스는 사용자의 카카오톡 친구 정보를 받아 처리하는 기능과 친구 목록을 직접 만들어야 합니다. 또한 친구 목록 가져오기 API와 카카오톡 메시지 API는 각각 사용 권한 신청이 필요합니다.

카카오톡 공유

카카오톡 공유는 사용자가 카카오톡 메시지로 친구에게 메시지에 담긴 정보를 공유하는 기능입니다. 사용자는 카카오톡 공유가 적용된 웹 페이지 또는 특정 정보를 자신의 카카오톡 친구에게 공유할 수 있습니다.

카카오톡 공유는 Kakao SDK for JavaScript, Android, iOS로만 제공되며, REST API로는 제공되지 않습니다. 이 기능은 최대한 간편하게 카카오톡으로 메시지를 보내 정보를 공유하는 기능을 구현할 수 있도록 만들어졌기 때문에, 카카오톡을 거치지 않고 메시지를 보내는 REST API 방식은 카카오톡 공유가 아닌 카카오톡 메시지 API로만 사용할 수 있습니다.

카카오톡 공유로 메시지를 보내는 과정을 간략히 정리하면 2단계로 나눌 수 있습니다.

1. 메시지 템플릿을 참고하여 보낼 메시지 내용 구성하기
2. 구성한 메시지를 전달 인자로 카카오톡 공유 API 호출하여 메시지 전송을 요청하기

카카오톡 공유 API가 제공하는 기능 및 가이드는 다음과 같습니다.

기능	설명	가이드
기본 템플릿으로 메시지 보내기	카카오에서 제공하는 템플릿 형식에 따라 메시지의 구성 요소 값을 JSON 형식이나 객체 형태로 직접 정의하고 전송하는 기능	JavaScript SDK Android SDK iOS SDK
사용자 정의 템플릿으로 메시지 보내기	개발자 웹사이트에 등록한 사용자 정의 템플릿을 사용해 구성한 메시지를 전송하는 기능	JavaScript SDK Android SDK iOS SDK
기본 템플릿으로 스크랩 메시지 보내기	스크랩한 웹 페이지 정보를 바탕으로 메시지를 구성하여 전송하는 기능	JavaScript SDK Android SDK iOS SDK
사용자 정의 템플릿으로 스크랩 메시지 보내기	스크랩한 웹 페이지 정보를 사용자 정의 템플릿을 바탕으로 메시지를 구성하여 전송하는 기능	JavaScript SDK Android SDK iOS SDK
카카오톡 공유 전송 성공 알림	카카오톡 공유를 통해 보낸 메시지가 정상적으로 전달되었음을 알려주는 기능, 플랫폼별 가이드에서 사용자 정의 파라미터 설정 필요	설정하기 JavaScript SDK Android SDK iOS SDK 콜백 알림 정보

카카오톡 메시지

카카오톡 메시지 API로 사용자의 카카오톡 친구에게 카카오톡 메시지를 보내는 과정은 3단계로 나뉩니다. 카카오톡 친구가 아닌 사용자 자신에게 메시지를 보낼 때는 2~3번 과정만 수행합니다.

1. 친구 목록 가져오기 API로 카카오톡 친구 정보를 받아 서비스 UI로 보여주고, 메시지를 보낼 친구 선택하게 하기
2. 메시지 템플릿을 참고하여 보낼 메시지 내용 구성하기
3. 구성한 메시지의 타입과 전송 대상에 맞는 카카오톡 메시지 보내기 API 호출하기

카카오톡 메시지 API가 제공하는 기능 및 가이드는 다음과 같습니다.

기능	설명	가이드
기본 템플릿으로 메시지 보내기	카카오에서 제공하는 템플릿 형식에 따라 메시지의 구성 요소 값을 JSON 형식이나 객체 형태로 직접 정의하고 전송하는 기능	REST API JavaScript SDK Android SDK iOS SDK
사용자 정의 템플릿으로 메시지 보내기	개발자 웹사이트에 등록한 사용자 정의 템플릿을 사용해 구성한 메시지를 전송하는 기능	REST API JavaScript SDK Android SDK iOS SDK
기본 템플릿으로 스크랩 메시지 보내기	스크랩한 웹 페이지 정보를 바탕으로 메시지를 구성하여 전송하는 기능	REST API JavaScript SDK Android SDK iOS SDK
사용자 정의 템플릿으로 스크랩 메시지 보내기	스크랩한 웹 페이지 정보를 사용자 정의 템플릿을 바탕으로 메시지를 구성하여 전송하는 기능	REST API JavaScript SDK Android SDK iOS SDK

이용 정책

사용 권한 신청

카카오톡 메시지 API 중 친구에게 보내기 기능은 기본적으로 앱의 팀원에 한해 동작합니다. 실제 서비스에서 앱의 팀원 뿐만 아니라 서비스의 모든 사용자가 카카오톡으로 친구에게 메시지를 보내려면 다음 순서로 사용 권한을 신청해야 합니다.

1. 동의 항목 설정을 참고하여 [카카오톡 메시지 전송] 동의 항목을 설정합니다.
2. 친구에게 보내기 기능을 구현합니다.
3. 앱의 팀원을 대상으로 친구에게 보내기 기능이 정상 동작하는지 확인합니다.
4. 기능 정상 동작 확인 후, 데브톡에서 [새 주제 만들기]에 [메시지 API 사용 신청] 카테고리를 선택하고, 양식에 따라 신청 게시물을 작성합니다.

카카오 플랫폼 관리자가 신청 내용을 확인한 뒤 메시지 API 사용 권한 제공 여부를 답변합니다. 검수를 거쳐 사용 권한을 받으면 서비스의 모든 사용자가 카카오톡으로 친구에게 메시지를 보낼 수 있습니다.

쿼터

카카오 API는 플랫폼 이용 정책에 따른 사용량 제한이 있습니다. 또한, 카카오톡 메시지 API는 사용 권한 신청 전에는 사용량이 제한됩니다. 앱 및 API마다 할당된 사용량을 초과하면 에러가 발생하며 더 이상 API를 사용할 수 없습니다. 할당된 사용량을 늘리려면 별도의 협의 및 제휴가 필요합니다. 단, 카카오톡 메시지의 경우 빈번한 메시지로부터 사용자를 보호하기 위하여 쿼터 증설이 불가능합니다. 제휴 안내는 데브톡으로 문의합니다.

프로필 공개 설정

카카오톡 메시지 API를 통해 발송된 메시지의 말풍선에는 프로필 공개 설정 버튼이 제공됩니다. 사용자는 해당 버튼을 눌러 해당 앱의 친구 목록에 자신을 노출할 것인지 공개 여부를 설정할 수 있습니다. 이 설정이 비공개인 사용자는 피커의 친구 목록과 친구 목록 가져오기 응답에 포함되지 않으므로, 카카오톡 메시지를 보낼 때 필요한 수신자 uuid 조회가 불가능하므로 메시지를 보낼 수 없습니다. 자세한 안내는 프로필 공개 설정을 참고합니다.

스크랩 허용을 위한 방화벽 설정

서비스 서버의 방화벽에서 카카오 스크랩 서버의 접근을 차단한 경우, 카카오톡 공유 전송이 매우 느리거나 이미지가 표시되지 않을 수 있습니다. 이 경우, 데브톡 FAQ를 참고해 ACL(Access Control List)에 카카오 스크랩 서버의 IP를 허용해야 합니다.

지원하는 기능

• 각 API 및 기능의 Kakao SDK 지원 여부는 지원 범위에서 확인할 수 있습니다.

카카오톡 공유

API 및 기능	설명
기본 템플릿으로 메시지 보내기	기본 템플릿을 사용해 카카오톡으로 메시지를 공유합니다.
사용자 정의 템플릿으로 메시지 보내기	사용자 정의 템플릿을 사용해 카카오톡으로 메시지를 공유합니다.
기본 템플릿으로 스크랩 메시지 보내기	지정한 웹 페이지를 스크랩한 정보로 스크랩 메시지를 구성하여 공유합니다.
사용자 정의 템플릿으로 스크랩 메시지 보내기	사용자 정의 템플릿에 지정한 웹 페이지의 스크랩 정보를 대입해 메시지를 구성하고 공유합니다.
이미지 업로드하기	카카오 서버에 이미지를 업로드합니다.
이미지 스크랩하기	카카오 서버에 이미지를 스크랩합니다.
이미지 삭제하기	카카오 서버에 업로드한 이미지를 삭제합니다.
카카오톡 공유 전송 성공 알림 받기	카카오톡 공유 메시지가 성공적으로 전달된 경우 서비스 서버에 알려줍니다. 카카오톡 공유 메시지는 카카오톡에서 발송되므로, 알림 받기를 통해서만 전송 성공 여부를 알 수 있습니다.

카카오톡 메시지

API 및 기능	설명
기본 템플릿으로 메시지 보내기	기본 템플릿을 사용해 카카오톡 메시지를 보냅니다.
사용자 정의 템플릿으로 메시지 보내기	사용자 정의 템플릿을 사용해 카카오톡 메시지를 보냅니다.
기본 템플릿으로 스크랩 메시지 보내기	지정한 웹 페이지를 스크랩한 정보로 스크랩 메시지를 구성해 카카오톡 메시지를 보냅니다.
사용자 정의 템플릿으로 스크랩 메시지 보내기	지정한 웹 페이지의 스크랩 정보를 사용자 정의 템플릿에 대입해 카카오톡 메시지를 보냅니다.