이해하기

이 문서는 카카오톡 소셜 API를 소개합니다.

기능 소개

카카오톡 소셜 API는 서비스의 소셜 기능 구현을 위한 사용자의 카카오톡 프로필과 친구 정보를 제공합니다. 제공받은 카카오톡 친구 정보를 토대로 카카오톡 메시지를 보낼 수도 있습니다.

* 카카오톡 프로필 및 친구 정보를 활용한 서비스 UI 예시

카카오톡 프로필

사용자의 카카오톡 프로필 정보를 제공하는 카카오톡 프로필 API를 제공합니다. 카카오 API를 통해 제공되는 프로필은 카카오계정의 프로필과 카카오톡의 프로필 두 가지이며, 두 프로필은 서로 일치하지 않을 수 있습니다. 서비스에서 카카오톡과 밀접하게 관련된 소셜 기능을 구현하기 위해 카카오톡의 프로필을 지정하여 제공받고 싶은 경우 카카오톡 프로필 API를 사용합니다.

참고: 카카오계정 프로필

카카오 로그인의 사용자 정보 가져오기 API를 사용하면 카카오계정의 프로필 정보를 받을 수 있습니다. 사용자가 카카오톡 또는 카카오계정 관리 페이지의 [설정] > [카카오계정] > [내정보 관리] > [프로필 업데이트 설정] 메뉴에서 [프로필 정보를 항상 최신으로 유지합니다] 옵션을 켠 경우, 카카오계정 프로필 정보가 카카오톡 프로필 정보와 동일하게 유지됩니다.

카카오톡 친구 정보

카카오톡 친구의 기본 정보와 프로필을 담은 데이터를 목록 형태로 제공합니다. 각 친구의 기본 정보는 카카오톡 메시지 전송 시 필요한 고유 ID(uuid) 값을 포함합니다.

카카오톡 친구 정보는 피커 또는 친구 목록 가져오기 API를 통해 제공받을 수 있습니다. 아래 표를 참고합니다.

구분	피커	친구 목록 가져오기 API
설명	서비스에서 Kakao SDK를 통해 피커 호출 시, 카카오에서 제공하는 친구 목록 피커 화면이 출력되고, 사용자가 선택한 친구의 데이터를 서비스에 제공	서비스의 API 요청 및 응답을 통해 사용자의 카카오톡 친구 목록 데이터 제공
활용	자체적인 친구 목록 UI 구현 없이 간편하게 카카오톡 친구 목록을 이용하고 싶은 경우 카카오톡 메시지 발송 등 사용자가 지정한 특정 친구의 데이터가 필요한 경우	서비스 UI에 맞춘 친구 목록을 직접 구현하여 제공하고 싶은 경우
친구 목록 UI 구현	불필요	필요
사용 환경	웹, 앱	서버, 웹, 앱
지원 범위	Kakao SDK for JavaScript, Android, iOS	REST API Kakao SDK for JavaScript, Android, iOS, Flutter

* 두 가지 방식 모두 친구 정보 제공 조건을 만족하는 친구의 데이터만 제공 가능

친구 피커

피커는 Kakao SDK를 통해 간편하게 친구 목록 UI와 친구 정보를 제공받을 수 있는 기능입니다. 피커는 파라미터 설정을 통해 원하는 화면 표시 형태, 선택 유형, 구성 요소 지정 기능을 제공합니다. 또한 기기의 언어 설정에 따라 다국어를 지원합니다. 아래 표와 예시 이미지를 참고합니다.

기능	상세
화면 표시 형태	풀 스크린 또는 팝업 비고: JavaScript SDK는 풀 스크린 형태만 제공
선택 유형	멀티 피커: 여러 대상 선택 가능, 선택 가능한 친구의 최대 및 최소 수 지정 가능 싱글 피커: 하나의 대상만 선택 가능
구성 요소	피커 화면 상단 제목 문구 변경, 내 프로필 표시 여부, 즐겨찾기 친구 표시 여부, 특정 친구 선택 불가 처리
다국어 지원	한국어, 영어, 일본어

이용 정책

사용 권한 신청

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

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

1. 동의항목을 참고해 [카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)(friends)] 동의항목 설정
2. 피커 또는 친구 목록 가져오기 API를 사용한 소셜 기능 구현
3. 앱의 팀원을 대상으로 기능이 정상 동작하는지 확인

사용 권한을 받으면 서비스의 모든 사용자에게 친구 목록 가져오기 API 기능을 제공할 수 있습니다. 또한 [카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)] 동의항목을 [선택 동의]로도 설정할 수 있습니다. 사용 권한을 받은 후에도 피커의 친구 목록과 친구 목록 가져오기 API의 응답은 친구 정보 제공 조건을 만족하는 친구 정보만 포함하는 점에 유의합니다.

쿼터

카카오 API는 원활한 서비스 제공을 위해 월간 및 일일 쿼터(Quota, 사용량 제한)를 적용합니다. 현재 적용 중인 쿼터 정보는 쿼터에서 확인할 수 있습니다. 적용된 쿼터 한도를 상향하기 위해서는 협의 및 제휴가 필요하므로 별도 문의합니다.

프로필 공개 설정

사용자는 [이 서비스의 친구 목록에 나를 보여주기] 설정에서 각 서비스의 친구 목록에 자신을 노출할 것인지 설정할 수 있습니다. 해당 설정은 메시지 말풍선 하단의 [설정] 버튼, 또는 카카오톡 [설정] > [카카오계정] > [연결된 서비스 관리]의 각 앱 정보 페이지에 위치합니다. 메시지 말풍선의 경우, 설정 버튼이 발신자의 말풍선에는 노출되지 않고 수신자의 말풍선에만 노출됩니다.

아래 설정 화면 이미지를 참고합니다.

프로필 공개 설정은 피커의 친구 목록과 친구 목록 가져오기 API 응답에 반영됩니다. 사용자가 [이 서비스의 친구 목록에 나를 보여주기]를 [비공개]로 설정했거나 [동의 철회]한 경우, 해당 사용자는 다른 사용자의 친구 목록 가져오기 응답에 포함되지 않습니다. 친구 목록 가져오기 응답의 친구 수에도 해당 사용자가 포함되지 않습니다.

카카오톡 메시지의 경우, 친구 목록 가져오기 API 응답으로 받은 uuid를 사용하므로, 프로필 공개 설정을 비공개로 설정한 사용자에게는 메시지를 보낼 수 없습니다.

프로필 정보 제공 기준

피커의 친구 목록과 친구 목록 가져오기 API의 응답은 멀티프로필의 영향을 받습니다. 멀티프로필은 카카오톡 사용자가 친구마다 다른 프로필을 보여주도록 설정하는 기능입니다.

카카오톡 프로필 정보는 닉네임(nickName), 프로필 이미지 URL(profileImageUrl), 카카오톡 프로필 썸네일 이미지 URL(thumbnailUrl)로 구성되어 있으며, 이 중 닉네임과 프로필 이미지는 다음과 같은 우선순위에 따라 친구 목록 가져오기 응답에 제공됩니다.

• 닉네임: 사용자가 설정한 친구 이름 > 사용자 주소록의 친구 이름 > 친구가 사용자에게 보이도록 설정한 멀티프로필 닉네임 > 친구가 설정한 기본 프로필 닉네임
• 프로필 이미지 URL: 친구가 사용자에게 보이도록 설정한 멀티프로필 이미지의 URL > 친구가 설정한 기본 프로필 이미지의 URL

사용자 자신의 프로필 정보를 요청하는 프로필 가져오기 API는 항상 사용자가 설정한 기본 프로필 정보를 사용하므로, 멀티프로필의 영향을 받지 않습니다.

친구 정보 제공 조건

피커의 친구 목록과 친구 목록 가져오기 API의 응답은 다음 조건을 모두 만족하는 친구만 포함합니다.

1. 친구가 앱과 연결된 상태일 것
2. 친구가 앱 연결 시 [카카오 서비스 내 친구 목록 제공] 동의항목에 동의한 상태일 것
3. 친구가 숨김 또는 차단 친구가 아닐 것
4. 친구의 프로필 공개 설정이 공개 상태일 것

위 조건과 관계없이 사용자의 모든 카카오톡 친구 정보를 요청하는 오픈 API는 제공되지 않습니다. 따라서 피커나 친구 목록 가져오기 API의 친구 수와 실제 카카오톡 친구 수는 다를 수 있습니다. 특정 친구가 응답에 포함되지 않은 경우에 대해서는 FAQ를 참고합니다.

친구 목록 가져오기 API 응답 캐시

친구 목록 가져오기 API는 10분의 응답 캐시가 있습니다. 한 번 친구 목록 가져오기 API를 요청하면, 캐시 시간인 10분 동안에는 친구 정보가 변경되더라도 이전 요청과 동일한 친구 목록으로 구성된 응답을 받습니다. 10분이 경과한 후 다시 친구 목록 가져오기 API를 요청해야 변경된 친구 목록을 받을 수 있습니다.

지원하는 기능

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

API 및 기능	설명	문서
프로필 가져오기	현재 로그인한 사용자의 카카오계정에 연결된 카카오톡 프로필 정보를 불러옵니다.	REST API JavaScript Android iOS Flutter
피커: 친구 선택하기	사용자가 카카오톡 친구를 선택할 수 있는 피커를 호출합니다.	JavaScript Android iOS Flutter
친구 목록 가져오기	현재 로그인한 사용자의 카카오계정에 연결된 카카오톡의 친구 정보를 불러옵니다.	REST API JavaScript Android iOS Flutter