카카오 소셜

REST API

이 문서는 카카오 또는 공동체 서비스용 카카오 소셜 REST API 사용법을 안내합니다.

카카오톡 프로필 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/talk/profile` 공동체 `https://kapi.kakao.com/v1/internal/talk/profile` 외부 `https://kapi.kakao.com/v1/api/talk/profile`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
-	어드민 키 카카오 로그인 활성화 동의항목	필요: 연결	필요: 이용 정책 참고

사용자 카카오계정에 연결된 카카오톡의 프로필 정보를 가져옵니다. 프로필은 닉네임(nickName), 프로필 이미지 URL(profileImageURL), 썸네일 이미지(thumbnailURL)로 구성돼 있습니다.

헤더에 원하는 인증 정보를 담아 GET으로 요청하고, 성공 시 사용자의 카카오톡 프로필 정보를 받습니다. 내부 API로 요청할 경우, 헤더의 인증 정보로 서비스 앱 어드민 키 방식과 위임 방식을 사용할 수 있습니다. 응답 구성에는 차이가 없습니다.

요청: 액세스 토큰 방식

헤더

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

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

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

쿼리 파라미터

이름	타입	설명	필수
target_id	`String`	카카오톡 프로필을 가져올 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O

요청: 위임 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	사용자 카카오톡 프로필을 가져올 서비스 앱의 키	O(Optional)
target_app_id	`Integer`	사용자 카카오톡 프로필을 가져올 서비스 앱의 ID	O(Optional)
target_access_token	`String`	카카오톡 프로필을 가져올 사용자의 액세스 토큰 값	O(Optional)
target_id	`String`	카카오톡 프로필을 가져올 사용자 ID	O(Optional)
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O(Optional)

응답

본문

이름	타입	설명	필수
id	`Long`	회원번호	O
nickName	`String`	카카오톡 프로필 닉네임 필요한 동의항목: 프로필(닉네임/프로필 사진) 또는 닉네임	X
profileImageURL	`String`	카카오톡 프로필 원본 이미지 URL 필요한 동의항목: 프로필(닉네임/프로필 사진) 또는 프로필 사진 참고: 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리	X
thumbnailURL	`String`	카카오톡 프로필 썸네일(Thumbnail) 이미지 URL 필요한 동의항목: 프로필(닉네임/프로필 사진) 또는 프로필 사진 참고: 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리	X

예제

요청: 액세스 토큰 방식

파라미터: 없음

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

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/profile" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=200513" \
  -d "target_id_type=account_id"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/profile" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_id_type=account_id" \
  -d "target_id=12345" \
  -d "target_app_key=${SERVICE_APP_KEY}"

요청: 위임 방식

파라미터
- 서비스 앱 ID(target_app_id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/profile" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_id_type=account_id" \
  -d "target_id=12345" \
  -d "target_app_id=55975"

요청: 위임 방식

파라미터
- 액세스 토큰(target_access_token)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/profile" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_access_token=${ACCESS_TOKEN}"

응답

{
  "id": 1234567,
  "nickName": "춘식이",
  "profileImageURL": "http://th-p.talk.kakao.co.kr/th/talkp/wkaIAOG3vK/PvT4raoSWPAq9Ds46kBSH0/q1ijr8_640x640_s.jpg",
  "thumbnailURL": "http://th-p.talk.kakao.co.kr/th/talkp/wkaIAOG3vK/PvT4raoSWPAq9Ds46kBSH0/q1ijr8_110x110_c.jpg"
}

응답, 사용자가 닉네임 동의항목만 동의한 경우

{
  "id": 1234567,
  "nickName": "춘식이"
}

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

기본 정보

메서드	URL	인증 방식
`GET/POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/profiles` 공동체 `https://kapi.kakao.com/v2/internal/talk/profiles`	서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
필요: 공동체 앱	어드민 키 카카오 로그인 활성화 동의항목	필요: 연결	필요: 이용 정책 참고

서비스 사용자의 카카오톡 프로필 목록을 조회합니다. 특정 사용자를 지정해 그 사용자 기준으로 보이는 카카오톡 프로필 목록을 조회할 수도 있습니다.

카카오톡 프로필 조회 API와 카카오톡 친구 목록 조회 API는 사용자의 인증 정보로 각각 서비스 사용자의 프로필과 친구 목록을 요청합니다. 반면, 이 API는 서비스 관리자가 서비스 어드민 키로 서비스 사용자의 카카오톡 프로필 정보를 조회합니다.

요청 시 조회할 사용자 ID 목록을 전달하면 사용자의 카카오톡 프로필 목록을 반환합니다. 조회 대상이 멀티 프로필을 설정한 경우, 멀티 프로필이 적용된 프로필 정보가 반환됩니다. 조회자와 조회 대상자가 친구 관계인 경우, 조회자 기준으로 노출되는 프로필 정보(닉네임, 이미지)가 반환됩니다. 프로필 정보 노출 우선순위를 참고합니다.

응답 중 카카오계정 ID(account_id), 카카오톡 회원번호(talk_user_id)는 권한이 있는 앱에서 요청한 경우에만 응답에 포함됩니다. 응답 제공에 필요한 동의항목을 함께 참고합니다.

요청: 서비스 앱 어드민 키 방식

헤더

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

쿼리 파라미터

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

요청: 위임 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_ids, target_id_type
- 서비스 앱 ID: target_app_id, target_ids, target_id_type

이름	타입	설명	필수
target_app_key	`String`	사용자 카카오톡 프로필을 가져올 서비스 앱의 키	O(Optional)
target_app_id	`Integer`	사용자 카카오톡 프로필을 가져올 서비스 앱의 ID	O(Optional)
target_ids	`String[]`	카카오톡 프로필을 가져올 대상 사용자 ID 목록	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
viewer_id	`String`	카카오톡 프로필을 조회할 때, 조회 기준이 될 사용자 ID	X
viewer_id_type	`String`	`viewer_id` 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	X

응답

본문

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

TalkProfileInfo

이름	타입	설명	필수
user_id	`Long`	회원번호	O
account_id	`Integer`	카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유	X
talk_user_id	`Long`	카카오톡 회원번호 제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유	X
nickname	`String`	카카오톡 프로필 닉네임 필요한 동의항목: 닉네임 또는 프로필 정보(닉네임/프로필 사진)	X
profile_image	`String`	카카오톡 프로필 사진 필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진)	X
thumbnail_image	`String`	카카오톡 프로필 썸네일 이미지 필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진) 참고: 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리	X

예제

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID 목록(target_ids)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)

curl -v -G "http://kapi.kakao.com/v2/internal/talk/profiles" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  --data-urlencode "target_ids=[200513,200937]" \
  --data-urlencode "target_id_type=account_id"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- (option) 프로필 조회 기준 사용자 ID(viewer_id)
- 사용자 ID 타입(target_id_type, viewer_id_type): 회원번호(user_id)
- 사용자 ID 목록(target_ids)

curl -v -G "http://kapi.kakao.com/v2/internal/talk/profiles" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  --data-urlencode "target_app_key=${SERVICE_APP_KEY}" \
  --data-urlencode "viewer_id=12345" \
  --data-urlencode "viewer_id_type=user_id" \
  --data-urlencode "target_id_type=user_id" \
  --data-urlencode "target_ids=[9876,5432]"

응답: viewer_id를 전달한 경우

// HTTP/1.1 200 OK
{
  "viewer": {
    "user_id": 12345, // 사용자 id
    "account_id": 7890, // account_id include 권한 필요
    "talk_user_id": 1222, // talk_user_id include 권한 필요
    "nickname": "xxx", // 사용자 카카오톡 닉네임
    "profile_image_url": "http://xxx.kakao.com/dn/.../img_640x640.jpg", // 사용자 카카오톡 프로필 사진
    "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg" // 사용자 카카오톡 썸네일 사진
  },
  "targets": [
    {
      "user_id": 9876,
      "account_id": 9999, // account_id include 권한 필요
      "talk_user_id": 8888, // talk_user_id include 권한 필요
      "nickname": "yyy",
      "profile_image_url": "http://xxx.kakao.com/dn/.../img_640x640.jpg",
      "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg"
    },
    {
      "user_id": 5432,
      "account_id": 11111, // account_id include 권한 필요
      "talk_user_id": 2222, // talk_user_id include 권한 필요
      "nickname": "zzz",
      "profile_image_url": "http://xxx.kakao.com/dn/.../img_640x640.jpg",
      "thumbnail_image": "http://yyy.kakao.com/dn/.../img_640x640.jpg"
    }
  ]
}

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

// HTTP/1.1 200 OK
[
  {
    "user_id": 1376012345429922124,
    "account_id": 200513, // 권한 필요
    "talk_user_id": 30173, // 권한 필요
    "nickname": "무지"
  }
  // ...
]

응답: 일부 사용자 프로필 조회에 실패한 경우

2명의 사용자를 대상으로 요청했으나, 한 명의 target_id가 유효하지 않아 나머지 한 명의 프로필 정보만 반환

// HTTP/1.1 200 OK
[
  {
    "user_id": 1376016924429922124,
    "nickname": "춘식이",
    "profile_image": "https://p.kakaocdn.net/th/talkp/wkaIC6OBUU/RK2hEsg9W8FgVvbJpZ05hK/b3f84m_640x640_s.jpg",
    "thumbnail_image": "https://p.kakaocdn.net/th/talkp/wkaIC6OBUU/RK2hEsg9W8FgVvbJpZ05hK/b3f84m_110x110_c.jpg"
  }
]

응답: 모든 사용자 프로필 조회에 실패한 경우

여러 명의 사용자를 대상으로 요청했으나, 모든 target_id가 유효하지 않아 빈 배열 반환

// HTTP/1.1 200 OK
[]

카카오톡 친구 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/talk/friends` 공동체 `https://kapi.kakao.com/v1/internal/talk/friends` 외부 `https://kapi.kakao.com/v1/api/talk/friends`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
-	어드민 키 카카오 로그인 활성화 동의항목 유료 API: 공동체 앱	필요: 연결	필요: 이용 정책 참고

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡의 친구 정보를 가져옵니다. 공동체 앱에는 권한에 따라 내부 API 및 아래 추가 정보를 제공합니다.

카카오계정 ID
카카오톡 회원번호

이 API와 인하우스 앱 전용 API인 인하우스 앱: 카카오톡 친구 목록 조회는 아래와 같은 차이가 있습니다.

API	카카오톡 친구 목록 조회	인하우스 앱: 카카오톡 친구 목록 조회
조회 대상 서비스	카카오톡	카카오톡
조회 대상 친구*	앱과 연결된 친구 필요한 동의항목에 동의한 친구	앱과 연결된 친구, 앱과 연결되지 않은 친구 모두 지원 친구의 동의 여부가 응답에 영향 주지 않음
필터링 옵션 (별도 권한 필요)	없음	카카오톡 국가 코드, 카카오톡 OS

* 두 API 모두 프로필 공개 설정이 비공개인 사용자는 응답에 포함되지 않음

이 API는 서비스에서 직접 친구 목록 UI를 구성하고자 할 때 사용합니다. 친구 목록을 직접 구성할 필요가 없다면, Kakao SDK에서 제공하는 친구 피커를 사용할 것을 권장합니다.

원하는 인증 정보를 헤더에 담아 GET으로 요청합니다. 요청 시 friend_order 파라미터로 친구 목록 정렬 기준을 지정할 수 있습니다.

응답은 카카오톡 친구 수, 즐겨찾기 친구 수, 친구 정보 목록을 포함합니다. 카카오계정 ID(account_id), 카카오톡 회원번호(talk_user_id)는 권한이 있는 앱에서 요청한 경우에만 응답에 포함됩니다.

각 친구의 카카오톡 프로필 정보는 친구가 응답 제공에 필요한 동의항목에 동의한 경우에 한해 제공됩니다. 카카오톡 프로필 정보 제공 기준은 카카오톡 프로필 정보 우선순위를 참고합니다.

응답의 친구 수가 limit 값을 초과해 친구 목록이 페이지 형태로 나뉜 경우, 아래 또는 이전 페이지를 조회할 수 있는 after_url과 before_url 값을 제공합니다.

응답에 일부 친구가 포함되지 않은 경우, 친구 정보 제공 조건을 참고해 원인을 확인합니다.

요청: 액세스 토큰 방식

헤더

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

쿼리 파라미터

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

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

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

쿼리 파라미터

이름	타입	설명	필수
target_id	`String`	친구 목록을 가져올 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
offset	`Integer`	친구 목록 시작 지점(기본값 `0`)	X
limit	`Integer`	한 페이지에 가져올 친구의 수 기본값: `100`(외부 URL로 호출 시 `10`), 최대: `10000`	X
order	`String`	친구 목록 정렬 순서 오름차순(`asc`) 또는 내림차순(`desc`)(기본값: `asc`)	X
friend_order	`String`	친구 목록 정렬 기준 설정 `favorite`: 즐겨찾기 친구 우선 정렬 `nickname`: 카카오톡 닉네임 순서 정렬 (기본값 `favorite`)	X

요청: 위임 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

본문

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	사용자 친구 목록을 가져올 서비스 앱의 키	O(Optional)
target_app_id	`Integer`	사용자 친구 목록을 가져올 서비스 앱의 ID	O(Optional)
target_access_token	`String`	친구 목록을 가져올 사용자의 액세스 토큰 값	O(Optional)
target_id	`String`	친구 목록을 가져올 사용자 ID	O(Optional)
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O(Optional)
offset	`Integer`	친구 목록 시작 지점(기본값 `0`)	X
limit	`Integer`	한 페이지에 가져올 친구의 수 기본값: `100`(외부 URL로 호출 시 `10`), 최대: `10000`	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`	회원번호(`user_id`)	O
uuid	`String`	사용자 고유 ID, 카카오톡 메시지 전송 시 사용 참고: ID 종류	O
account_id	`Integer`	카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유, 내부 API 요청	X
talk_user_id	`Long`	카카오톡 회원번호 제공 조건: 카카오톡 회원번호 응답 권한 보유, 내부 API 요청	X
favorite	`Boolean`	해당 친구 즐겨찾기 여부	X
profile_nickname	`String`	카카오톡 프로필 닉네임 필요한 동의항목: 아래 중 하나 프로필 정보(닉네임/프로필 사진) 닉네임 카카오 서비스내 친구목록(즐겨찾기, 프로필사진, 닉네임 포함) 참고: 카카오톡 프로필 정보 우선순위	X
profile_thumbnail_image	`String`	카카오톡 프로필 썸네일(Thumbnail) 이미지 URL 필요한 동의항목: 아래 중 하나 프로필 정보(닉네임/프로필 사진) 프로필 사진 카카오 서비스내 친구목록(즐겨찾기, 프로필사진, 닉네임 포함) 참고: 카카오톡 프로필 정보 우선순위, 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리	X

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

예제

요청: 액세스 토큰 방식

파라미터
- 한 페이지에 가져올 친구의 수(limit): 500

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

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)
- 한 페이지에 가져올 친구의 수(limit): 2000

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/friends" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=2137162" \
  -d "target_id_type=account_id" \
  -d "limit=2000"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)
- 한 페이지에 가져올 친구의 수(limit): 1000

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/friends" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_id=1376016924426709466" \
  -d "target_id_type=user_id" \
  -d "target_app_key=${SERVICE_APP_KEY}" \
  -d "limit=1000"

요청: 위임 방식

파라미터
- 서비스 앱 ID(target_app_id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오톡 회원번호(talk_id)
- 한 페이지에 가져올 친구의 수(limit): 1000

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/friends" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_id=700119942" \
  -d "target_id_type=talk_id" \
  -d "target_app_id=977071" \
  -d "limit=1000"

요청: 위임 방식

파라미터
- 액세스 토큰(target_access_token)
- 한 페이지에 가져올 친구의 수(limit): 1000

curl -v -G GET 'http://kapi.kakao.com/v1/internal/talk/friends' \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_access_token=${ACCESS_TOKEN}" \
  -d "limit=1000"

응답

// HTTP/1.1 200 OK
{
  "elements": [
    {
      "profile_nickname": "무지",
      "profile_thumbnail_image": "https://p.kakaocdn.net/th/talkp/wmBecgciWj/JVCSaBKdnYVcaThgIjvPvk/3v0e00_110x110_c.jpg",
      "id": 1050570723,
      "uuid": "7NXm0OLV-cj5yPnB8cPv3eTU4djriR",
      "favorite": false
    },
    {
      "profile_nickname": "어피치",
      "profile_thumbnail_image": "https://p.kakaocdn.net/th/talkp/wkOGobjPrA/rqxKF3MiHKO6Yy6QZMTRd1/9dze00_110x110_c.jpg",
      "id": 1057443045,
      "uuid": "7N7m3-be59f7yfnA-M77wvPL59Xs3OnQ42C",
      "favorite": false
    },
    {
      "profile_nickname": "프로도",
      "profile_thumbnail_image": "https://p.kakaocdn.net/th/talkp/wkOGobjPrA/rqxKF3MiHKO6Yy6QZMTRd1/sf2e00_110x110_c.jpg",
      "id": 1054423045,
      "uuid": "7N7m3-be59f7yfnA-M77wvPL59Xs4snQ42C",
      "favorite": false
    }
  ],
  "total_count": 20,
  "after_url": "http://kapi.kakao.com/v1/internal/talk/friends?offset=4&limit=3&order=asc",
  "favorite_count": 0
}

응답: 일부 친구가 목록에 포함되지 않은 경우

총 5명의 연결된 친구가 있지만, 그 중 1명은 [카카오 서비스 내 친구목록] 동의항목에 동의하지 않음
동의하지 않은 친구는 elements와 total_count에 모두 포함되지 않음

// HTTP/1.1 200 OK
{
  "elements": [
    {
      "profile_nickname": "무지",
      "profile_thumbnail_image": "https://p.kakaocdn.net/th/talkp/wmBecgciWj/JVCSaBKdnYVcaThgIjvPvk/3v0e00_110x110_c.jpg",
      "id": 1050570723,
      "uuid": "7NXm0OLV-cj5yPnB8cPv3eTU4djriR",
      "favorite": false
    },
    {
      "profile_nickname": "어피치",
      "profile_thumbnail_image": "https://p.kakaocdn.net/th/talkp/wkOGobjPrA/rqxKF3MiHKO6Yy6QZMTRd1/9dze00_110x110_c.jpg",
      "id": 1057443045,
      "uuid": "7N7m3-be59f7yfnA-M77wvPL59Xs3OnQ42C",
      "favorite": false
    },
    {
      "profile_nickname": "프로도",
      "profile_thumbnail_image": "https://p.kakaocdn.net/th/talkp/wdDGobjPQs/tqxKF3Mi34owYy6QZMTRd1/sf2e00_110x110_c.jpg",
      "id": 105442311,
      "uuid": "2efeT-be59f7yfnA-5LewvKL59Xs8tbEO2C",
      "favorite": false
    },
    {
      "profile_nickname": "제이지",
      "profile_thumbnail_image": "https://p.kakaocdn.net/th/talkp/wIOnobjPyU/uqeKF3MiHK23Aa6QZMTRd1/3d64fr_110x110_c.jpg",
      "id": 1054425718,
      "uuid": "23qpO-ls5vT7yfnA-T2wWeUo59Xs4snS31q",
      "favorite": false
    }
  ],
  "total_count": 4,
  "after_url": "http://kapi.kakao.com/v1/internal/talk/friends?offset=4&limit=3&order=asc",
  "favorite_count": 0
}

응답: 닉네임 동의항목만 필수 설정했거나, 친구가 닉네임에만 동의한 경우

// HTTP/1.1 200 OK
{
  "elements": [
    {
      "profile_nickname": "무지",
      "id": 1050570723,
      "uuid": "7NXm0OLV-cj5yPnB8cPv3eTU4djriR",
      "favorite": false
    }
    // ...
  ],
  "total_count": 20,
  "after_url": "http://kapi.kakao.com/v1/internal/talk/friends?offset=4&limit=3&order=asc",
  "favorite_count": 0
}

읽지 않은 채팅방 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v2/internal/talk/unread_chats` 공동체 `https://kapi.kakao.com/v2/internal/talk/unread_chats`	액세스 토큰 서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
필요: 공동체 앱	어드민 키 카카오 로그인 활성화 동의항목	필요: 연결	필요: 이용 정책 참고

사용자의 카카오계정과 연결된 카카오톡에서 읽지 않은 메시지가 있는 채팅방 목록을 가져옵니다. 이 API는 오픈채팅을 지원하지 않습니다.

원하는 인증 정보를 헤더에 담아 GET으로 요청하고, 성공 시 사용자가 읽지 않은 메시지가 있는 채팅방 목록을 받습니다. 파라미터로 필터를 지정한 경우에는 조건에 부합하는 채팅방 정보 목록을 제공합니다.

응답의 채팅방의 이름 및 이미지는 아래와 같은 기준을 적용합니다.

채팅방에 이름 및 이미지를 설정한 경우, 사용자가 카카오톡 클라이언트에서 설정한 이름과 동기화되어 제공
채팅방에 이름을 설정하지 않은 경우
- 1:1 채팅방: 대화 상대가 직접 설정한 닉네임으로 채팅방 이름을 대체해 제공
- 그룹 채팅방: 채팅방 멤버를 카카오톡 회원번호를 기준으로 정렬한 뒤, 그중 상위 5명 멤버의 닉네임을 쉼표(,)로 구분해 조합한 문자열로 채팅방 이름을 대체해 제공, 각 멤버가 직접 설정한 닉네임 사용
채팅방에 이미지를 설정하지 않은 경우
- 응답에 채팅방 이미지(image_url) 제공하지 않음
- 멤버들의 썸네일 이미지 목록(display_member_images)을 토대로 직접 구성해야 함
일부 응답에 멀티프로필 적용
- 채팅방 이름(title): title_source가 별도 설정 없음(default)인 경우, 요청 사용자(target_id)를 기준으로 멤버들의 멀티프로필 닉네임 적용
- 멤버 이미지(display_member_images): 멤버들의 썸네일 이미지 조합으로써 요청 사용자(target_id)를 기준으로 멀티프로필 썸네일 이미지 적용

요청: 액세스 토큰 방식

헤더

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

쿼리 파라미터

이름	타입	설명	필수
filter_id	`String`	`filter_id_type`에 해당하는 ID `chat_id`의 경우 해당 채팅방의 읽지 않은 메시지가 있는지 확인 `account_id`나 `user_id`의 경우에는 `talk_id`로 변환해 1:1 채팅방(`Direct`)의 읽지 않은 메시지가 있는지 확인 `filter_id` 및 `filter_id_type`이 없을 경우 최대 채팅방 30개 확인	X
filter_id_type	`String`	`filter_id` 타입, 아래 중 하나 `chat_id`: 채팅방 ID `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `filter_id` 또는 `filter_id_type`이 지정되지 않은 경우 최대 30개의 읽지 않은 메시지가 있는 채팅방 목록 제공	X
limit	`Integer`	한 페이지에 가져올 채팅방 수(기본값: `30`, 최대: `30`)	X
after_id	`Long`	특정 `chat_id` 이후의 채팅방 목록을 요청하기 위한 기준 ID	X

요청: 서비스 앱 어드민 키 방식

헤더

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

쿼리 파라미터

이름	타입	설명	필수
target_id	`String`	읽지 않은 채팅방 목록을 가져올 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
filter_id	`String`	`filter_id_type`에 해당하는 ID `chat_id`의 경우 해당 채팅방의 읽지 않은 메시지가 있는지 확인 `account_id`나 `user_id`의 경우에는 `talk_id`로 변환해 1:1 채팅방(`Direct`)의 읽지 않은 메시지가 있는지 확인 `filter_id` 및 `filter_id_type`이 없을 경우 최대 채팅방 30개 확인	X
filter_id_type	`String`	`filter_id` 타입, 아래 중 하나 `chat_id`: 채팅방 ID `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `filter_id` 또는 `filter_id_type`이 지정되지 않은 경우 최대 30개의 읽지 않은 메시지가 있는 채팅방 목록 제공	X
limit	`Integer`	한 페이지에 가져올 채팅방 수(기본값: `30`, 최대: `30`)	X
after_id	`Long`	특정 `chat_id` 이후의 채팅방 목록을 요청하기 위한 기준 ID	X

응답

본문

이름	타입	설명	필수
elements	`ChatInfo[]`	각 채팅방 정보로 구성된 목록	O
total_count	`Integer`	읽지 않은 채팅방 수	X
after_url	`String`	읽지 않은 채팅방 목록 중 현재 페이지의 다음 페이지 URL `null`일 경우 다음 페이지가 존재하지 않음	X

ChatInfo

이름	타입	설명	필수
id	`Long`	채팅방 ID	O
title	`String`	채팅방 이름	X
title_source	`String`	채팅방 이름 타입, 아래 중 하나 `user`: 사용자가 설정한 이름 `chat`: 채팅방 생성 시 설정된 이름 `default`: 별도 설정 없음	X
image_url	`String`	채팅방 이미지 채팅방에 지정된 이미지가 없어 응답에 포함되지 않은 경우 `display_member_images`를 참조할 것	X
member_count	`Integer`	채팅방 멤버 수	X
display_member_images	`String[]`	채팅방 멤버 중 최대 5명의 썸네일 이미지 목록 중요: 멤버의 프로필이 존재하지 않을 경우 응답에 포함되지 않을 수 있음	X
chat_room_type	`String`	채팅방 타입, 아래 중 하나 `MemoChat`: 나와의 채팅방 `DirectChat`: 다른 사용자와의 1:1 채팅방 `MultiChat`: 다른 사용자들과의 그룹 채팅방 `OpenDirectChat`: 1:1 오픈채팅방 `OpenMultiChat`: 그룹 오픈채팅방	X
direct_chat_talk_user_id	`Long`	1:1 채팅방의 상대방 카카오톡 회원번호 중요: `chat_room_type`이 `DirectChat`이며, 별도 응답 권한을 보유한 경우에만 응답에 포함	X
unread_message_count	`Integer`	읽지 않은 메시지 수 읽지 않은 채팅방 목록 조회 호출 시에만 포함	X

* chat_type: Deprecated, chat_room_type으로 변경

예제

요청: 액세스 토큰 방식

파라미터: 없음

curl -X GET "http://kapi.kakao.com/v2/internal/talk/unread_chats" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -X GET "http://kapi.kakao.com/v2/internal/talk/unread_chats" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id=1376016924426684995"

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오톡 회원번호(talk_id)

curl -X GET "http://kapi.kakao.com/v2/internal/talk/unread_chats" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id_type=talk_id" \
  -d "target_id=700009318"

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)

curl -X GET "http://kapi.kakao.com/v2/internal/talk/unread_chats" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id_type=account_id" \
  -d "target_id=1000"

응답

{
  "elements": [
    {
      "id": 88604424245226298,
      "title": "잡담방",
      "member_count": 26,
      "image_url": "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/kLyxKPKmDeCMcuigHqPN70/1p1vfb_110x110_c.jpg",
      "display_member_images": ["http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/AAAXXX.jpg", "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/BBBXXX.jpg", "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/CCCXXX.jpg", "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/DDDXXX.jpg", "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/DDDXXX.jpg"],
      "chat_room_type": "MultiChat",
      "unread_message_count": 3
    },
    {
      "id": 8824612356722704,
      "title": "업무방",
      "title_source": "default",
      "member_count": 8,
      "display_member_images": ["http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/EEEXXX.jpg", "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/FFFXXX.jpg", "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/GGGXXX.jpg", "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/HHHXXX.jpg", "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/IIIXXX.jpg"],
      "chat_room_type": "MultiChat",
      "unread_message_count": 1
    }
  ],
  "total_count": 3,
  "after_url": "http://kapi.kakao.com/v2/internal/talk/unread_chats?target_id_type=user_id&target_id=1376016924426684995&limit=2&after_id=8824612356722704"
}

사용처 제한 API

사용 협의 필요

사용처 제한 API는 지정된 사용처에만 제공하는 카카오 API입니다. 지정된 사용처 이외의 서비스에서 사용처 제한 API를 사용하려면 [서비스] API플랫폼 아지트에서 별도 협의가 필요합니다.

인하우스 앱: 카카오톡 친구 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/friends` 공동체 `https://kapi.kakao.com/v1/internal/friends` 외부 `https://kapi.kakao.com/v1/friends` 배치 `http://kapi.kakao.com/v1/internal/friends/batch`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
인하우스 앱 전용 배치 API: 별도 사용 권한 필요	어드민 키 카카오 로그인 활성화 동의항목	필요: 연결	필요: 카카오 서비스 내 친구목록

사용자의 카카오계정과 연결된 카카오톡 친구 정보를 가져옵니다. 이 API는 인하우스 앱 전용 API이며, 카카오톡 친구 목록 조회에서 오픈 API와 다른 점을 확인할 수 있습니다.

원하는 인증 정보를 헤더에 담아 GET으로 요청합니다. 요청 시 friend_order 파라미터로 친구 목록 정렬 기준을 지정할 수 있습니다.

응답은 카카오톡 친구 정보 목록을 받습니다. 카카오계정 ID(account_id), 카카오톡 회원번호(talk_id)는 권한이 있는 앱에서 내부 API로 요청한 경우에만 응답에 포함됩니다. 카카오톡 프로필 정보 제공 기준은 카카오톡 프로필 정보 우선순위를 참고합니다.

응답에 일부 친구가 포함되지 않은 경우, 친구 정보 제공 조건을 참고해 원인을 확인합니다.

친구 타입과 필터링 옵션

파라미터로 상세한 조회 조건을 지정할 수 있습니다.

친구 목록 필터링 옵션(friend_filter)
- 없음(none)
- 앱과 연결된 친구(registered)
- 앱과 연결되지 않은 친구(invitable)
- 생일인 친구(birthday)

예를 들어, 카카오톡 친구 중 앱과 연결된 친구 목록을 불러오려면 파라미터에 friend_filter=registered를 포함해 요청합니다.

카카오톡의 친구 관계

내부 API로 요청할 경우, 사용자와 각 친구의 친구 관계 정보(talk_friend_status)가 응답에 포함됩니다.
친구 관계의 유형은 아래와 같습니다.
- 1: NOT_IN_CONTACT (나에게만 친구 중 연락처에 없는 친구, 단방향 친구)
- 2: IN_CONTACT (나에게만 친구 중 연락처에 있는 친구, 단방향 친구)
- 3: MUTUAL (서로 친구, 양방향 친구)

생일 정보 제공 조건

아래 조건을 모두 만족한 경우에만 응답에 친구의 생일 정보(birthday)가 포함됩니다.

응답에 생일 정보를 포함하도록 요청한 경우
- 친구 목록 필터링 옵션(friend_filter)을 생일인 친구(birthday)로 지정
- 응답 구성 설정(friend_option)에 INCLUDE_BIRTHDAY 포함
생일인 친구 조회 기간 시작일(birthday_from)부터 종료일(birthday_to) 이내에 생일이 포함된 친구인 경우
- 생일인 친구 조회 기간에 생일이 포함되지 않은 친구는 생일 정보 미제공
- 음력 생일이 설정된 친구는 양력 생일로 변환한 날짜가 생일인 친구 조회 기간에 포함될 경우 생일 정보 제공
사용자가 카카오톡의 [더보기] > [설정] > [관리] > [생일 알림] 설정을 켠 경우

이 API는 샌드박스 페이즈에서만 샘플 앱으로 테스트 가능합니다.

샘플 앱 이외의 앱으로 테스트하려면 해당 앱에 필요한 권한을 받아야 합니다.

요청: 액세스 토큰 방식

헤더

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

쿼리 파라미터

이름	타입	설명	필수
friend_filter	`String`	친구 목록 필터링 옵션, 아래 중 하나 `none`: 전체 친구 `registered`: 앱에 연결된 친구 `invitable`: 앱에 연결되지 않은 친구 `birthday`: 생일인 친구 (기본값: `none`)	X
friend_order	`String`	친구 목록 정렬 기준, 아래 중 하나 `favorite`: 즐겨찾기 `nickname`: 닉네임 (기본값: `nickname`) 참고: 카카오 리치보드게임의 경우, 별도 기준(`age`)을 적용해 미성년자 제외 및 성인 우선 정렬	X
friend_option	`String`	응답 구성 설정 `INCLUDE_BIRTHDAY`: 응답에 생일(`birthday`) 필드 제공 중요: `friend_filter`를 `birthday`로 지정한 경우 `INCLUDE_BIRTHDAY`를 기본값으로 적용	X
country_codes	`String`	친구 국가 코드로 요청 결과를 필터링할 때 사용 "country_codes=kr,us,jp,cn" 형식으로 여러 개의 국가 코드를 쉼표(,)로 구분	X
offset	`Integer`	가져올 친구 목록의 시작 지점(기본값: 0, 처음부터)	X
limit	`Integer`	한 페이지에 가져올 친구의 수 기본값: `100`(외부 URL로 호출 시 `10`), 최대: `10000`	X
order	`String`	친구 리스트 정렬 순서, 아래 중 하나 `asc`: 오름차순 `desc`: 내림차순 (기본값: `asc`)	X
birthday_from	`String`	생일인 친구 조회 기간 시작일, `yyyyMMdd` 형식 미지정 시 기본값 적용 `birthday_from` 사용 시 `birthday_to`도 필수 사용 (기본값: 요청일로부터 2일 전의 날짜) 중요: `friend_filter`를 `birthday`로 지정하거나, `friend_option`에 `INCLUDE_BIRTHDAY`를 포함하지 않은 경우 입력된 값 무시	X
birthday_to	`String`	생일인 친구 조회 기간 종료일, `yyyyMMdd` 형식 미지정 시 기본값 적용 `birthday_from`으로부터 31일 이내여야 함 `birthday_to` 사용 시 `birthday_from`도 필수 사용 (기본값: 요청일로부터 7일 후의 날짜) 중요: `friend_filter`를 `birthday`로 지정하거나, `friend_option`에 `INCLUDE_BIRTHDAY`를 포함하지 않은 경우 입력된 값 무시	X

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

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

쿼리 파라미터

이름	타입	설명	필수
target_id	`String`	친구 목록을 가져올 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
friend_filter	`String`	친구 목록 필터링 옵션, 아래 중 하나 `none`: 전체 친구 `registered`: 앱에 연결된 친구 `invitable`: 앱에 연결되지 않은 친구 `birthday`: 생일인 친구 (기본값: `none`)	X
friend_order	`String`	친구 목록 정렬 기준, 아래 중 하나 `favorite`: 즐겨찾기 `nickname`: 닉네임 (기본값: `nickname`) 참고: 카카오 리치보드게임의 경우, 별도 기준(`age`)을 적용해 미성년자 제외 및 성인 우선 정렬	X
friend_option	`String`	응답 구성 설정 `INCLUDE_BIRTHDAY`: 응답에 생일(`birthday`) 필드 추가 제공 중요: `friend_filter`를 `birthday`로 지정한 경우 `INCLUDE_BIRTHDAY`를 기본값으로 적용	X
country_codes	`String`	친구 국가 코드로 요청 결과를 필터링할 때 사용 "country_codes=kr,us,jp,cn" 형식으로 여러 개의 국가 코드를 쉼표(,)로 구분	X
offset	`Integer`	가져올 친구 목록의 시작 지점(기본값: 0, 처음부터)	X
limit	`Integer`	한 페이지에 가져올 친구의 수 기본값: `100`(외부 URL로 호출 시 `10`), 최대: `10000`	X
order	`String`	친구 리스트 정렬 순서, 아래 중 하나 `asc`: 오름차순 `desc`: 내림차순 (기본값: `asc`)	X
birthday_from	`String`	생일인 친구 조회 기간 시작일, `yyyyMMdd` 형식 미지정 시 기본값 적용 `birthday_from` 사용 시 `birthday_to`도 필수 사용 (기본값: 요청일로부터 2일 전의 날짜) 중요: `friend_filter`를 `birthday`로 지정하거나, `friend_option`에 `INCLUDE_BIRTHDAY`를 포함하지 않은 경우 입력된 값 무시	X
birthday_to	`String`	생일인 친구 조회 기간 종료일, `yyyyMMdd` 형식 미지정 시 기본값 적용 `birthday_from`으로부터 31일 이내여야 함 `birthday_to` 사용 시 `birthday_from`도 필수 사용 (기본값: 요청일로부터 7일 후의 날짜) 중요: `friend_filter`를 `birthday`로 지정하거나, `friend_option`에 `INCLUDE_BIRTHDAY`를 포함하지 않은 경우 입력된 값 무시	X

요청: 위임 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	사용자 친구 목록을 가져올 서비스 앱의 키	O(Optional)
target_app_id	`Integer`	사용자 친구 목록을 가져올 서비스 앱의 ID	O(Optional)
target_access_token	`String`	친구 목록을 가져올 사용자의 액세스 토큰 값	O(Optional)
target_id	`String`	친구 목록을 가져올 사용자 ID	O(Optional)
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O(Optional)
friend_filter	`String`	친구 목록 필터링 옵션, 아래 중 하나 `none`: 전체 친구 `registered`: 앱에 연결된 친구 `invitable`: 앱에 연결되지 않은 친구 `birthday`: 생일인 친구 (기본값: `none`)	X
friend_order	`String`	친구 목록 정렬 기준, 아래 중 하나 `favorite`: 즐겨찾기 `nickname`: 닉네임 (기본값: `nickname`) 참고: 카카오 리치보드게임의 경우, 별도 기준(`age`)을 적용해 미성년자 제외 및 성인 우선 정렬	X
friend_option	`String`	응답 구성 설정 `INCLUDE_BIRTHDAY`: 응답에 생일(`birthday`) 필드 추가 제공 중요: `friend_filter`를 `birthday`로 지정한 경우 `INCLUDE_BIRTHDAY`를 기본값으로 적용	X
country_codes	`String`	친구 국가 코드로 요청 결과를 필터링할 때 사용 "country_codes=kr,us,jp,cn" 형식으로 여러 개의 국가 코드를 쉼표(,)로 구분	X
offset	`Integer`	가져올 친구 목록의 시작 지점(기본값: 0, 처음부터)	X
limit	`Integer`	한 페이지에 가져올 친구의 수 기본값: `100`(외부 URL로 호출 시 `10`), 최대: `10000`	X
order	`String`	친구 리스트 정렬 순서, 아래 중 하나 `asc`: 오름차순 `desc`: 내림차순 (기본값: `asc`)	X
birthday_from	`String`	생일인 친구 조회 기간 시작일, `yyyyMMdd` 형식 미지정 시 기본값 적용 `birthday_from` 사용 시 `birthday_to`도 필수 사용 (기본값: 요청일로부터 2일 전의 날짜) 중요: `friend_filter`를 `birthday`로 지정하거나, `friend_option`에 `INCLUDE_BIRTHDAY`를 포함하지 않은 경우 입력된 값 무시	X
birthday_to	`String`	생일인 친구 조회 기간 종료일, `yyyyMMdd` 형식 미지정 시 기본값 적용 `birthday_from`으로부터 31일 이내여야 함 `birthday_to` 사용 시 `birthday_from`도 필수 사용 (기본값: 요청일로부터 7일 후의 날짜) 중요: `friend_filter`를 `birthday`로 지정하거나, `friend_option`에 `INCLUDE_BIRTHDAY`를 포함하지 않은 경우 입력된 값 무시	X

응답

본문

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

InhouseFriend

카카오톡 친구 목록 조회와 다른 제휴 API 응답 정보입니다.
일부 응답은 내부 API로 요청할 경우에만 제공됩니다.

이름	타입	설명	필수
id	`Long`	친구의 회원번호(user_id), 앱과 연결된 친구에게만 존재	X
uuid	`String`	사용자 고유 ID 참고: ID 종류	O
account_id	`Integer`	카카오계정이 있는 친구의 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유, 내부 API 요청	X
talk_user_id	`Long`	친구의 카카오톡 회원번호 제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유, 내부 API 요청	X
app_registered	`Boolean`	친구의 앱 연결 여부	X
profile_nickname	`String`	친구의 대표 프로필 닉네임 참고: 카카오톡 프로필 정보 우선순위	X
profile_thumbnail_image	`String`	친구의 대표 썸네일(Thumbnail) 이미지 URL 참고: 카카오톡 프로필 정보 우선순위, 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리	X
talk_os	`String`	카카오톡 가입 기기의 OS 정보, 아래 중 하나 `android`: 안드로이드 `ios`: iOS	X
favorite	`Boolean`	카카오톡의 친구 즐겨찾기 여부	X
relation	`Relation`	카카오톡 사용자와 친구의 관계	X
birthday	`String`	친구의 생일, `yyyyMMdd` 형식 생일 정보 제공 조건 참고	X

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

Relation

카카오톡 친구 목록 조회와 다른 제휴 API 응답 정보입니다.
일부 응답은 내부 URL로 요청할 경우에만 제공됩니다.

이름	타입	설명	필수
talk	`String`	친구와 내가 카카오톡 친구인지 여부, 아래 중 하나 friend: 친구 no_friend: 친구 아님 N/A: 카카오톡 친구 요청이 아니어서 알 수 없음	X
talk_friend_status	`Int`	카카오톡 친구인 경우 친구와 나의 카카오톡의 친구 관계, 아래 중 하나 3: `MUTUAL`, 서로 친구 2: `IN_CONTACT`, 나에게만 친구 중 연락처에 있는 친구 1: `NOT_IN_CONTACT`, 나에게만 친구 중 연락처에 없는 친구 카카오톡의 친구 관계 참고 제공 조건: 내부 API 요청 시	X

예제

요청: 액세스 토큰 방식

파라미터
- 친구 목록 필터링 옵션(friend_filter): 없음(none)
- 한 페이지에 가져올 친구의 수(limit)

curl -v -G GET "http://kapi.kakao.com/v1/internal/friends" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "friend_filter=none" \
  -d "limit=3"

요청: 서비스 앱 어드민 키 방식

파라미터
- 친구 목록 필터링 옵션(friend_filter): 없음(none)
- 한 페이지에 가져올 친구의 수(limit)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/friends" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=1376016924426709466" \
  -d "target_id_type=user_id" \
  -d "friend_filter=none" \
  -d "limit=3"

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)
- 친구 목록 필터링 옵션(friend_filter): 생일인 친구(birthday)
- 응답 구성 설정(friend_option): 생일 정보 제공(INCLUDE_BIRTHDAY)
- 생일 조회 기간(birthday_from, birthday_to)

curl -v -G GET "http://kapi.kakao.com/v1/internal/friends" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=81828" \
  -d "target_id_type=account_id" \
  -d "friend_filter=birthday" \
  -d "friend_option=INCLUDE_BIRTHDAY" \
  -d "birthday_from=20240901" \
  -d "birthday_to=20240930"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/friends" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_id=1376016924426709466" \
  -d "target_id_type=user_id" \
  -d "target_app_key=${SERVICE_APP_KEY}"

요청: 위임 방식

파라미터
- 서비스 앱 ID(target_app_id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/friends" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_id=1376016924426709466" \
  -d "target_id_type=user_id" \
  -d "target_app_id=224794"

요청: 위임 방식

파라미터
- 액세스 토큰(target_access_token)

curl -v -G GET 'http://kapi.kakao.com/v1/internal/friends' \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_access_token=${ACCESS_TOKEN}"

응답

// HTTP/1.1 200 OK
{
  "elements": [
    {
      "uuid": "1-bV49r2x_HD-szg0uDU49ruuA",
      "account_id": 1369, // 권한 필요
      "favorite": true,
      "app_registered": false,
      "relation": {
        "talk": "friend",
        "talk_friend_status": 3
      },
      "profile_nickname": "gray",
      "profile_thumbnail_image": "http://th-p.talk.kakao.co.kr/th/talkp/wkamVy1sfN/pOQANi5pAqyMcLlGTk9jW1/1ijegh_110x110_c.jpg",
      "talk_os": "android"
    },
    {
      "id": 1376016924426743837,
      "uuid": "1-XV5dzv2PTM-cr9y-fV59Pk3emA",
      "account_id": 200937, // 권한 필요
      "talk_user_id": 85376, // 권한 필요
      "favorite": false,
      "app_registered": true,
      "relation": {
        "talk": "friend",
        "talk_friend_status": 3
      },
      "profile_nickname": "mj_alpha_g2",
      "profile_thumbnail_image": "",
      "talk_os": "android"
    }
    // ...
  ],
  "total_count": 8,
  "favorite_count": 1,
  "before_url": null,
  "after_url": "http://kapi.kakao.com/v1/internal/friends?limit=3&friend_filter=none&target_id_type=user_id&order=asc&offset=3&target_id=1376016924426709466",
  "result_id": "zbnYtN-AuIy9jb_g0uDU49rusd-w3rvR"
}

응답: 생일 포함

// HTTP/1.1 200 OK
{
  "elements": [
    {
      "profile_nickname": "${FRIEND_NAME}",
      "profile_thumbnail_image": "",
      "talk_os": "android",
      "allowed_msg": true,
      "uuid": "NQQyBzcCOhYkFycRIxc7CTkBMAIyDw",
      "account_id": 165000,
      "app_registered": false,
      "relation": {
        "talk": "friend",
        "talk_friend_status": 3
      },
      "favorite": false,
      "birthday": "20240912"
    }
    // ...
  ],
  "total_count": 2,
  "after_url": null,
  "result_id": "zbnYtN-AsYi8jLWG2evb49Lg0I_thPaC6o7vlsmnzq3GqMmkwZ6u8ZD8kM-ky5Ti1gY",
  "favorite_count": 0
}

인하우스 앱: 채팅방 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/talk/chat/list` 공동체 `https://kapi.kakao.com/v1/internal/talk/chat/list` 외부 `https://kapi.kakao.com/v1/api/talk/chat/list`	액세스 토큰 서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
인하우스 앱 전용	어드민 키 카카오 로그인 활성화 동의항목	필요: 연결	필요: 카카오톡 챗방 목록

사용자 카카오계정에 연결된 카카오톡에서 채팅방 목록을 가져옵니다. 오픈채팅 채팅방 또한 지원합니다.

원하는 인증 정보를 헤더에 담아 GET으로 요청하고, 성공 시 채팅방 목록을 받습니다. 외부용 API는 헤더에 액세스 토큰 인증 방식만 지원합니다.

응답의 채팅방의 이름 및 이미지는 아래와 같은 기준을 적용합니다.

채팅방에 이름 및 이미지를 설정한 경우, 사용자가 카카오톡 클라이언트에서 설정한 이름과 동기화되어 제공
채팅방에 이름을 설정하지 않은 경우
- 1:1 채팅방: 대화 상대가 직접 설정한 닉네임으로 채팅방 이름을 대체해 제공
- 그룹 채팅방: 채팅방 멤버를 카카오톡 회원번호를 기준으로 정렬한 뒤, 그중 상위 5명 멤버의 닉네임을 쉼표(,)로 구분해 조합한 문자열로 채팅방 이름을 대체해 제공, 각 멤버가 직접 설정한 닉네임 사용
채팅방에 이미지를 설정하지 않은 경우
- 응답에 채팅방 이미지(image_url) 제공하지 않음
- 멤버들의 썸네일 이미지 목록(display_member_images)을 토대로 직접 구성해야 함
일부 응답에 멀티프로필 적용
- 채팅방 이름(title): title_source가 별도 설정 없음(default)인 경우, 요청 사용자(target_id)를 기준으로 멤버들의 멀티프로필 닉네임 적용
- 멤버 이미지(display_member_images): 멤버들의 썸네일 이미지 조합으로써 요청 사용자(target_id)를 기준으로 멀티프로필 썸네일 이미지 적용

요청: 액세스 토큰 방식

헤더

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

쿼리 파라미터

이름	타입	설명	필수
filter	`String`	원하는 결과 타입 필터 미지정 시 보유 권한에 따라 조회 가능한 범위의 전체 채팅방 목록 제공, 아래 중 하나 `open`: 오픈채팅방 `regular`: 일반 채팅방 `multi`: 그룹 채팅방 `direct`: 1:1 채팅방 쉼표(",")를 구분자로 다중 선택 가능 (예: 일반 그룹 채팅방 요청 시 "regular,multi")	X
offset	`Integer`	가져올 채팅방 목록의 시작 지점	X
limit	`Integer`	한 페이지에 가져올 채팅방 수(기본값: `20`, 최대: `20`)	X
page_order	`String`	채팅방 목록 정렬 방법, 아래 중 하나 `asc`: 오름차순 `desc`: 내림차순 (기본값: `asc`)	X

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

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

쿼리 파라미터

이름	타입	설명	필수
target_id	`String`	카카오톡 채팅방 목록을 가져올 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
filter	`String`	원하는 결과 타입 필터 미지정 시 보유 권한에 따라 조회 가능한 범위의 전체 채팅방 목록 제공, 아래 중 하나 `open`: 오픈채팅방 `regular`: 일반 채팅방 `multi`: 그룹 채팅방 `direct`: 1:1 채팅방 쉼표(",")를 구분자로 다중 선택 가능 (예: 일반 그룹 채팅방 요청 시 "regular,multi")	X
offset	`Integer`	가져올 채팅방 목록의 시작 지점	X
limit	`Integer`	한 페이지에 가져올 채팅방 수(기본값: `20`, 최대: `20`)	X
page_order	`String`	채팅방 목록 정렬 방법, 아래 중 하나 `asc`: 오름차순 `desc`: 내림차순 (기본값: `asc`)	X

응답

본문

이름	타입	설명	필수
elements	`ChatInfo[]`	각 채팅방 정보로 구성된 목록	X
total_count	`Integer`	전체 채팅방 수	O
before_url	`String`	채팅방 목록 현재 페이지의 이전 페이지 URL	X
after_url	`String`	채팅방 목록 현재 페이지의 다음 페이지 URL	X

ChatInfo

이름	타입	설명	필수
id	`Long`	채팅방 ID	O
title	`String`	채팅방 이름	X
title_source	`String`	채팅방 이름 타입, 아래 중 하나 `user`: 사용자가 설정한 이름 `chat`: 채팅방 생성 시 설정된 이름 `default`: 별도 설정 없음	O
image_url	`String`	채팅방 이미지 채팅방에 지정된 이미지가 없어 응답에 포함되지 않은 경우 `display_member_images`를 참조할 것	X
member_count	`Integer`	채팅방 멤버 수	X
display_member_images	`String[]`	채팅방 멤버 중 최대 5명의 썸네일 이미지 목록 중요: 멤버의 프로필이 존재하지 않을 경우 응답에 포함되지 않을 수 있음	X
chat_room_type	`String`	채팅방 타입, 아래 중 하나 `MemoChat`: 나와의 채팅방 `DirectChat`: 다른 사용자와의 1:1 채팅방 `MultiChat`: 다른 사용자들과의 그룹 채팅방 `OpenDirectChat`: 1:1 오픈채팅방 `OpenMultiChat`: 그룹 오픈채팅방	O
direct_chat_talk_user_id	`Long`	1:1 채팅방의 상대방 카카오톡 회원번호 중요: `chat_room_type`이 `DirectChat`이며, 별도 응답 권한을 보유한 경우에만 응답에 포함	X
unread_message_count	`Integer`	읽지 않은 메시지 수 읽지 않은 채팅방 목록 조회 호출 시에만 포함	X

* chat_type: Deprecated, chat_room_type으로 변경

예제

요청: 액세스 토큰 방식

파라미터
- 채팅방 타입 필터(filter): 그룹 채팅방(multi)
- 한 페이지에 가져올 채팅방 수(limit)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/chat/list" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "limit=5" \
  -d "filter=multi"

요청: 액세스 토큰 방식

외부 API로 요청
파라미터
- 한 페이지에 가져올 채팅방 수(limit)

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

요청: 액세스 토큰 방식

외부 API로 요청
파라미터
- 한 페이지에 가져올 채팅방 수(limit)
- 채팅방 타입 필터(filter): 일반 그룹 채팅방(regular,multi)

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/chat/list" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "limit=5" \
  -d "filter=regular,multi"

요청: 액세스 토큰 방식

외부 API로 요청
파라미터
- 한 페이지에 가져올 채팅방 수(limit)
- 채팅방 타입 필터(filter): 그룹 채팅방(multi)

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/chat/list" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "limit=5" \
  -d "filter=multi"

요청: 서비스 앱 어드민 키 방식

파라미터
- 채팅방 타입 필터(filter): 그룹 채팅방(multi)
- 한 페이지에 가져올 채팅방 수(limit)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/chat/list" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "limit=5" \
  -d "filter=multi" \
  -d "target_id=1376016924426684995" \
  -d "target_id_type=user_id"

응답: 권한 및 동의항목 미설정으로 요청 실패

{
  "msg": "${APP_NAME} App disabled [talk_chats] scopes for [TALK_CHAT_LIST] API on developers.kakao.com. Enable it first.",
  "code": -3
}

응답: 일반 채팅방 조회 권한이 있는 경우

{
  "elements": [
    {
      "id": 355354313646591,
      "title": "1:1 채팅방",
      "member_count": 2,
      "display_member_images": [],
      "chat_room_type": "DirectChat",
      "title_source": "default"
    },
    {
      "id": 88604424245226298,
      "title": "그룹 채팅방",
      "member_count": 26,
      "image_url": "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/kLyxKPKmDeCMcuigHqPN70/1p1vfb_110x110_c.jpg",
      "display_member_images": [
        "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/CCCXXX.jpg",
        "http://th-gp.talk.kakao.com/th/talkp/wkislpHYlg/DDDXXX.jpg"
        // ...
      ],
      "chat_room_type": "MultiChat"
    },
    {
      "id": 18319587582148530,
      "title": "오픈채팅방",
      "member_count": 2,
      "display_member_images": [],
      "chat_room_type": "OpenMultiChat",
      "title_source": "default"
    }
    // ...
  ],
  "total_count": 20,
  "after_url": "http://kapi.kakao.com/v1/internal/talk/chat/list?offset=5&limit=5&order=asc"
}

응답: 일반 채팅방 조회 권한이 없는 경우, 오픈채팅방 목록

{
  "elements": [
    {
      "id": 18303808341566691,
      "title": "길드오픈채팅방",
      "image_url": "",
      "member_count": 25,
      "display_member_images": [],
      "chat_room_type": "OpenMultiChat",
      "title_source": "default"
    },
    {
      "id": 18284593369904501,
      "title": "주민모임",
      "member_count": 17,
      "display_member_images": [],
      "chat_room_type": "OpenMultiChat",
      "title_source": "default"
    },
    {
      "id": 18306267450224920,
      "title": "고양이집사들",
      "member_count": 6,
      "display_member_images": [],
      "chat_room_type": "OpenMultiChat",
      "title_source": "default"
    }
  ],
  "total_count": 4,
  "after_url": null
}

인하우스 앱: 채팅방 정보 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/talk/chat_info` 공동체 `https://kapi.kakao.com/v1/internal/talk/chat_info` 외부 `https://kapi.kakao.com/v1/api/talk/chat_info`	액세스 토큰 서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
인하우스 앱 전용	어드민 키 카카오 로그인 활성화 동의항목	필요: 연결	필요: 카카오톡 챗방 목록

사용자 카카오계정에 연결된 카카오톡에서 채팅방 정보를 가져옵니다. 오픈채팅 채팅방 또한 지원합니다.

원하는 인증 정보를 헤더에 담아 GET으로 요청하고, 성공 시 채팅방 정보를 받습니다. 외부용 API는 헤더에 액세스 토큰 인증 방식만 지원합니다.

응답의 채팅방의 이름 및 이미지는 인하우스 앱: 채팅방 목록 조회 API의 내용을 참고합니다.

요청: 액세스 토큰 방식

헤더

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

쿼리 파라미터

이름	타입	설명	필수
chat_id	`Long`	채팅방 정보를 가져올 채팅방 ID	O

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

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

쿼리 파라미터

이름	타입	설명	필수
target_id	`String`	카카오톡 채팅방 목록을 가져올 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
chat_id	`Long`	채팅방 정보를 가져올 채팅방 ID	O

응답

이름	타입	설명	필수
id	`Long`	채팅방 ID	O
title	`String`	채팅방 이름	X
title_source	`String`	채팅방 이름 타입, 아래 중 하나 `user`: 사용자가 설정한 이름 `chat`: 채팅방 생성 시 설정된 이름 `default`: 별도 설정 없음	O
image_url	`String`	채팅방 이미지 채팅방에 지정된 이미지가 없어 응답에 포함되지 않은 경우 `display_member_images`를 참조할 것	X
member_count	`Integer`	채팅방 멤버 수	X
display_member_images	`String[]`	채팅방 멤버 중 최대 5명의 썸네일 이미지 목록 중요: 멤버의 프로필이 존재하지 않을 경우 응답에 포함되지 않을 수 있음	X
chat_room_type	`String`	채팅방 타입, 아래 중 하나 `MemoChat`: 나와의 채팅방 `DirectChat`: 다른 사용자와의 1:1 채팅방 `MultiChat`: 다른 사용자들과의 그룹 채팅방 `OpenDirectChat`: 1:1 오픈채팅방 `OpenMultiChat`: 그룹 오픈채팅방	O
direct_chat_talk_user_id	`Long`	1:1 채팅방의 상대방 카카오톡 회원번호 중요: `chat_room_type`이 `DirectChat`이며, 별도 응답 권한을 보유한 경우에만 응답에 포함	X

예제

요청: 액세스 토큰 방식

파라미터
- 채팅방 정보를 가져올 채팅방 ID(chat_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/chat_info" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "chat_id=${CHAT_ID}"

요청: 서비스 앱 어드민 키 방식

외부 API로 요청
파라미터
- 채팅방 정보를 가져올 채팅방 ID(chat_id)

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/chat_info" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=1376016924426684995" \
  -d "target_id_type=user_id" \
  -d "chat_id=${CHAT_ID}"

응답

{
    "id": 355354313646591,
    "title": "1:1 채팅방",
    "member_count": 2,
    "display_member_images": [],
    "chat_room_type": "DirectChat",
    "title_source": "default"
},

인하우스 앱: 채팅방 멤버 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/talk/members` 공동체 `https://kapi.kakao.com/v1/internal/talk/members` 외부 `https://kapi.kakao.com/v1/api/talk/members`	액세스 토큰 서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
인하우스 앱 전용	어드민 키 카카오 로그인 활성화 동의항목	필요: 연결	필요: 카카오톡 챗방 목록

사용자 카카오계정과 연결된 카카오톡에서 특정 채팅방의 멤버 목록을 가져옵니다.

원하는 인증 정보를 헤더에 담아 GET으로 요청하고, 성공 시 해당 카카오톡 채팅방의 멤버 정보 목록을 받습니다. 멤버 닉네임은 각 멤버가 직접 설정한 닉네임을 제공합니다. 응답 중 카카오계정 ID(account_id), 카카오톡 회원번호(talk_id)는 권한이 있는 앱에서 내부 API로 요청한 경우에만 응답에 포함됩니다.

요청: 액세스 토큰 방식

헤더

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

쿼리 파라미터

이름	타입	설명	필수
chat_id	`Long`	멤버 목록을 가져올 채팅방 ID	O
token	`Long`	요청에 대한 토큰(Token) 정보 첫 요청 시 값이 발급되어 응답에 포함 기본값일 경우 모든 채팅방 멤버 정보가 응답에 포함되며, 기본값이 아닌 토큰 값을 전달할 경우 해당 토큰 발생 시점 이후 변경된 정보만 응답에 포함(기본값: 0)	X
friends_only	`Boolean`	카카오톡 친구인 멤버 정보만 받을지 필터링 여부(기본값: `false`)	X
include_profile	`Boolean`	멤버의 프로필 포함 여부(기본값: `true`)	X

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

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

쿼리 파라미터

이름	타입	설명	필수
chat_id	`Long`	멤버 목록을 가져올 채팅방 ID	O
target_id	`String`	멤버 목록을 가져올 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
token	`Long`	요청에 대한 토큰(Token) 정보 첫 요청 시 값이 발급되어 응답에 포함 기본값일 경우 모든 채팅방 멤버 정보가 응답에 포함되며, 기본값이 아닌 토큰이 발행된 후에는 해당 시점 이후 변경된 정보만 응답에 포함(기본값: 0)	X
friends_only	`Boolean`	카카오톡 친구인 멤버 정보만 받을지 필터링 여부(기본값: `false`)	X
include_profile	`Boolean`	멤버의 프로필 포함 여부(기본값: `true`)	X

응답

본문

이름	타입	설명	필수
type	`String`	해당 채팅방의 타입, 아래 중 하나 `DirectChat`: 1:1 채팅방 `MultiChat`: 그룹 채팅방	X
members	`InhouseMemberInfo[]`	해당 채팅방에 참여 중인 멤버 정보로 구성된 목록 액세스 토큰 또는 `target_id`에 해당하는 사용자 자신의 정보를 포함하지 않음	X
token	`Long`	요청에 대한 토큰(Token) 정보 첫 요청 시 값이 발급되어 응답에 포함 기본값일 경우 모든 채팅방 멤버 정보가 응답에 포함되며, 아래 요청 시 기본값이 아닌 토큰 값을 전달할 경우 해당 토큰 발생 시점 이후 변경된 정보만 응답에 포함(기본값: 0)	X
active_members_count	`Integer`	채팅방 멤버 수	X
active_friends_count	`Integer`	채팅방 멤버 중 카카오톡 친구의 수 제공 조건: 요청 시 `friends_only` 파라미터를 `true`로 지정한 경우	X

InhouseMemberInfo

이름	타입	설명	필수
id	`Long`	회원번호(User ID)	X
uuid	`String`	해당 앱에서의 사용자 고유 아이디, 연결 상태와 무관하며 일반적으로 메시지 전송 시 사용	O
account_id	`Integer`	카카오계정 ID, 카카오톡에 연결된 카카오계정의 ID 제공 조건: 카카오계정 ID 응답 권한 보유, 내부 API 요청	X
talk_id	`Long`	카카오톡 회원번호 제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유, 내부 API 요청	X
app_registered	`Boolean`	앱 연결 여부	X
nickname	`String`	닉네임	X
thumbnail_image	`String`	썸네일 이미지 참고: 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리	X

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

예제

요청: 액세스 토큰 방식

파라미터
- 채팅방 ID(chat_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/members" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "chat_id=114019701633311"

요청: 서비스 앱 어드민 키 방식

파라미터
- 채팅방 ID(chat_id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/members" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "chat_id=114019701633311" \
  -d "target_id=1376016924426684995" \
  -d "target_id_type=user_id"

요청: 서비스 앱 어드민 키 방식

파라미터
- 채팅방 ID(chat_id)
- 토큰(token)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/members" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "chat_id=114019701633311" \
  -d "token=1438176349000" \
  -d "target_id=1376016924426684995" \
  -d "target_id_type=user_id"

응답

{
  "type": "MultiChat",
  "members": [
    {
      "uuid": "eEp6SnNAd1tjVmVSZEh6S3hOdkMO",
      "account_id": 200937, // 권한 필요
      "talk_id": 85376 // 권한 필요
    },
    {
      "uuid": "eE92TmJQY1JmUn5MfU54QHU3",
      "account_id": 798, // 권한 필요
      "talk_id": 23144 // 권한 필요
    },
    {
      "uuid": "eEhkV2BZbVh0RndEckp_Rg",
      "talk_id": 37945 // 권한 필요
    },
    {
      "id": 1376016924426684995,
      "uuid": "eEp6Sn9OfVFiUmNUZ0t5SHtNdUAQ",
      "account_id": 200513, // 권한 필요
      "talk_id": 30173 // 권한 필요
    }
  ],
  "token": 1438176349000
}

응답

{
  "active_members_count": 4,
  "active_friends_count": 3,
  "members": [
    {
      "account_id": 1393284, // 권한 필요
      "app_registered": false,
      "nickname": "무지",
      "thumbnail_image": "",
      "uuid": "soOwibqIsISon6-fr52snqeXu4y5i7mMudI"
    },
    {
      "account_id": 787573, // 권한 필요
      "app_registered": false,
      "nickname": "프로도",
      "thumbnail_image": "http://th-p.talk.kakao.co.kr/th/talkp/wkaLcfXVXV/X6GJpmqkTwkPNgPY41S231/8vifdm_110x110_c.jpg",
      "uuid": "soW9ir-Iu5egkKCQoJKrnqmFsoe1h7KH3A"
    },
    {
      "account_id": 371878, // 권한 필요
      "app_registered": false,
      "nickname": "콘",
      "thumbnail_image": "http://th-p.talk.kakao.co.kr/th/talkp/wkaIzbfDmC/j3FmaOYQtHZp7kPmfkApkK/ux2keu_110x110_c.jpg",
      "uuid": "soG2h7-IsJykkaSVpYm-i7mLvovb"
    }
  ],
  "token": 1533541416000,
  "type": "MultiChat"
}

응답

{
  "type": "MultiChat",
  "members": [],
  "token": 1438176349000
}

응답: 대상 채팅방 없음

{
  "code": -2,
  "msg": "chat(or link) not found"
}

멜론: 카카오톡 프로필 뮤직에 곡 추가

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v1/internal/talk/profile/add/music` 공동체 `https://kapi.kakao.com/v1/internal/talk/profile/add/music`	액세스 토큰 서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
멜론, 헤이카카오 전용	어드민 키 카카오 로그인 활성화 동의항목	필요: 연결	필요: 카카오톡 프로필(홈) 공유

사용자의 카카오톡 프로필 뮤직에 멜론의 특정 곡을 추가합니다. 카카오톡 프로필 뮤직은 최대 30곡까지 추가할 수 있습니다. 이미 추가된 곡에 대해 요청한 경우, 뮤직 리스트의 최상단으로 위치시킵니다.

이 API를 사용하려면 앱에 [카카오톡 프로필(홈) 공유(talk_profile_home)] 동의항목 설정이 필요하고, 요청 대상 사용자가 해당 동의항목에 동의한 상태여야 합니다.

원하는 인증 정보를 헤더에 담아 POST로 요청합니다. 요청 시 카카오톡 프로필 뮤직에 추가할 곡의 ID를 전달해야 합니다. 요청 성공 시 응답으로 사용자의 회원번호를 받습니다. 사용자가 필요한 동의항목에 동의하지 않은 경우, -402 에러 코드가 반환됩니다.

요청: 액세스 토큰 방식

헤더

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

본문

이름	타입	설명	필수
song_id	`Long`	카카오톡 프로필 뮤직에 추가할 곡 ID	O

요청: 서비스 앱 어드민 키 방식

헤더

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

본문

이름	타입	설명	필수
target_id	`String`	사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
song_id	`Long`	카카오톡 프로필 뮤직에 추가할 곡 ID	O

응답

본문

이름	타입	설명	필수
id	`Long`	사용자 회원번호	O

예제 (#add-talk-profile-music-sample)

요청: 액세스 토큰 방식

파라미터
- 카카오톡 프로필 뮤직에 추가할 곡 ID

curl -v -X POST "http://kapi.kakao.com/v1/internal/talk/profile/add/music" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "song_id=1883446"

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)
- 카카오톡 프로필 뮤직에 추가할 곡 ID

curl -v -X POST "http://kapi.kakao.com/v1/internal/talk/profile/add/music" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=208120" \
  -d "target_id_type=user_id" \
  -d "song_id=1883446"

응답

// HTTP/ 1.1 200 OK
{
  "id": 142452
}

응답: 실패, 사용자가 필요한 동의항목에 동의하지 않음

// HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_PROFILE_ADD_MUSIC",
  "required_scopes": ["talk_profile_home"],
  "allowed_scopes": ["birthday", "talk_message", "gender", "birthyear", "is_kakaotalk_user", "friends", "age_range", "account_email", "profile_image", "profile_nickname", "name", "phone_number", "shipping_address"]
}

사이드 메뉴

오픈 문서

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

인공지능

플랫폼 API

API 제공

전용 API

어드민 API

더 보기

REST API

카카오톡 프로필 조회

기본 정보

요청: 액세스 토큰 방식

헤더

요청: 서비스 앱 어드민 키 방식

헤더

쿼리 파라미터

요청: 위임 방식

헤더

쿼리 파라미터

응답

본문

예제

요청: 액세스 토큰 방식

요청: 서비스 앱 어드민 키 방식

요청: 위임 방식

요청: 위임 방식

요청: 위임 방식

응답

응답, 사용자가 닉네임 동의항목만 동의한 경우

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

기본 정보

요청: 서비스 앱 어드민 키 방식

헤더

쿼리 파라미터

요청: 위임 방식

헤더

쿼리 파라미터

응답

본문

TalkProfileInfo

예제

요청: 서비스 앱 어드민 키 방식

요청: 위임 방식

응답: viewer_id를 전달한 경우

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

응답: 일부 사용자 프로필 조회에 실패한 경우

응답: 모든 사용자 프로필 조회에 실패한 경우

카카오톡 친구 목록 조회

기본 정보

요청: 액세스 토큰 방식

헤더

쿼리 파라미터

요청: 서비스 앱 어드민 키 방식

헤더

쿼리 파라미터

요청: 위임 방식

헤더

본문

응답

본문

Friend

예제

요청: 액세스 토큰 방식

요청: 서비스 앱 어드민 키 방식

요청: 위임 방식

요청: 위임 방식

요청: 위임 방식

응답

응답: 일부 친구가 목록에 포함되지 않은 경우

응답: 닉네임 동의항목만 필수 설정했거나, 친구가 닉네임에만 동의한 경우

읽지 않은 채팅방 목록 조회

기본 정보

요청: 액세스 토큰 방식

헤더

쿼리 파라미터

요청: 서비스 앱 어드민 키 방식