본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

관련사이트

사이드 메뉴

플랫폼 API

API 제공

전용 API

어드민 API

이 문서는 카카오 또는 공동체 서비스가 JavaScript SDK(Kakao SDK for JavaScript)를 사용한 카카오톡 소셜 API 구현 방법을 안내합니다.

사용자 카카오계정에 연결된 카카오톡의 프로필 정보를 가져옵니다.

자세한 안내와 예제는 카카오톡 프로필 조회를 참고합니다.

레퍼런스앱 설정
selectFriend()
selectFriends()
설치
초기화
하이브리드 앱 가이드(팝업 방식으로 사용 시)

카카오톡 친구 목록을 불러와 친구 피커를 표시하고, 사용자가 선택한 친구의 정보를 제공합니다.

사용자가 선택하도록 할 친구의 수에 따라 필요한 친구 피커를 호출합니다.

  • 한 명: 싱글 피커, selectFriend()
  • 여러 명: 멀티 피커, selectFriends()

피커 화면 구성 요소를 설정하는 파라미터를 제공합니다.

Inhouse
: 공동체 앱은 권한 필요
이름타입설명필수
titleString피커 이름
(기본값: "친구 선택")
X
friendFilter
Inhouse
String친구 목록 필터링 설정, 아래 중 하나
  • none: 필터링하지 않음, 전체 친구 조회
  • registered: 앱에 연결된 친구만 조회
  • invitable: 앱과 연결되지 않아 초대 가능한 친구만 조회
(기본값: none)
X
countryCodeFilters
Inhouse
String[]국가 코드 필터링 설정X
usingOsFilter
Inhouse
String친구의 카카오톡 가입 기기 OS 필터링 설정, 아래 중 하나
  • ios: iOS 사용자만 조회
  • android: Android 사용자만 조회
  • all: Android와 iOS 사용자 모두 조회
(기본값: "all")
X
enableSearchBoolean검색 기능 사용 여부
(기본값: true)
X
showMyProfileBoolean내 프로필 표시 여부
true일 경우 사용자 본인 프로필 선택 가능
(기본값: true)
X
showFavoriteBoolean즐겨찾기 친구 표시 여부
(기본값: true)
X
showPickedFriendBoolean멀티 피커 전용
선택한 친구 표시 여부
(기본값: true)
X
disableSelectOptionsDisableSelectOption[]선택 불가 설정
(기본값: null)
X
displayAllProfile
Inhouse
Boolean미동의 사용자 프로필 표시 설정
  • true: 미동의한 친구의 uuid, 프로필 이미지와 원본 닉네임 제공
  • false: 미동의한 친구의 uuid와 마스킹된 닉네임만 제공
(기본값: false)

참고: 동의한 친구는 displayAllProfile 값과 상관 없이 닉네임, 프로필 이미지, uuid, id, favorite 제공
X
maxPickableCountNumber멀티 피커 전용
선택 가능한 최대 대상 수
(기본값: 30, 최대: 100)
X
minPickableCountNumber멀티 피커 전용
선택 가능한 최소 대상 수
(기본값: 1, 최대: 100)
X
returnUrlString리다이렉트 방식 사용 시 필수
응답을 전달받을 서비스 URL

중요: 앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용
X
enableBackButtonBoolean리다이렉트 방식 전용
뒤로가기 버튼 사용 여부
  • true: 사용
  • false: 미사용
(기본값: true)
X

피커는 팝업 방식으로 열립니다. 팝업이 아닌 현재 창에서 피커로 이동하려면 리다이렉트 방식을 사용합니다.

응답은 Promise로 전달됩니다. 응답 정보는 SelectedUsers를 참고합니다. 친구가 정보 제공에 동의하지 않았거나, 앱이 [미동의 사용자 프로필] 권한이 없는 경우 profile_nickname마스킹 처리된 닉네임이 반환됩니다. 응답 제공에 필요한 동의항목피커: 추가 권한 신청을 참고합니다.

Kakao.Picker.selectFriend({
friendFilter: "registered",
title: "친구 선택",
})
.then(function (response) {
console.log(response)
})
.catch(function (error) {
console.log(error)
})

리다이렉트 방식으로 피커를 호출합니다. 리다이렉트 방식 사용 시, 현재 창에서 피커로 이동합니다.

returnUrl 파라미터로 응답을 전달받을 서비스 서버의 URL을 지정해야 합니다. returnUrl앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용됩니다. enableBackButton 파라미터로 뒤로가기 버튼 사용 여부를 설정할 수 있습니다.

사용자가 선택을 완료하면, 서비스 서버의 returnUrl로 리다이렉트(HTTP 302 Redirect) 되면서 응답이 URL 인코딩된 쿼리 문자열로 전달됩니다.

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

파라미터를 사용해 특정 조건을 만족하는 사용자만 친구 피커에 표시할 수 있습니다.

아래는 앱과 연결되어 있고, Android 기기를 사용하는 한국 사용자만 친구 목록에 표시하도록 하는 예제입니다.

Kakao.Picker.selectFriends({
title: "친구 선택",
friendFilter: "registered", // 친구 목록 필터링 설정
usingOsFilter: "android", // 친구의 카카오톡 가입 기기 OS 필터링 설정
countryCodeFilters: ["kr"], // 국가 코드 필터링 설정
maxPickableCount: 5,
minPickableCount: 1,
})
.then(function (response) {
console.log(response)
})
.catch(function (error) {
console.log(error)
})

친구 초대 기능 구현을 위해 미동의 친구 목록을 표시하려면 friendFilterdisplayAllProfile 파라미터를 사용합니다.

미동의 친구 목록, 미동의 사용자의 전체 프로필을 제공받으려면 권한을 받아야 합니다. 미동의 사용자 프로필을 마스킹 처리 없이 피커에 표시하려면 displayAllProfile 파라미터 값을 true로 지정합니다.

Kakao.Picker.selectFriends({
title: "친구 초대",
friendFilter: "invitable", // 친구 목록 필터링 설정
displayAllProfile: true, // 미동의 사용자 프로필 표시 설정
maxPickableCount: 5,
minPickableCount: 1,
})
.then(function (response) {
console.log(response)
})
.catch(function (error) {
console.log(error)
})

피커에서 특정 조건에 해당하는 친구를 사용자가 선택할 수 없도록 제한하려면 disableSelectOptions 파라미터를 사용합니다. 자세한 정보는 선택 가능한 대상 제한을 참고합니다.

아래는 사용자가 이미 초대한 친구를 선택할 수 없도록 설정하는 예제입니다.

Kakao.Picker.selectFriends({
title: "친구 선택",
friendFilter: "invitable",
maxPickableCount: 10,
minPickableCount: 1,
disableSelectOptions: [
{
reason: "custom", // 서비스 상황에 맞게 표시할 사용자 선택 불가 원인
message: "초대 완료", // 사용자 닉네임 아래에 표시할 선택 불가 원인
uuids: ["${USER_UUID_1}", "${USER_UUID_2}"], // 사용자 선택 불가 원인를 적용할 사용자의 고유 ID
},
],
})
.then(function (response) {
console.log(response)
})
.catch(function (error) {
console.log(error)
})
레퍼런스앱 설정
-설치
초기화
하이브리드 앱 가이드(팝업 방식으로 사용 시)

카카오톡 채팅방 목록을 불러와 풀 스크린 형태의 채팅방 피커를 표시하고, 사용자가 선택한 채팅방의 정보를 제공합니다.

Kakao.Picker.selectChat()을 호출합니다. 필수 파라미터인 selectionType의 값은 CHAT으로 지정합니다. 피커의 화면 모드와 방향, 밝기, 필터 등을 설정하는 파라미터를 제공합니다.

Inhouse
: 공동체 앱은 권한 필요
이름타입설명필수
selectionTypeString채팅방 피커 종류
chat: 채팅방
chatMember: 채팅방 멤버
O
titleString피커 이름
(기본값: "채팅방 선택")

중요: 채팅방 멤버 목록의 타이틀은 "친구 선택"으로 고정
X
chatFiltersString[]채팅방 목록 필터링 설정

아래 중 다중 선택 가능:
regular: 일반 채팅
open: 오픈 채팅
direct: 일반채팅과 오픈채팅의 1:1채팅방
multi: 일반채팅과 오픈채팅의 그룹채팅방
(기본값: ["regular"])

중요: directmulti는 단독으로 지정할 수 없음
X
enableSearchBoolean검색 기능 사용 여부
(기본값: true)
X
returnUrlString리다이렉트 방식 사용 시 필수
응답을 전달받을 서비스 URL

중요: 앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용
X
enableBackButtonBoolean리다이렉트 방식 전용
뒤로가기 버튼 사용 여부
  • true: 사용
  • false: 미사용
(기본값: true)
X

피커는 팝업 방식으로 열립니다. 팝업이 아닌 현재 창에서 피커로 이동하려면 리다이렉트 방식을 사용합니다.

응답은 Promise로 전달됩니다. 응답 정보는 SelectedChat을 참고합니다.

Kakao.Picker.selectChat({
selectionType: "chat",
chatFilters: ["regular"],
title: "채팅방 선택",
})
.then(function (response) {
console.log(response)
})
.catch(function (error) {
console.log(error)
})

리다이렉트 방식으로 피커를 호출합니다. 리다이렉트 방식 사용 시, 현재 창에서 피커로 이동합니다.

returnUrl 파라미터로 응답을 전달받을 서비스 서버의 URL을 지정해야 합니다. returnUrl앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용됩니다. enableBackButton 파라미터로 뒤로가기 버튼 사용 여부를 설정할 수 있습니다.

사용자가 선택을 완료하면, 서비스 서버의 returnUrl로 리다이렉트(HTTP 302 Redirect) 되면서 응답이 URL 인코딩된 쿼리 문자열로 전달됩니다.

// 리다이렉트 방식
// 성공: ${returnUrl}?selected=${SelectedChat}
// 실패: ${returnUrl}?error=${Error}
Kakao.Picker.selectChat({
returnUrl: "https://developers.kakao.com", // 필수
selectionType: "chat",
chatFilters: ["regular"],
title: "채팅방 선택",
})

chatFilters 파라미터로 특정 타입의 채팅방만 채팅방 피커에 표시할 수 있습니다.

아래는 오픈 채팅 중 그룹 채팅방만 표시하도록 하는 예제입니다.

Kakao.Picker.selectChat({
selectionType: "chat",
chatFilters: ["open", "multi"], // 채팅방 목록 필터링 설정
title: "채팅방 선택",
})
.then(function (response) {
console.log(response)
})
.catch(function (error) {
console.log(error)
})

사용자가 채팅방을 선택 후 해당 채팅방 안의 특정 멤버를 선택하도록 하려면, 아래와 같이 파라미터를 지정해 요청합니다.

  • selectionType: chatMember
  • chatSelectParams: SelectionMode.SINGLE
  • chatMemberSelectParams: 내부 파라미터(mode, maxPickableCount, minPickableCount)를 필요 기능에 해당하는 값으로 포함 필요
  • chatFilters: 값에 open 포함 불가

미동의 친구 목록, 미동의 사용자의 전체 프로필을 제공받으려면 권한을 받아야 합니다. 미동의 사용자 프로필을 마스킹 처리 없이 피커에 표시하려면 displayAllProfile 파라미터 값을 true로 지정합니다. 아래는 채팅방 멤버 선택 시 추가로 사용할 수 있는 파라미터 정보입니다.

이름타입설명필수
disableSelectOptionsDisableSelectOption[]채팅방 멤버 선택 시에만 사용
선택 불가 설정
(기본값: null)
X
displayAllProfile
Inhouse
Boolean채팅방 멤버 선택 시에만 사용
미동의 사용자 프로필 표시 설정
  • true: 미동의한 친구의 uuid, 프로필 이미지와 원본 닉네임 제공
  • false: 미동의한 친구의 uuid와 마스킹된 닉네임만 제공
(기본값: false)

참고: 동의한 친구는 displayAllProfile 값과 상관 없이 닉네임, 프로필 이미지, uuid, id, favorite 제공
X
maxPickableCountNumber채팅방 멤버 선택 시에만 사용
선택 가능한 최대 대상 수
(기본값: 30, 최대: 100)
X
minPickableCountNumber채팅방 멤버 선택 시에만 사용
선택 가능한 최소 대상 수
(기본값: 1, 최대: 100)
X

응답 정보는 SelectedUsers를 참고합니다.

Kakao.Picker.selectChat({
selectionType: 'chatMember', // 필수
chatFilters: ['regular'],
displayAllProfile: true
title: '채팅방 멤버 선택',
maxPickableCount: 5,
minPickableCount: 1,
})
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
레퍼런스앱 설정
-설치
초기화
하이브리드 앱 가이드(팝업 방식으로 사용 시)

카카오톡 친구 목록과 채팅방 목록을 불러와 탭 피커를 표시하고, 사용자가 선택한 친구나 채팅방의 정보를 제공합니다.

Kakao.Picker.select()를 호출합니다. 필수 파라미터인 selectionType의 값은 chat으로 지정합니다. 채팅방 선택 후 멤버 선택으로 설정하려면 selectionType의 값을 chatMember로 지정합니다.

Inhouse
: 공동체 앱은 권한 필요
이름타입설명필수
titleString피커 이름
(기본값: "친구 선택")

중요: 채팅방 멤버 목록의 타이틀은 "친구 선택"으로 고정
X
enableSearchBoolean검색 기능 사용 여부
(기본값: true)
X
initialPickerTabString최초 노출 탭, 아래 중 하나
  • friend: 친구 탭
  • chat: 채팅방 탭
X
disableSelectOptionsDisableSelectOption[]선택 불가 설정
(기본값: null)
X
displayAllProfile
Inhouse
Boolean앱과 연결되지 않았거나 동의항목에 미동의한 친구의 프로필 전체 정보 표시 여부

  • true: 미동의한 친구의 uuid, 프로필 이미지와 원본 닉네임 제공
  • false: 미동의한 친구의 uuid와 마스킹된 닉네임만 제공
(기본값: false)

참고: 동의한 친구는 displayAllProfile 값과 상관 없이 닉네임, 프로필 이미지, uuid, id, favorite 제공
X
maxPickableCountNumber선택 가능한 최대 대상 수
(기본값: 30, 최대: 100)
X
minPickableCountNumber선택 가능한 최소 대상 수
(기본값: 1, 최대: 100)
X
friendsParamsFriendsParams친구 피커 설정X
chatParamsChatParams채팅방 피커 설정O
returnUrlString리다이렉트 방식 사용 시 필수
응답을 전달받을 서비스 URL

중요: 앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용
X
enableBackButtonBoolean리다이렉트 방식 전용
뒤로가기 버튼 사용 여부
  • true: 사용
  • false: 미사용
(기본값: true)
X
enableMultiBoolean여러 대상 선택 사용 여부
  • true: 사용
  • false: 미사용
O

피커는 팝업 방식으로 열립니다. 팝업이 아닌 현재 창에서 피커로 이동하려면 리다이렉트 방식을 사용합니다.

응답은 Promise로 전달됩니다. 응답 정보는 SelectedChat, SelectedUsers를 참고합니다.

Kakao.Picker.select({
title: "친구 선택",
maxPickableCount: 5,
minPickableCount: 1,
friendsParams: {
friendFilter: "registered",
},
chatParams: {
selectionType: "chat",
chatFilters: ["regular"],
},
})
.then(function (response) {
console.log(response)
})
.catch(function (error) {
console.log(error)
})

리다이렉트 방식으로 피커를 호출합니다. 리다이렉트 방식 사용 시, 현재 창에서 피커로 이동합니다.

returnUrl 파라미터로 응답을 전달받을 서비스 서버의 URL을 지정해야 합니다. returnUrl앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용됩니다. enableBackButton 파라미터로 뒤로가기 버튼 사용 여부를 설정할 수 있습니다.

사용자가 선택을 완료하면, 서비스 서버의 returnUrl로 리다이렉트(HTTP 302 Redirect) 되면서 응답이 URL 인코딩된 쿼리 문자열로 전달됩니다.

// 리다이렉트 방식
// 성공: ${returnUrl}?selected=${SelectedUsers | SelectedChat}
// 실패: ${returnUrl}?error=${Error}
Kakao.Picker.select({
returnUrl: "https://developers.kakao.com", // 필수
title: "친구 선택",
maxPickableCount: 5,
minPickableCount: 1,
friendsParams: {
friendFilter: "registered",
},
chatParams: {
selectionType: "chat",
chatFilters: ["regular"],
},
})

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡의 친구 정보를 가져옵니다. 공동체 앱은 유료 API이 필요한 기능입니다.

자세한 안내와 예제는 카카오톡 친구 목록 조회를 참고합니다.

Inhouse
: 공동체 앱은 권한 필요
이름타입설명필수
selectionTypeString채팅방 피커 종류
chat: 채팅방
chatMember: 채팅방 멤버
O
chatFiltersString[]채팅방 목록 필터링 설정

아래 중 다중 선택 가능:
regular: 일반 채팅
open: 오픈 채팅
direct: 1:1 채팅방
multi: 그룹 채팅방
(기본값: ["regular"])

중요: selectionTypechatMember일 경우, directmulti를 단독으로 지정하거나 open 지정 시 에러 발생
X
이름타입설명필수
reasonString사용자 닉네임 아래에 표시할 선택 불가 원인

아래 중 다중 선택 가능:
registered: 앱과 연결된 사용자에게 "가입" 표시
unregistered: 앱과 연결되지 않은 사용자에게 "미가입" 표시
notFriend: 친구가 아닌 사용자에게 "카카오톡 친구 아님" 표시
custom: message로 서비스에서 직접 설정한 불가 사유 표시

중요: custom 선택 시, 함께 선택한 불가 사유는 무시되고 지정한 사용자에게 별도의 불가 사유 표시
O
messageString서비스 상황에 맞게 표시할 사용자 선택 불가 원인

중요: reasoncustom일 경우만 필수
X
uuidsString[]사용자 선택 불가 원인를 적용할 사용자의 고유 아이디(uuid) 목록

중요: reasoncustom일 경우만 필수
X
Inhouse
: 공동체 앱은 권한 필요
이름타입설명필수
friendFilter
Inhouse
String친구 목록 필터링 설정, 아래 중 하나
  • none: 필터링하지 않음, 전체 친구 조회
  • registered: 앱에 연결된 친구만 조회
  • invitable: 앱과 연결되지 않아 초대 가능한 친구만 조회
(기본값: none)
X
countryCodeFilters
Inhouse
String[]국가 코드 필터링 설정X
usingOsFilter
Inhouse
String친구의 카카오톡 가입 기기 OS 필터링 설정, 아래 중 하나
  • ios: iOS 사용자만 조회
  • android: Android 사용자만 조회
  • all: Android와 iOS 사용자 모두 조회
(기본값: "all")
X
showMyProfileBoolean내 프로필 표시 여부
true일 경우 사용자 본인 프로필 선택 가능
(기본값: true)
X
showFavoriteBoolean즐겨찾기 친구 표시 여부
(기본값: true)
X
showPickedFriendBoolean선택한 친구 표시 여부
(기본값: true)
X
이름타입설명필수
idString채팅방 IDO
member_countNumber채팅방 멤버 수O
title_sourceString채팅방 이름 타입, 아래 중 하나
  • user: 사용자가 설정한 이름
  • chat: 채팅방 생성 시 설정된 이름
  • default: 별도 설정 없음
O
typeString채팅방 타입, 아래 중 하나
  • MemoChat: 나와의 채팅방
  • DirectChat: 다른 사용자와의 1:1 채팅방
  • MultiChat: 다른 사용자들과의 그룹 채팅방
  • OpenDirectChat: 1:1 오픈채팅방
  • OpenMultiChat: 그룹 오픈채팅방
O
image_urlString채팅방 이미지 URLX
이름타입설명필수
selectedTotalCountNumber선택한 사용자 수O
usersSelectedUser[]선택한 사용자 정보 목록, 정보 제공이 불가능한 사용자 제외X
이름타입설명필수
uuidString사용자 고유 IDO
profile_nicknameString카카오톡 프로필 닉네임

중요: 사용자가 동의하지 않은 경우 마스킹된 닉네임 제공, 동의 여부에 따른 친구 정보 제공 범위 참고
O
profile_thumbnail_imageString프로필 썸네일 이미지X
idString회원번호, 앱과 연결된 사용자에게만 존재X
favoriteBoolean즐겨찾기 친구 여부X

도움이 되었나요?