친구 목록 조회 API

이 문서는 게임플레이 파트너사의 연동에 필요한 카카오디벨로퍼스 공식 가이드 내용을 요약한 안내입니다.
실제 구현 전 반드시 카카오톡 친구 목록 조회 REST API 공식 가이드에서 최신 요청·응답 규격과 제약사항을 확인하세요.

파트너사 앱에 연결되고 친구 목록 제공에 동의한 사용자 사이의 친구 정보를 조회합니다.
친구 랭킹처럼 파트너사가 친구 데이터를 직접 구성하는 기능은 친구 목록 API를 사용하고, 사용자가 특정 친구를 고르는 기능은 친구 피커를 사용할 수 있습니다.

관련 가이드: 카카오싱크 설정의 친구 목록 조회에서 동의항목 설정과 친구 정보 제공 조건을 먼저 확인하세요.

제공 방식 선택

방식	적합한 기능	제공 형태
친구 목록 API	게임 결과와 연계한 친구 랭킹 등 파트너사가 목록 UI와 데이터를 직접 구성하는 기능	API 응답으로 친구 목록 제공
친구 피커	메시지 전송 등 사용자가 특정 친구를 직접 선택하는 기능	카카오가 제공하는 피커 화면에서 선택한 친구 정보 제공

두 방식 모두 파트너사 앱에 연결되고 friends 동의항목에 동의한 친구만 제공합니다.
친구 피커는 사용자의 전체 카카오톡 친구를 보여주는 화면이 아니며, 파트너사 게임을 이용 중인 친구 중 친구 정보 제공 조건을 만족하는 사용자만 선택할 수 있습니다.

사전 조건

1. 카카오디벨로퍼스의 [앱] > [추가 기능 신청] 에서 카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함) 사용 권한을 신청합니다. 신청 방법은 개인정보 동의항목 추가 기능 신청을 참고하세요.
2. 사용 권한을 받은 뒤 [카카오 로그인] > [동의항목] 에서 동의 단계를 선택 동의로 설정합니다. 동의 단계의 의미는 카카오 로그인 동의항목 설정을 참고하세요.
3. 친구 기능을 요청한 사용자가 friends 동의항목에 동의했는지 확인합니다.
4. 동의하지 않은 사용자는 게임 중 추가 동의 흐름으로 scope=friends 동의를 요청합니다.

API 응답에는 아래 조건을 모두 만족하는 친구만 포함됩니다.

• 파트너사 앱에 연결된 사용자
• friends 동의항목에 동의한 사용자
• 조회 사용자의 숨김 또는 차단 친구가 아닌 사용자
• 프로필 공개 설정이 공개 상태인 사용자

조회 사용자도 friends 동의가 필요하므로, 결과적으로 파트너사 앱 가입자 사이에 쌍방 동의가 완료된 경우에만 친구 정보가 제공됩니다.

Endpoint

GET https://kapi.kakao.com/v1/api/talk/friends

항목	값
인증	사용자 액세스 토큰
Authorization	Bearer ${ACCESS_TOKEN}

Request

주요 조회 옵션만 사용하고, 전체 파라미터와 정렬 정책은 카카오톡 친구 목록 조회 REST API를 참고하세요.

이름	타입	설명
offset	Integer	기본값 0친구 목록 시작 위치
limit	Integer	기본값 10페이지당 친구 수. 최대 100
order	String	기본값 asc정렬 방향. asc 또는 desc
friend_order	String	기본값 favorite정렬 기준. favorite 또는 nickname

curl -G "https://kapi.kakao.com/v1/api/talk/friends" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "offset=0" \
  -d "limit=20" \
  -d "friend_order=nickname"

Response

응답의 elements에 제공 조건을 만족하는 친구 정보가 포함됩니다.
페이지 이동에는 before_url과 after_url을 사용합니다.

필드	타입	설명
elements	Friend[]	친구 정보 배열
total_count	Integer	제공 가능한 전체 친구 수
before_url	String	이전 페이지 URL
after_url	String	다음 페이지 URL
favorite_count	Integer	즐겨찾기 친구 수

Friend의 주요 필드는 회원번호 id, 메시지 전송용 사용자 고유 ID uuid, 즐겨찾기 여부 favorite, 닉네임 profile_nickname, 프로필 썸네일 profile_thumbnail_image입니다.

{
  "elements": [
    {
      "id": 123456789,
      "uuid": "sample-friend-uuid",
      "favorite": false,
      "profile_nickname": "게임친구",
      "profile_thumbnail_image": "https://example.com/profile.jpg"
    }
  ],
  "total_count": 1,
  "favorite_count": 0
}

에러

상황	처리
액세스 토큰이 없거나 만료됨	유효한 사용자 액세스 토큰을 다시 발급한 뒤 요청합니다.
사용자가 friends 항목에 동의하지 않음	친구 기능 진입 시 추가 동의를 요청합니다.
예상한 친구가 응답에 없음	앱 연결, 쌍방 동의, 숨김·차단 여부, 프로필 공개 설정을 확인합니다.

제약 조건

• 사용자의 전체 카카오톡 친구를 제공하는 API가 아닙니다.
• 친구 목록 API와 친구 피커 모두 친구 정보 제공 조건을 만족하는 사용자만 제공합니다.
• 친구 목록 응답은 10분 동안 캐시되므로 변경 사항이 즉시 반영되지 않을 수 있습니다.
• 사용자가 선택 동의를 거부하거나 취소해도 친구 기능 외의 게임 이용은 계속할 수 있도록 예외 처리합니다.

세부 요청·응답 필드와 오류 코드는 카카오톡 친구 목록 조회 REST API를 참고하세요.

참고 문서

• 카카오싱크 설정
• 카카오싱크 API
• 카카오톡 친구 피커
• 카카오톡 친구 정보 제공 조건
• 카카오톡 친구 목록 조회 REST API
• 기술 문의: 카카오디벨로퍼스 데브톡