이해하기

이 문서는 메시지 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로 사용자의 카카오톡 친구에게 카카오톡 메시지를 보내는 과정은 3단계로 나뉩니다. 카카오톡 친구가 아닌 사용자 자신에게 메시지를 보낼 때는 2~3번 과정만 수행합니다.

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

이용 정책

사용 권한 신청

카카오톡 메시지 API 중 친구에게 보내기 API는 사용 권한이 주어진 앱에서만 사용할 수 있습니다. 사용 권한을 받기 전에는 앱의 팀원에게만 사용 가능하도록 기능 동작이 제한됩니다. 실제 서비스에서 모든 사용자에게 기능을 사용하려면 [내 애플리케이션] > [앱 권한 신청]에서 사용 권한을 신청해야 합니다.

사용 권한 신청 전 아래 과정을 선행해야 합니다.

1. 동의항목을 참고해 [카카오톡 메시지 전송(talk_message)] 동의항목 설정
2. 친구에게 보내기 API를 사용한 기능 구현
3. 앱의 팀원을 대상으로 기능이 정상 동작하는지 확인

사용 권한을 받으면 서비스의 모든 사용자에게 친구에게 메시지 API 기능을 제공할 수 있습니다.

쿼터

카카오 API는 원활한 서비스 제공을 위해 월간 및 일일 쿼터(Quota, 사용량 제한)를 적용합니다. 현재 적용 중인 쿼터 정보는 쿼터에서 확인할 수 있습니다.

카카오톡 공유

카카오톡 공유 API 쿼터는 앱 권한 신청으로 적용된 한도의 상향 권한을 신청할 수 있습니다. 이외의 협의 및 제휴는 별도 문의합니다.

카카오톡 메시지

카카오톡 메시지 API는 사용 권한 신청 전에는 쿼터 한도가 제한되며, 빈번한 메시지로부터 사용자를 보호하기 위해 쿼터 한도 상향이 불가능합니다.

프로필 공개 설정

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

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

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

지원하는 기능

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

카카오톡 공유

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

카카오톡 메시지

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