카카오톡 채널

이 문서는 기존 버전의 카카오톡 채널 REST API 사용 방법을 안내합니다.

카카오톡 채널 관계 확인하기

기본 정보

메서드	URL	인증 방식
GET	https://kapi.kakao.com/v1/api/talk/channels	액세스 토큰 서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	사용자 동의
필요: 동의항목	플랫폼 등록 카카오 로그인 활성화 동의항목 카카오톡 채널 연결	필요	필요: 카카오톡 채널 추가 상태 및 내역

현재 로그인한 사용자와 앱에 연결된 카카오톡 채널의 친구 관계를 확인합니다.

사용자 액세스 토큰(Access Token)을 헤더에 담아 GET으로 요청합니다. 서비스 서버에서 관리자가 요청할 경우, 앱별 어드민 키(Admin Key)로 특정 사용자의 카카오톡 채널 관계를 확인할 수 있습니다. 어드민 키는 보안에 유의해야 하므로 서버에서의 호출 시에만 사용해야 합니다.

특정 카카오톡 채널의 정보만 받아보려면 channel_public_ids 파라미터로 해당 카카오톡 채널의 프로필 ID를 지정하여 요청합니다.

응답은 JSON 형식이며 사용자가 추가 또는 차단한 카카오톡 채널 중, 서비스 앱과 연결된 카카오톡 채널에 한해 정보를 제공합니다. 응답의 각 카카오톡 채널 정보는 사용자와 카카오톡 채널의 현재 추가 상태, 변경 시점과 같은 자세한 정보를 포함합니다.

사용자가 [카카오톡 채널 추가 상태 및 내역] 동의항목에 동의하지 않아 에러 응답을 받았을 경우, 추가 항목 동의 받기 기능을 사용해 사용자에게 다시 동의를 요청할 수 있습니다.

요청: 액세스 토큰 방식

헤더

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

쿼리 파라미터

이름	타입	설명	필수
channel_public_ids	String[]	사용자와의 친구 관계를 확인할 카카오톡 채널의 프로필 ID 목록 참고: 카카오톡 채널 프로필 ID 확인 방법	X

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

헤더

이름	설명	필수
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
target_id_type	String	사용자 ID 타입, user_id로 고정	O
target_id	String	회원번호	O
channel_public_ids	String[]	사용자와의 친구 관계를 확인할 카카오톡 채널의 프로필 ID 목록 (기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록) 참고: 카카오톡 채널 프로필 ID 확인 방법	X

응답

본문

이름	타입	설명	필수
user_id	Long	회원번호	O
channels	Channels[]	카카오톡 채널 정보	X

Channels

이름	타입	설명	필수
channel_uuid	String	카카오톡 채널의 검색용 ID	O
channel_public_id	String	카카오톡 채널 프로필 ID	O
relation	String	카카오톡 채널과 사용자 관계 ADDED: 카카오톡 채널이 추가된 상태 BLOCKED: 카카오톡 채널이 차단된 상태 NONE: 카카오톡 채널이 추가되거나 차단된 적 없는 상태	O
created_at	Datetime	카카오톡 채널 추가 시간, UTC* 카카오톡 채널이 추가(ADDED) 상태인 경우만 포함	X
updated_at	Datetime	카카오톡 채널 상태 변경 시간, UTC* 카카오톡 채널이 추가(ADDED) 또는 차단(BLOCKED)된 상태일 경우만 포함	X

* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고

예제

요청: 액세스 토큰 방식

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/channels" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data-urlencode 'channel_public_ids=["_frxjem","_xnrxjem","_Brxjem"]'

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

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/channels" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=${USER_ID}" \
    --data-urlencode 'channel_public_ids=["_frxjem","_xnrxjem","_Brxjem"]'

응답: 성공

HTTP/1.1 200 OK
{
  "user_id": 1111111,
  "channels": [
    {
      "channel_uuid": "@테스트",
      "channel_public_id": "_ZeUTxl",
      "relation": "ADDED", // ADDED, BLOCKED, NONE 중 하나
      "created_at": "2020-04-18T03:17:05Z", // ADDED 상태일 때만 존재
      "updated_at": "2021-05-17T05:25:01Z" // ADDED, BLOCKED 상태일 때만 존재
    },
    ...
  ]
}

응답: 실패, 카카오톡 미사용자를 대상으로 요청한 경우

HTTP/1.1 400 Bad Request
{
    "msg": "given account is not connected to any talk user.",
    "code": -501
}