페이지 이동경로

문서>
카카오톡 소셜>
REST API

카카오톡 소셜

REST API

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

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

카카오톡 프로필 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://kapi.kakao.com/v1/api/talk/profile`	액세스 토큰

권한	사전 설정	카카오 로그인	동의항목
필요: 동의항목	카카오 로그인 활성화 동의항목	필요	필요: 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진

로그인한 사용자의 카카오계정에 연결된 카카오톡 프로필 정보를 조회합니다.

카카오톡 프로필과 카카오계정 프로필

카카오 API로 조회 가능한 사용자의 프로필 종류와 차이점은 사용자 프로필에서 확인할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

응답

본문

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

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

프로필 정보 동의항목 분리

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

예제

요청

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/profile" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

응답: 성공

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"
}

응답: 성공, 사용자가 닉네임만 동의한 경우

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "nickName":"홍길동"
}

응답: 성공, 사용자가 프로필 사진만 동의한 경우

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"
}

응답: 사용자가 모든 필요한 동의항목에 동의하지 않은 경우

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{}

카카오톡 친구 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://kapi.kakao.com/v1/api/talk/friends`	액세스 토큰

권한	사전 설정	카카오 로그인	동의항목
필요: 사용 권한	카카오 로그인 활성화 동의항목	필요	필요: 카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)

로그인한 사용자의 카카오계정에 연결된 카카오톡 친구 정보를 조회합니다.

참고: 사용자 동의

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

동의항목에 [카카오 서비스 내 친구목록]을 사용하도록 설정했는지 확인합니다.
동의항목 추가 동의 요청 API로 '카카오 서비스 내 친구목록'의 사용자 동의를 받습니다.

참고: 친구 목록 정렬 순서

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

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

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

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

쿼리 파라미터

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

응답

본문

이름	타입	설명	필수
elements	`Friend[]`	각 친구 정보를 담은 `JSON` 배열	X
total_count	`Integer`	전체 친구 수	O
before_url	`String`	친구 목록 이전 페이지 URL	X
after_url	`String`	친구 목록 다음 페이지 URL	X
favorite_count	`Integer`	즐겨찾기(`favorite`) 친구 수	X

Friend

이름	타입	설명	필수
id	`Long`	회원번호	O
uuid	`String`	사용자 고유 아이디(`uuid`) 카카오톡 메시지 전송 시 사용	O
favorite	`Boolean`	해당 친구 즐겨찾기 여부	X
profile_nickname	`String`	프로필 닉네임	X
profile_thumbnail_image	`String`	프로필 썸네일(Thumbnail) 이미지 `HTTPS`만 지원	X

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

예제

요청: 친구 3명의 정보만 요청

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/friends" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "limit=3"

요청: 친구 목록 다음 페이지 요청하기

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"

응답

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
}

사용자 목록으로 카카오톡 프로필 조회

기본 정보

메서드	URL	인증 방식
`GET/POST`	`https://kapi.kakao.com/v2/api/talk/profiles`	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
필요: 동의항목	어드민 키 카카오 로그인 활성화 동의항목	필요	필요: 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진

서비스 사용자의 카카오톡 프로필 목록을 조회합니다. 지정한 특정 사용자가 확인 가능한 카카오톡 프로필 목록을 조회할 수도 있습니다.

사용자 목록으로 카카오톡 프로필 조회 API 동작

조회 대상 사용자 ID 목록(target_ids)에 미가입 사용자를 포함해 요청한 경우 API 호출이 실패합니다.
조회 기준 사용자 ID(viewer_id)를 포함한 경우, 해당 사용자가 확인 가능한 프로필 정보를 응답합니다.
응답 프로필 정보는 멀티프로필 노출 우선순위를 따릅니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

이름	타입	설명	필수
target_ids	`Long[]`	카카오톡 프로필을 가져올 대상 사용자 ID 목록	O
target_id_type	`String`	`target_id` 타입, `user_id`(회원번호)로 고정	O
viewer_id	`Long`	카카오톡 프로필을 조회할 때, 조회 기준이 될 사용자 ID `viewer_id`를 전달하지 않는 경우, `target_ids`로 전달한 사용자의 카카오톡 프로필만 응답	X
viewer_id_type	`String`	`viewer_id` 타입, `user_id`(회원번호)로 고정	X

응답

본문

이름	타입	설명	필수
viewer	`TalkProfileInfo`	요청한 `viewer_id`에 해당하는 사용자의 카카오톡 프로필 정보 파라미터에 `viewer_id`를 포함한 경우에만 제공	X
targets	`TalkProfileInfo[]`	`target_ids`로 지정한 사용자의 카카오톡 프로필 정보 목록 중요: `viewer_id`의 사용자와 친구인 경우, 사용자에게 보이는 멀티 프로필이 적용되어 반환	O

TalkProfileInfo

이름	타입	설명	필수
user_id	`Long`	회원번호, 카카오계정과 앱이 연결될 때 부여되는 앱별 사용자 고유 ID	O
nickname	`String`	카카오톡 프로필 닉네임 필요한 동의항목: 닉네임, 또는 프로필 정보(닉네임/프로필 사진)	X
profile_image	`String`	카카오톡 프로필 사진 URL 필요한 동의항목: 프로필 사진, 또는 프로필 정보(닉네임/프로필 사진)	X
thumbnail_image	`String`	카카오톡 프로필 썸네일 이미지 URL 필요한 동의항목: 프로필 사진, 또는 프로필 정보(닉네임/프로필 사진) 참고: 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리	X

예제

요청

curl -X GET "https://kapi.kakao.com/v2/api/talk/profiles" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -d "viewer_id=12345" \
  -d "viewer_id_type=user_id" \
  -d "target_ids=[9876,5432]" \
  -d "target_id_type=user_id"

응답: 성공, viewer_id를 전달한 경우

HTTP/1.1 200 OK
{
  "viewer": {
    "user_id": 12345,
    "nickname": "xxx",
    "profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg",
    "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg",
  },
  "targets": [
  {
    "user_id": 9876,
    "nickname": "yyy",
    "profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg",
    "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg",
  },
  {
    "user_id": 5432,
    "nickname": "zzz",
    "profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg",
    "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg",
  }
  ]
}

응답: 성공, 닉네임 동의항목만 필수 설정했거나, 사용자가 닉네임에만 동의한 경우

HTTP/1.1 200 OK
{
  "targets": [
    {
      "user_id": 9876,
      "nickname": "yyy",
    },
  ]
}

응답: 실패, viewer_id가 가입자가 아닌 경우

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
  "code": -101,
  "msg": "NotRegisteredUserException"
}

응답: 실패, 프로필 조회 대상 중 한 명이라도 서비스에 가입하지 않은 경우

HTTP/1.1 400 Bad request
Content-Type: application/json;charset=UTF-8
{
  "code": -2,
  "msg": "invalid target_ids. can get the profile only to registered users."
}

menu

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

카카오톡 소셜

REST API

카카오톡 프로필 조회

기본 정보

카카오톡 프로필과 카카오계정 프로필

요청

헤더

응답

본문

예제

요청

응답: 성공

응답: 성공, 사용자가 닉네임만 동의한 경우

응답: 성공, 사용자가 프로필 사진만 동의한 경우

응답: 사용자가 모든 필요한 동의항목에 동의하지 않은 경우

카카오톡 친구 목록 조회

기본 정보

참고: 사용자 동의

참고: 친구 목록 정렬 순서

요청

헤더

쿼리 파라미터

응답

본문

Friend

예제

요청: 친구 3명의 정보만 요청

요청: 친구 목록 다음 페이지 요청하기

응답

사용자 목록으로 카카오톡 프로필 조회

기본 정보

사용자 목록으로 카카오톡 프로필 조회 API 동작

요청

헤더

쿼리 파라미터

응답

본문

TalkProfileInfo

예제

요청

응답: 성공, viewer_id를 전달한 경우

응답: 성공, 닉네임 동의항목만 필수 설정했거나, 사용자가 닉네임에만 동의한 경우

응답: 실패, viewer_id가 가입자가 아닌 경우

응답: 실패, 프로필 조회 대상 중 한 명이라도 서비스에 가입하지 않은 경우

더 보기