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

카카오톡 소셜

REST API

이 문서는 REST API를 사용한 카카오톡 소셜 API 구현 방법을 안내합니다.

이 문서에 포함된 기능은 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.

프로필 가져오기

기본 정보

GET /v1/api/talk/profile HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
사전 설정 카카오 로그인 사용자 동의
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
프로필 정보(닉네임/프로필 사진)
닉네임
프로필 사진

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡 프로필 정보를 받는 기능입니다. 카카오톡 프로필과 카카오계정 프로필의 차이에 대해서는 이해하기를 참고합니다.

액세스 토큰을 헤더에 담아 GET으로 요청하고, 응답은 JSON 객체로 받습니다. 사용자 카카오계정에 연결된 카카오톡이 없다면 에러 응답을 받습니다.

Request

Response

Name Type Description Required
nickName String 카카오톡 닉네임

필요한 동의 항목: 프로필 정보(닉네임/프로필 사진) 또는 닉네임
X
profileImageURL String 카카오톡 프로필 이미지 URL
640px * 640px 크기, HTTPS만 지원

필요한 동의 항목: 프로필 정보(닉네임/프로필 사진) 또는 프로필 사진
X
thumbnailURL String 카카오톡 프로필 썸네일(Thumbnail) 이미지 URL
110px * 110px 크기, HTTPS만 지원

필요한 동의 항목: 프로필 정보(닉네임/프로필 사진) 또는 프로필 사진
X

* countryISO: Deprecated, 사용자가 카카오톡을 이용 중인 국가(String), 공지 참고

프로필 정보 동의 항목 분리

2021년 6월 25일부터 프로필 정보가 '닉네임'과 '프로필 사진'으로 분리되어 제공됩니다. 분리된 동의 항목인 '닉네임'과 '프로필 사진' 동의 항목을 각각 설정하여 서비스에 필요한 프로필 정보만 선택적으로 제공 받을 수 있습니다. 기존 '프로필(닉네임/프로필 사진)' 동의 항목을 사용 중인 앱에서는 기존과 같이 해당 동의 항목을 통해 닉네임과 프로필 사진 정보를 모두 받을 수 있습니다. 기존 동의 항목을 사용하던 앱에서 분리된 동의 항목을 사용하려면 데브톡을 통해 변경을 요청합니다. 이 경우, 응답 구성이 변경될 수 있으므로 주의합니다. 자세한 사항은 공지사항을 참고합니다.

Sample

Request
curl -v -X GET "https://kapi.kakao.com/v1/api/talk/profile" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
Response: 성공
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "nickName":"홍길동",
  "profileImageURL":"https://xxx.kakao.co.kr/.../aaa.jpg",
  "thumbnailURL":"https://xxx.kakao.co.kr/.../bbb.jpg"
}
Response: 성공, 사용자가 닉네임만 동의한 경우
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "nickName":"홍길동"
}
Response: 성공, 사용자가 프로필 사진만 동의한 경우
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "profileImageURL":"https://xxx.kakao.co.kr/.../aaa.jpg",
  "thumbnailURL":"https://xxx.kakao.co.kr/.../bbb.jpg"
}
Response: 사용자가 모든 필요한 동의 항목에 동의하지 않은 경우
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{}

친구 목록 가져오기

기본 정보

GET /v1/api/talk/friends HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
사전 설정 카카오 로그인 사용자 동의 권한
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)
필요:
사용 권한

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡의 친구 정보를 받아 옵니다. 액세스 토큰을 헤더에 담아 GET으로 요청합니다. 정렬 순서, 한 페이지에 가져올 친구 수 등 파라미터를 선택적으로 사용할 수 있습니다.

응답은 JSON 객체로 받습니다. 카카오톡 친구 수가 요청 시 limit보다 많다면 결과가 페이지로 나뉩니다. 이 경우, 직접 개별 파라미터를 지정하지 않고도 액세스 토큰과 응답에 포함된 after_urlGET 요청을 해 다음 페이지의 친구 목록을 받아올 수 있습니다. 사용자 카카오계정에 연결된 카카오톡이 없다면 에러 응답을 받습니다.

파라미터 중 친구 정보를 정렬하는 기준은 orderfriend_order으로 설정합니다. 만약 친구 목록 응답에 즐겨찾기 친구들을 먼저 나오게 하고 싶다면 order는 'asc', friend_order은 'favorite'으로 지정합니다. 즐겨찾기 여부와 관계없이 닉네임 오름차순으로 친구 목록을 받아보려면 order는 'asc', friend_order은 'nickname'으로 지정합니다.

참고: 사용자 동의

만약 사용자가 카카오톡 친구 목록 제공에 동의하지 않아 요청이 실패한 경우, 다음 내용을 참고해 사용자 동의를 받은 후 다시 요청합니다.

  • 동의 항목에 [카카오 서비스 내 친구목록]을 사용하도록 설정했는지 확인합니다.
  • 추가 항목 동의 받기를 사용해 '카카오 서비스 내 친구목록'의 사용자 동의를 받습니다.
참고: 친구 목록 정렬 순서

친구 목록은 파라미터(order) 지정에 따라 오름차순(asc) 또는 내림차순(desc)으로 정렬되며, 기본 정렬 기준인 'asc'일 경우, 세부적인 정렬 순서는 다음과 같습니다. 'desc'일 경우는 아래의 정렬 순서와 반대로 정렬됩니다.

  • 한글: 한글, 특수문자, 숫자, 영어, 일본어, 이모지 순으로 정렬
  • 영어: 특수문자, 숫자, 영어, 일어, 한글, 이모지 순으로 정렬

기본적으로 한글 기준으로 정렬되지만, Kakao SDK를 통해 언어를 설정한 경우 영어 기준으로 정렬됩니다. friend_orderfavorite으로 설정해 즐겨찾기 친구 우선 정렬로 요청했다면 즐겨찾기 친구, 그 외 친구들의 정보 순으로 정렬되며, 각각 동일한 세부 정렬 순서가 적용됩니다.

Request

Parameter
Name Type Description Required
offset Integer 친구 목록 시작 지점(기본값: 0) X
limit Integer 한 페이지에 가져올 친구 최대 수(기본값: 10, 최대: 100) X
order String 친구 목록 정렬 순서
오름차순(asc) 또는 내림차순(desc)(기본값 asc)
X
friend_order String 친구 목록 정렬 시 기준 설정
favorite: 즐겨찾기 친구 우선 정렬
nickname: 닉네임 순서 정렬로 기준 설정
(기본값 favorite)
X

Response

Name Type Description Required
elements Friend[] 각 친구 정보를 담은 JSON 배열 X
total_count Integer 전체 친구 수 O
before_url String 친구 목록 이전 페이지 URL X
after_url String 친구 목록 다음 페이지 URL X
favorite_count Integer 즐겨찾기(favorite) 친구 수 X
Friend
Name Type Description Required
id Long 회원번호 O
uuid String 친구마다 고유한 값을 가지는 참고용 코드(Code)
카카오톡 메시지 전송 시 사용
O
favorite Boolean 해당 친구 즐겨찾기 여부 X
profile_nickname String 프로필 닉네임 X
profile_thumbnail_image String 프로필 썸네일(Thumbnail) 이미지
HTTPS만 지원
X

* allowed_msg: Deprecated, 메시지 차단 여부, 프로필 공개 설정 기능 추가에 따라 더 이상 사용되지 않음

Sample

Request: 친구 3명의 정보만 요청
curl -v -G GET "https://kapi.kakao.com/v1/api/talk/friends" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "limit=3"
Request: 친구 목록 다음 페이지 요청하기
curl -v -G GET "https://kapi.kakao.com/v1/api/talk/friends" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "offset=3" \
    -d "limit=3" \
    -d "order=asc"
Response
HTTP/1.1 200 OK
{
    "after_url": "https://kapi.kakao.com/v1/api/talk/friends?offset=3&limit=3&order=asc",
    "elements": [
        {
            "id": 00000000001,
            "uuid": "abcdefg0001",
            "favorite": true,
            "profile_nickname": "이수민",
            "profile_thumbnail_image": "https://xxx.kakao.co.kr/.../aaa.jpg"
        },
        {
            "id": 00000000002,
            "uuid": "abcdefg0002",
            "favorite": false,
            "profile_nickname": "홍길동",
            "profile_thumbnail_image": "https://xxx.kakao.co.kr/.../bbb.jpg"
        },
         {
            "id": 00000000003,
            "uuid": "abcdefg0003",
            "favorite": false,
            "profile_nickname": "김철수",
            "profile_thumbnail_image": "https://xxx.kakao.co.kr/.../ccc.jpg"
        }
    ],
    "total_count": 11,
    "favorite_count": 1
}

더보기