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

카카오톡 소셜

JavaScript

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

프로필 가져오기

기본 정보

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

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

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

Parameter
Name Type Description Required
url String /v1/api/talk/profile로 고정 O

Sample

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의 사이트 도메인 등록 필수

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

Parameter
Name Type Description Required
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
Sample
// 팝업 방식
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
Name Type Description Required
selectedTotalCount Number 친구 피커에서 사용자가 선택한 친구 수
선택한 친구 정보 목록의 친구 수와 다를 수 있음

참고: 피커를 통해 제공받은 친구 정보의 수가 선택한 친구 수보다 적은 경우		 O
users SelectedUser[] 선택한 친구 정보 목록 X
SelectedUser
Name Type Description Required
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를 참고합니다.

Parameter
Name Type Description Required
url String /v1/api/talk/friends로 고정 O
data Object API에 전달할 파라미터 X
data: 친구 목록 가져오기
Name Type Description Required
offset Number 친구 목록 시작 지점(기본값: 0) X
limit Number 한 페이지에 가져올 친구 최대 수(기본값: 10, 최대: 100) X
order String 친구 목록 정렬 순서, 오름차순("asc") 또는 내림차순("desc")(기본값 "asc") X
friend_order String 친구 목록 정렬 시, 즐겨찾기 친구의 우선 정렬 또는 닉네임 순서 정렬로 기준 설정
즐겨찾기 친구(favorite) 또는 카카오톡 닉네임(nickname)
(기본값: favorite)		 X
Sample
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