페이지 이동경로
  • 문서>
  • 카카오톡 소셜>
  • JavaScript

카카오톡 소셜

JavaScript

이 문서는 Kakao SDK for JavaScript(이하 JavaScript SDK)를 사용한 카카오톡 소셜 API 구현 방법을 안내합니다.

프로필 가져오기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- 플랫폼 등록
카카오 로그인 활성화
동의 항목		 필요 필요:
프로필 정보(닉네임/프로필 사진)
닉네임
프로필 사진		 request()

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡 프로필 정보를 받습니다. 사용자 카카오계정에 연결된 카카오톡이 없다면 에러 응답을 받습니다.

url 값을 /v1/api/talk/profile로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터
이름 타입 설명 필수
url String /v1/api/talk/profile로 고정 O
예제
Kakao.API.request({
  url: '/v1/api/talk/profile',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

피커: 친구 선택하기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의
필요:
사용 권한		 플랫폼 등록
카카오 로그인 활성화
동의 항목		 필요 필요:
카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)

사용자가 카카오톡 친구를 선택할 수 있는 피커를 호출합니다. 선택 유형에 따라 호출해야 할 함수가 다르므로, 서비스의 필요에 맞는 함수를 선택해 사용합니다.

선택 유형 함수
싱글 피커 selectFriend()
멀티 피커 selectFriends()

JavaScript SDK를 사용해 피커를 호출할 경우, 서비스 UI/UX에 맞춰 피커 화면으로 자연스럽게 이동할 수 있도록 두 가지 사용 방식을 제공합니다.

  • 팝업 방식
    • 피커가 팝업창으로 나타나는 형태
    • 선택한 친구 정보를 Promise로 전달
  • 리다이렉트(Redirect) 방식
    • 현재 창에서 피커로 이동하는 형태
    • 선택한 친구 정보를 URL 인코딩하여 서비스 서버의 returnUrl로 리다이렉트(HTTP 302 Redirect)하여 쿼리 스트링(Query string)으로 전달
    • [내 애플리케이션] > [플랫폼] > [Web]에 returnUrl의 사이트 도메인 등록 필수

피커의 구성 요소, 언어는 파라미터를 사용해 선택적으로 지정할 수 있습니다. 아래 표를 참고합니다.

파라미터
이름 타입 설명 필수
title String 친구 피커의 타이틀 영역에 표시될 텍스트
(기본값: "친구 선택")		 X
enableSearch Boolean 친구 검색 기능 사용 여부
(기본값: true)		 X
showMyProfile Boolean 내 프로필 표시 여부
true일 경우 자신의 프로필 선택 가능
(기본값: true)		 X
showFavorite Boolean 즐겨찾기 친구 표시 여부
(기본값: true)		 X
showPickedFriend Boolean 멀티 피커 전용
선택한 친구 표시 여부
(기본값: true)		 X
maxPickableCount Number 멀티 피커 전용
선택 가능한 친구 수의 최대 값
minPickableCount 보다 크거나 같은 수
(기본값: 30, 최대: 100)		 X
minPickableCount Number 멀티 피커 전용
선택 가능한 친구 수의 최소 값
maxPickableCount 보다 작거나 같은 수
(기본값: 1, 최대: 100)		 X
returnUrl String 리다이렉트 방식 사용 시 필수
선택한 친구 정보를 받을 서비스 URL

비고: [내 애플리케이션] > [플랫폼] > [Web]에 등록된 사이트 도메인만 허용		 X
enableBackButton Boolean 리다이렉트 방식 전용
뒤로가기 버튼 사용 여부 지정
true: 사용
false: 미사용
(기본값: true)		 X
예제
// 팝업 방식
Kakao.Picker.selectFriends({
  title: '친구 선택',
  maxPickableCount: 10,
  minPickableCount: 1,
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

// 리다이렉트 방식
// 성공: ${returnUrl}?selected=${SelectedUsers}
// 실패: ${returnUrl}?error=${Error}
Kakao.Picker.selectFriends({
  returnUrl: 'https://developers.kakao.com', // 필수
  title: '친구 선택',
  maxPickableCount: 10,
  minPickableCount: 1,
});

사용자가 피커 화면에서 친구 선택을 완료하면 SelectedUsers 객체가 반환됩니다. 해당 객체는 선택된 각 친구의 정보를 SelectedUser 객체의 배열로 포함합니다. 요청에 실패했거나 문제가 발생한 경우 문제 해결에서 원인을 확인합니다.

SelectedUsers
이름 타입 설명 필수
selectedTotalCount Number 친구 피커에서 사용자가 선택한 친구 수
선택한 친구 정보 목록의 친구 수와 다를 수 있음

참고: 피커를 통해 제공받은 친구 정보의 수가 선택한 친구 수보다 적은 경우		 O
users SelectedUser[] 선택한 친구 정보 목록 X
SelectedUser
이름 타입 설명 필수
uuid String 친구마다 고유한 값을 가지는 참고용 코드(Code)
카카오톡 메시지 전송 시 사용

참고: 카카오톡을 탈퇴하거나 새로 가입할 경우 값이 변경될 수 있음		 O
id String 친구의 회원번호 X
profile_nickname String 카카오톡 프로필 닉네임 X
profile_thumbnail_image String 카카오톡 프로필 썸네일 이미지 X
favorite Boolean 카카오톡 친구 즐겨찾기 설정 여부 X

친구 목록 가져오기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
필요:
사용 권한		 플랫폼 등록
카카오 로그인 활성화
동의 항목		 필요 필요:
카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)		 request()

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡의 친구 정보를 받아 옵니다.

정렬 순서, 한 페이지에 가져올 친구 수 등 파라미터를 선택적으로 사용하여 요청할 수 있습니다. 사용자 카카오계정에 연결된 카카오톡이 없다면 에러 응답을 받습니다.

응답 중 각 친구의 uuid 값은 메시지 보내기 API 요청 시 사용하는 수신자 정보로, 메시지 보내기 전 친구 목록을 먼저 받아와야 해당 값을 구할 수 있습니다.

카카오톡 친구 수가 요청 시 limit보다 많다면 결과가 페이지로 나뉩니다. 응답에 포함된 after_url을 사용해 친구 목록 받기를 요청하면 파라미터를 다시 지정하지 않고도 다음 페이지의 친구 목록을 받아올 수 있습니다.

url 값을 /v1/api/talk/friends로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터
이름 타입 설명 필수
url String /v1/api/talk/friends로 고정 O
data Object API에 전달할 파라미터 X
data: 친구 목록 가져오기
이름 타입 설명 필수
offset Number 친구 목록 시작 지점(기본값: 0) X
limit Number 한 페이지에 가져올 친구 최대 수(기본값: 10, 최대: 100) X
order String 친구 목록 정렬 순서, 오름차순("asc") 또는 내림차순("desc")(기본값 "asc") X
friend_order String 친구 목록 정렬 시, 즐겨찾기 친구의 우선 정렬 또는 닉네임 순서 정렬로 기준 설정
즐겨찾기 친구(favorite) 또는 카카오톡 닉네임(nickname)
(기본값: favorite)		 X
예제
Kakao.API.request({
  url: '/v1/api/talk/friends',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Legacy

카카오톡 소셜의 Legacy Kakao SDK for JavaScript(이하 Legacy JavaScript SDK) 개발 가이드는 다음 링크에서 확인할 수 있습니다. 추후 Legacy JavaScript SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 JavaScript SDK로 변경할 것을 권장합니다.

더 보기

카카오톡 소셜> JavaScript