사이드 메뉴
커뮤니케이션
API 제공
어드민 API
JavaScript
이 문서는 카카오 또는 공동체 서비스가 JavaScript SDK(Kakao SDK for JavaScript)를 사용한 카카오톡 소셜 API 구현 방법을 안내합니다.
사용자 카카오계정에 연결된 카카오톡의 프로필 정보를 가져옵니다.
자세한 안내와 예제는 카카오톡 프로필 조회를 참고합니다.
| 레퍼런스 | 앱 설정 |
|---|---|
selectFriend()selectFriends() | 설치 초기화 하이브리드 앱 가이드(팝업 방식으로 사용 시) |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요: 공동체 앱 | JavaScript 키 JavaScript SDK 도메인 카카오 로그인 활성화 동의항목 유료 API: 공동체 앱 | 필요: 연결 | - |
카카오톡 친구 목록을 불러와 친구 피커를 표시하고, 사용자가 선택한 친구의 정보를 제공합니다.
사용자가 선택하도록 할 친구의 수에 따라 필요한 친구 피커를 호출합니다.
- 한 명: 싱글 피커,
selectFriend() - 여러 명: 멀티 피커,
selectFriends()
피커 화면 구성 요소를 설정하는 파라미터를 제공합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| title | String | 피커 이름 (기본값: "친구 선택") | X |
| friendFilter Inhouse | String | 친구 목록 필터링 설정, 아래 중 하나
none) | X |
| countryCodeFilters Inhouse | String[] | 국가 코드 필터링 설정 | X |
| usingOsFilter Inhouse | String | 친구의 카카오톡 가입 기기 OS 필터링 설정, 아래 중 하나
"all") | X |
| enableSearch | Boolean | 검색 기능 사용 여부 (기본값: true) | X |
| showMyProfile | Boolean | 내 프로필 표시 여부true일 경우 사용자 본인 프로필 선택 가능(기본값: true) | X |
| showFavorite | Boolean | 즐겨찾기 친구 표시 여부 (기본값: true) | X |
| showPickedFriend | Boolean | 멀티 피커 전용 선택한 친구 표시 여부 (기본값: true) | X |
| disableSelectOptions | DisableSelectOption[] | 선택 불가 설정 (기본값: null) | X |
| displayAllProfile Inhouse | Boolean | 미동의 사용자 프로필 표시 설정
false)참고: 동의한 친구는 displayAllProfile 값과 상관 없이 닉네임, 프로필 이미지, uuid, id, favorite 제공 | X |
| maxPickableCount | Number | 멀티 피커 전용 선택 가능한 최대 대상 수 (기본값: 30, 최대: 100) | X |
| minPickableCount | Number | 멀티 피커 전용 선택 가능한 최소 대상 수 (기본값: 1, 최대: 100) | X |
| returnUrl | String | 리다이렉트 방식 사용 시 필수 응답을 전달받을 서비스 URL 중요: 앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용 | X |
| enableBackButton | Boolean | 리다이렉트 방식 전용 뒤로가기 버튼 사용 여부
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)})
친구 초대 기능 구현을 위해 미동의 친구 목록을 표시하려면 friendFilter와 displayAllProfile 파라미터를 사용합니다.
미동의 친구 목록, 미동의 사용자의 전체 프로필을 제공받으려면 권한을 받아야 합니다. 미동의 사용자 프로필을 마스킹 처리 없이 피커에 표시하려면 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)})
| 레퍼런스 | 앱 설정 |
|---|---|
| - | 설치 초기화 하이브리드 앱 가이드(팝업 방식으로 사용 시) |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요: 공동체 앱 | JavaScript 키 JavaScript SDK 도메인 카카오 로그인 활성화 동의항목 유료 API: 공동체 앱 | 필요: 연결 | 필요: 이용 정책 참고 |
카카오톡 채팅방 목록을 불러와 풀 스크린 형태의 채팅방 피커를 표시하고, 사용자가 선택한 채팅방의 정보를 제공합니다.
Kakao.Picker.selectChat()을 호출합니다. 필수 파라미터인 selectionType의 값은 CHAT으로 지정합니다. 피커의 화면 모드와 방향, 밝기, 필터 등을 설정하는 파라미터를 제공합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| selectionType | String | 채팅방 피커 종류chat: 채팅방chatMember: 채팅방 멤버 | O |
| title | String | 피커 이름 (기본값: "채팅방 선택") 중요: 채팅방 멤버 목록의 타이틀은 "친구 선택"으로 고정 | X |
| chatFilters | String[] | 채팅방 목록 필터링 설정 아래 중 다중 선택 가능: regular: 일반 채팅open: 오픈 채팅direct: 일반채팅과 오픈채팅의 1:1채팅방multi: 일반채팅과 오픈채팅의 그룹채팅방(기본값: ["regular"])중요: direct나 multi는 단독으로 지정할 수 없음 | X |
| enableSearch | Boolean | 검색 기능 사용 여부 (기본값: true) | X |
| returnUrl | String | 리다이렉트 방식 사용 시 필수 응답을 전달받을 서비스 URL 중요: 앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용 | X |
| enableBackButton | Boolean | 리다이렉트 방식 전용 뒤로가기 버튼 사용 여부
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:chatMemberchatSelectParams:SelectionMode.SINGLEchatMemberSelectParams: 내부 파라미터(mode,maxPickableCount,minPickableCount)를 필요 기능에 해당하는 값으로 포함 필요chatFilters: 값에open포함 불가
미동의 친구 목록, 미동의 사용자의 전체 프로필을 제공받으려면 권한을 받아야 합니다. 미동의 사용자 프로필을 마스킹 처리 없이 피커에 표시하려면 displayAllProfile 파라미터 값을 true로 지정합니다. 아래는 채팅방 멤버 선택 시 추가로 사용할 수 있는 파라미터 정보입니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| disableSelectOptions | DisableSelectOption[] | 채팅방 멤버 선택 시에만 사용 선택 불가 설정 (기본값: null) | X |
| displayAllProfile Inhouse | Boolean | 채팅방 멤버 선택 시에만 사용 미동의 사용자 프로필 표시 설정
false)참고: 동의한 친구는 displayAllProfile 값과 상관 없이 닉네임, 프로필 이미지, uuid, id, favorite 제공 | X |
| maxPickableCount | Number | 채팅방 멤버 선택 시에만 사용 선택 가능한 최대 대상 수 (기본값: 30, 최대: 100) | X |
| minPickableCount | Number | 채팅방 멤버 선택 시에만 사용 선택 가능한 최소 대상 수 (기본값: 1, 최대: 100) | X |
응답 정보는 SelectedUsers를 참고합니다.
Kakao.Picker.selectChat({selectionType: 'chatMember', // 필수chatFilters: ['regular'],displayAllProfile: truetitle: '채팅방 멤버 선택',maxPickableCount: 5,minPickableCount: 1,}).then(function(response) {console.log(response);}).catch(function(error) {console.log(error);});
| 레퍼런스 | 앱 설정 |
|---|---|
| - | 설치 초기화 하이브리드 앱 가이드(팝업 방식으로 사용 시) |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요: 공동체 앱 | JavaScript 키 JavaScript SDK 도메인 카카오 로그인 활성화 동의항목 유료 API: 공동체 앱 | 필요: 연결 | 필요: 이용 정책 참고 |
카카오톡 친구 목록과 채팅방 목록을 불러와 탭 피커를 표시하고, 사용자가 선택한 친구나 채팅방의 정보를 제공합니다.
Kakao.Picker.select()를 호출합니다. 필수 파라미터인 selectionType의 값은 chat으로 지정합니다. 채팅방 선택 후 멤버 선택으로 설정하려면 selectionType의 값을 chatMember로 지정합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| title | String | 피커 이름 (기본값: "친구 선택") 중요: 채팅방 멤버 목록의 타이틀은 "친구 선택"으로 고정 | X |
| enableSearch | Boolean | 검색 기능 사용 여부 (기본값: true) | X |
| initialPickerTab | String | 최초 노출 탭, 아래 중 하나
| X |
| disableSelectOptions | DisableSelectOption[] | 선택 불가 설정 (기본값: null) | X |
| displayAllProfile Inhouse | Boolean | 앱과 연결되지 않았거나 동의항목에 미동의한 친구의 프로필 전체 정보 표시 여부
false)참고: 동의한 친구는 displayAllProfile 값과 상관 없이 닉네임, 프로필 이미지, uuid, id, favorite 제공 | X |
| maxPickableCount | Number | 선택 가능한 최대 대상 수 (기본값: 30, 최대: 100) | X |
| minPickableCount | Number | 선택 가능한 최소 대상 수 (기본값: 1, 최대: 100) | X |
| friendsParams | FriendsParams | 친구 피커 설정 | X |
| chatParams | ChatParams | 채팅방 피커 설정 | O |
| returnUrl | String | 리다이렉트 방식 사용 시 필수 응답을 전달받을 서비스 URL 중요: 앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록된 도메인만 허용 | X |
| enableBackButton | Boolean | 리다이렉트 방식 전용 뒤로가기 버튼 사용 여부
true) | X |
| enableMulti | Boolean | 여러 대상 선택 사용 여부
| 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이 필요한 기능입니다.
자세한 안내와 예제는 카카오톡 친구 목록 조회를 참고합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| selectionType | String | 채팅방 피커 종류chat: 채팅방chatMember: 채팅방 멤버 | O |
| chatFilters | String[] | 채팅방 목록 필터링 설정 아래 중 다중 선택 가능: regular: 일반 채팅open: 오픈 채팅direct: 1:1 채팅방multi: 그룹 채팅방(기본값: ["regular"])중요: selectionType이 chatMember일 경우, direct나 multi를 단독으로 지정하거나 open 지정 시 에러 발생 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| reason | String | 사용자 닉네임 아래에 표시할 선택 불가 원인 아래 중 다중 선택 가능: registered: 앱과 연결된 사용자에게 "가입" 표시unregistered: 앱과 연결되지 않은 사용자에게 "미가입" 표시notFriend: 친구가 아닌 사용자에게 "카카오톡 친구 아님" 표시custom: message로 서비스에서 직접 설정한 불가 사유 표시중요: custom 선택 시, 함께 선택한 불가 사유는 무시되고 지정한 사용자에게 별도의 불가 사유 표시 | O |
| message | String | 서비스 상황에 맞게 표시할 사용자 선택 불가 원인 중요: reason이 custom일 경우만 필수 | X |
| uuids | String[] | 사용자 선택 불가 원인를 적용할 사용자의 고유 아이디(uuid) 목록중요: reason이 custom일 경우만 필수 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| friendFilter Inhouse | String | 친구 목록 필터링 설정, 아래 중 하나
none) | X |
| countryCodeFilters Inhouse | String[] | 국가 코드 필터링 설정 | X |
| usingOsFilter Inhouse | String | 친구의 카카오톡 가입 기기 OS 필터링 설정, 아래 중 하나
"all") | X |
| showMyProfile | Boolean | 내 프로필 표시 여부true일 경우 사용자 본인 프로필 선택 가능(기본값: true) | X |
| showFavorite | Boolean | 즐겨찾기 친구 표시 여부 (기본값: true) | X |
| showPickedFriend | Boolean | 선택한 친구 표시 여부 (기본값: true) | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | String | 채팅방 ID | O |
| member_count | Number | 채팅방 멤버 수 | O |
| title_source | String | 채팅방 이름 타입, 아래 중 하나
| O |
| type | String | 채팅방 타입, 아래 중 하나
| O |
| image_url | String | 채팅방 이미지 URL | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| selectedTotalCount | Number | 선택한 사용자 수 | O |
| users | SelectedUser[] | 선택한 사용자 정보 목록, 정보 제공이 불가능한 사용자 제외 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| uuid | String | 사용자 고유 ID | O |
| profile_nickname | String | 카카오톡 프로필 닉네임 중요: 사용자가 동의하지 않은 경우 마스킹된 닉네임 제공, 동의 여부에 따른 친구 정보 제공 범위 참고 | O |
| profile_thumbnail_image | String | 프로필 썸네일 이미지 | X |
| id | String | 회원번호, 앱과 연결된 사용자에게만 존재 | X |
| favorite | Boolean | 즐겨찾기 친구 여부 | X |