친구

친구 API는 앱에 가입한 사용자의 카카오톡 친구 정보를 제공해주는 API 입니다. 카카오계정 로그인을 사용하는 앱에서 사용할 수 있습니다.

  • 앱에 가입된 친구만 대상이 됩니다.
  • '서비스 내 친구목록' 정보 제공에 동의한 친구만 목록에 포함되고, 친구 리스트 중 친구 정보 제공에 동의하지 않은 경우 목록에서 제외됩니다.

API 활용 범위

  • 카카오톡 친구 정보를 활용하여 애플리케이션의 소셜 서비스를 구축 할 수 있습니다.
  • 해당 애플리케이션에 카카오톡 로그인을 통해서 서비스를 이용하는 친구들 중 카카오 '서비스 내 친구목록' 개인 정보 제공에 동의한 친구만 대상이 됩니다.
  • 사용자들의 친구 관계를 다른 사용자에게 제공해줄 수 없습니다.
  • 친구 정보를 따로 저장할 수 없습니다.
  • 친구들의 관계 정보를 분석/조합해서 제공해줄 수 없습니다.

친구목록 조회

친구 정보가 많을 수 있기 때문에 사용하는 클라이언트에서는 paging 기반으로 요청해야 합니다. 이를 위해 요청 파라미터로 offset, limit 이 제공되고 전달한 offset 인덱스부터 limit 개만큼의 결과를 가져옵니다.

해당 paging 기반 요청을 기준으로 더 불러올 친구 목록이 있는 경우, 응답 JSON 프로퍼티로 after_url이 주어지고 해당 url을 통해 다음 친구 paging을 요청하면 됩니다.

[Request]

GET /v1/friends HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

사용자 토큰을 헤더에 담아 GET으로 요청합니다. 사용자 토큰과 함께 아래 파라미터의 값을 선택적으로 추가할 수 있습니다.

설명 타입 필수
secure_resource 이미지 url을 secure url(http/https)로 받을 것인지 여부. Boolean X (false)
offset 가져올 친구 리스트의 시작 offset. Integer X (0)
limit 한 페이지에 가져올 친구 최대 수. (최대 100개) Integer X (100)
order 친구 리스트 정렬 순서. (“asc” or “desc”) String X (“asc”)

예를 들면,

curl -v -X GET "https://kapi.kakao.com/v1/friends?limit=3" \
    -H "Authorization: Bearer {access_token}"

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
elements 친구 리스트. (하위 상세 Element 정보는 Elements 상세를 참고한다.) List
total_count 앱에 가입 및 정보제공에 동의한 전체 친구의 수. Integer
before_url 이전 페이지 URL. 이전 페이지가 없을 경우 null. String
after_url 다음 페이지 URL. 다음 페이지가 없을 경우 null. String

Elements 상세
설명 타입
id 앱 유저 아이디. Long
profile_nickname 유저 프로필 닉네임. String
profile_thumbnail_image 유저 프로필 썸네일 이미지. String

예를 들면,

HTTP/1.1 200 OK
{
    "after_url": "https://kapi.kakao.com/v1/friends?offset=3&limit=3&order=asc",
    "elements": [
        {
            "id": 12345678901,
            "profile_nickname": "이수민",
            "profile_thumbnail_image": "http://xxx.kakao.co.kr/.../aaa.jpg"
        },
        {
            "id": 12345678004,
            "profile_nickname": "홍길동",
            "profile_thumbnail_image": "http://xxx.kakao.co.kr/.../bbb.jpg"
        },
         {
            "id": 12340078901,
            "profile_nickname": "김철수",
            "profile_thumbnail_image": "http://xxx.kakao.co.kr/.../ccc.jpg"
        }
    ],
    "total_count": 11
}

받아올 친구가 더 있는 경우 after_url에 url이 전달되며, 해당 url을 동일하게 GET 요청을 하면 다음 친구가 전달됩니다.

예를 들면,

curl -v -X GET 'https://kapi.kakao.com/v1/friends?offset=3&limit=3&order=asc' \
    -H "Authorization: Bearer {access_token}"

API 사용 제약

  • 검수 전에는 별도의 개인정보 제공 동의없이 내 애플리케이션 > 설정 > 팀관리에 설정된 카카오 계정의 톡 친구들에 한해서 동작하게 됩니다.
  • 해당 API를 서비스에 적용하려면 반드시 검수를 받아야 합니다. 친구 API 검수 신청하기

  • 검수를 마치면 내 애플리케이션 > 설정 > 사용자 관리 > 동의항목 > 설정에서 카카오 서비스 내 친구목록 개인정보 보호항목을 설정할 수 있게 됩니다.


Last Modified : 2018-08-27