페이지 이동경로
  • 문서>
  • 카카오톡 소셜>
  • 이해하기

카카오톡 소셜

이해하기

이 문서는 카카오톡 소셜 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. 피커 또는 친구 목록 가져오기 API를 사용한 소셜 기능 구현
    • 권한을 받기 전에도 개발 및 테스트를 위해 팀원에 한해 기능 동작
    • 앱의 팀원뿐 아니라 일반 사용자를 대상으로 친구 정보를 받으려면 권한 필요
  2. 앱의 팀원을 대상으로 기능이 정상 동작하는지 확인
  3. 데브톡에서 [새글 쓰기] 클릭 후, [친구 API 사용 신청] 카테고리를 선택하여 신청 양식 작성

카카오 플랫폼 관리자가 신청 내용을 확인한 뒤 친구 목록 가져오기 API 사용 권한 제공 여부를 답변합니다. 검수를 거쳐 사용 권한을 받으면 서비스의 모든 사용자가 친구 목록 가져오기 API 기능을 이용할 수 있습니다. 또한 [내 애플리케이션] > [동의항목] > [개인정보]에서 [카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)] 항목을 [선택 동의]로도 설정할 수 있습니다. 사용 권한을 받은 후에도 피커의 친구 목록과 친구 목록 가져오기 API의 응답은 친구 정보 제공 조건을 만족하는 친구 정보만 포함하는 점에 유의합니다.

주의

사용 권한이 필요한 기능이나 API의 경우, 사용 권한을 받기 전에는 테스트 목적에 맞게 기능 동작이 제한됩니다. 실제 서비스에서 기능을 정상적으로 사용하려면 반드시 검수를 거쳐 사용 권한을 받아야 합니다.

프로필 공개 설정

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

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

프로필 공개 설정 화면

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

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

친구 정보 제공 조건

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

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

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

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

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

프로필 정보 제공 기준

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

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

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

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

지원하는 기능

  • 각 API 및 기능의 Kakao SDK 지원 여부는 지원 범위에서 확인할 수 있습니다.
API 및 기능 설명
프로필 가져오기 현재 로그인한 사용자의 카카오계정에 연결된 카카오톡 프로필 정보를 불러옵니다.
친구 목록 가져오기 현재 로그인한 사용자의 카카오계정에 연결된 카카오톡의 친구 정보를 불러옵니다.