REST API
이 문서는 REST API를 이용하여 카카오톡 채널 관계 조회 및 카카오톡 채널 고객 관리 기능을 구현하는 방법을 안내합니다.

카카오톡 채널 관계 조회
기본 정보
메서드	URL	인증 방식
GET	https://kapi.kakao.com/v2/api/talk/channels	액세스 토큰
서비스 앱 어드민 키
권한	사전 설정	카카오 로그인	동의항목
필요: 동의항목	어드민 키
카카오 로그인 활성화
동의항목
앱에 카카오톡 채널 연결	필요	필요:
카카오톡 채널 추가 상태 및 내역

신규 API 제공 안내
카카오톡 채널 관계 조회 API가 v2 버전으로 업그레이드되었습니다. 기존 API 정보는 별도 문서에서 확인할 수 있습니다.

참고
사용자가 서비스와 연결된 카카오톡 채널을 추가 또는 차단했을 때 알림을 받으려면 카카오톡 채널 웹훅을 사용합니다.

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

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

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

요청 성공 시 응답은 서비스 앱과 연결된 카카오톡 채널과 사용자의 관계 정보를 제공합니다. 각 카카오톡 채널 정보는 사용자와 카카오톡 채널의 현재 관계, 변경 시점과 같은 자세한 정보를 포함합니다.

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

요청: 액세스 토큰 방식
헤더
이름	설명	필수
Authorization	Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청	O
쿼리 파라미터
이름	타입	설명	필수
channel_ids	String	사용자와의 친구 관계를 확인할 카카오톡 채널 프로필 ID 목록
쉼표로 구분된 하나의 문자열로 전달
(예: _Bxkd,_RQxl,_vxfxm, 기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록)

참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	String	카카오톡 채널 ID 타입, channel_public_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	회원번호	O
target_id_type	String	사용자 ID 타입, user_id로 고정	O
channel_ids	String	사용자와의 친구 관계를 확인할 카카오톡 채널 프로필 ID 목록
쉼표로 구분된 하나의 문자열로 전달
(예: _Bxkd,_RQxl,_vxfxm, 기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록)

참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	String	카카오톡 채널 ID 타입, channel_public_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/v2/api/talk/channels" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "channel_ids=_frxjem,_xnrxjem,_Brxjem"
요청: 서비스 앱 어드민 키 방식
curl -v -G GET "https://kapi.kakao.com/v2/api/talk/channels" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=${USER_ID}" \
    -d "channel_ids=_frxjem,_xnrxjem,_Brxjem"
응답: 성공
HTTP/1.1 200 OK
{
  "user_id": ${USER_ID},
  "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
}
여러 사용자 카카오톡 채널 관계 조회
기본 정보
메서드	URL	인증 방식
GET	https://kapi.kakao.com/v2/api/talk/channels/multi	서비스 앱 어드민 키
권한	사전 설정	카카오 로그인	동의항목
필요: 동의항목	어드민 키
카카오 로그인 활성화
동의항목
앱에 카카오톡 채널 연결	필요	필요:
카카오톡 채널 추가 상태 및 내역

참고
사용자가 서비스와 연결된 카카오톡 채널을 추가 또는 차단했을 때 알림을 받으려면 카카오톡 채널 웹훅을 사용합니다.

앱에 연결된 카카오톡 채널과 여러 사용자의 친구 관계를 확인합니다. 전체 또는 그룹 단위의 사용자를 대상으로 특정 카카오톡 채널과의 친구 관계를 확인하는 데 사용합니다.

서비스 앱 어드민 키를 헤더에 담아 GET으로 요청합니다. 사용자 회원번호 목록, 카카오톡 채널 프로필 ID 목록을 쿼리 파라미터로 전달해야 합니다. 한 번에 최대 200명의 사용자를 대상으로 요청 가능합니다.

요청 처리 성공 시 응답은 각 사용자의 카카오톡 채널별 친구 관계 목록을 포함합니다. 확인에 실패한 사용자의 정보는 응답에서 제외됩니다.

요청
헤더
이름	설명	필수
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입	O
쿼리 파라미터
이름	타입	설명	필수
target_ids	String	회원번호 목록, 쉼표로 구분된 하나의 문자열로 구성	O
target_id_type	String	사용자 ID 타입, user_id로 고정	O
channel_ids	String[]	사용자와의 친구 관계를 확인할 카카오톡 채널의 프로필 ID 목록, 쉼표로 구분된 하나의 문자열로 구성
(예: _Bxkd,_RQxl,_vxfxm, 기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록)

참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	String	카카오톡 채널 ID 타입, channel_public_id로 고정	X
응답
본문
이름	타입	설명	필수
-	TalkChannelsResult[]	각 사용자의 카카오톡 채널별 친구 관계 목록	O
TalkChannelsResult
이름	타입	설명	필수
user_id	Long	회원번호	O
channels	TalkChannelRelation[]	각 카카오톡 채널과 사용자의 관계 정보	X
TalkChannelRelation
이름	타입	설명	필수
channel_public_id	String	카카오톡 채널 프로필 ID	O
channel_uuid	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/v2/api/talk/channels/multi" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_ids=${USER_ID_1},${USER_ID_2},${USER_ID_3}" \
    --data-urlencode 'channel_ids=_frxjem,_xnrxjem,_Brxjem'
응답
HTTP/1.1 200 OK
[
    {
        "user_id": ${USER_ID_1},
        "channels": [
            {
                "channel_public_id": "_xnrxjem",
                "channel_uuid": "@플러스친구",
                "relation": "ADDED",
                "created_at": "2022-11-09T07:08:48Z",
                "updated_at": "2023-07-20T07:21:05Z"
            }
        ]
    }, {
        "user_id": ${USER_ID_2},
        "channels": [
            {
                "channel_public_id": "_xnrxjem",
                "channel_uuid": "@플러스친구",
                "relation": "NONE"
            }
        ]
    },
    ...
]
응답: 확인에 실패한 사용자 제외
HTTP/1.1 200 OK
[
    {
        "user_id": ${USER_ID_1},
        "channels": [
            {
                "channel_public_id": "_xnrxjem",
                "channel_uuid": "@플러스친구",
                "relation": "ADDED",
                "created_at": "2022-11-09T07:08:48Z",
                "updated_at": "2023-07-20T07:21:05Z"
            }
        ]
    }
]
고객 관리: 고객파일 등록
기본 정보
메서드	URL	인증 방식
POST	https://kapi.kakao.com/v1/talkchannel/create/target_user_file	REST API 키
서비스 앱 어드민 키
권한	사전 설정	카카오 로그인	동의항목
-	REST API 키
어드민 키
고객 관리 API 정책 동의	-	-

새로운 고객파일을 만듭니다. 새 파일 이름은 file_name, 적용할 필터링 기준은 schema에 각각 정의합니다. 한 번 정의한 스키마(Schema)는 수정할 수 없으니 주의합니다.

새 고객파일을 만드는 데 성공하면 file_id 값으로 등록된 파일 ID가 반환됩니다. 파일 ID는 해당 파일에 사용자를 추가하거나 제외할 때 사용합니다.

제약 사항: 스키마
카카오톡 채널 고객 관리 API를 이용하여 고객파일을 등록할 경우, 반드시 지정된 스키마 규칙을 따라야 합니다.

고객의 데이터가 문자열(String)인 경우, 지원하는 키만 사용 가능
생년월일, 국가, 지역, 성별, 연령, 구매금액, 포인트, 가입일, 최근 구매일, 응모일
새로운 키 추가 시 "앱유저아이디" 또는 "전화번호" 키 사용 불가, 키에 해당하는 값은 숫자(Number) 자료형만 허용
스키마는 최대 30개 항목 포함 가능
요청
헤더
이름	설명	필수
Authorization	Authorization: KakaoAK ${APP_KEY}
인증 방식, REST API 키 또는 서비스 앱 어드민 키로 인증 요청	O
본문
이름	타입	설명	필수
channel_public_id	String	카카오톡 채널 프로필 ID

참고: 카카오톡 채널 프로필 ID 확인 방법	O
schema	JSON	고객파일에 등록되는 데이터 항목과 항목의 종류를 정의
키(Key)와 값(Value)의 JSON 자료형(Type)으로 구성
키: 생년월일, 국가, 지역, 성별, 연령, 구매금액, 포인트, 가입일, 최근 구매일, 응모일
값의 자료형: String 또는 Number	O
file_name	String	관리할 파일의 이름	O
응답
본문
이름	타입	설명
file_id	Integer	등록된 고객파일 ID
예제
요청
curl -v -X POST "https://kapi.kakao.com/v1/talkchannel/create/target_user_file" \
    -H "Authorization: KakaoAK ${APP_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
            "channel_public_id": "_ZeUTxl",
            "file_name": "vip고객리스트",
            "schema":{
                "생년월일":"string",
                "성별":"string",
                "연령":"number"
        }
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "file_id" : 437
}
고객 관리: 고객파일 조회
기본 정보
메서드	URL	인증 방식
GET	https://kapi.kakao.com/v1/talkchannel/target_user_file	REST API 키
서비스 앱 어드민 키
권한	사전 설정	카카오 로그인	동의항목
-	REST API 키
어드민 키
고객 관리 API 정책 동의	-	-

카카오톡 채널에 등록된 고객파일 정보들을 확인합니다. 어떤 카카오톡 채널에 등록된 파일 정보들을 알고 싶은지 channel_public_id 파라미터의 값을 명시하여 요청합니다. 요청 성공 시 해당 카카오톡 채널에 등록된 고객파일들의 정보를 받습니다.

요청
헤더
이름	설명	필수
Authorization	Authorization: KakaoAK ${APP_KEY}
인증 방식, REST API 키 또는 서비스 앱 어드민 키로 인증 요청	O
쿼리 파라미터
이름	타입	설명	필수
channel_public_id	String	카카오톡 채널 프로필 ID

참고: 카카오톡 채널 프로필 ID 확인 방법	O
응답
본문
이름	타입	설명
empty_slot	Integer	사용 가능한 슬롯 수
using_slot	Integer	사용 중인 슬롯 수
results	Results[]	카카오톡 채널에 등록된 고객파일들의 정보
Results
이름	타입	설명
file_id	Integer	파일 ID
file_name	String	파일 이름
status	String	파일 상태
using, deleting, failed 중 하나
update_at	String	파일이 업로드 된 시간
schema	JSON	파일에 등록된 데이터 항목과 항목의 종류
예제
요청
curl -v -G GET "https://kapi.kakao.com/v1/talkchannel/target_user_file" \
    -H "Authorization: KakaoAK ${APP_KEY}" \
    -d "channel_public_id=_ZeUTxl"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "empty_slot":27,
  "using_slot":3,
  "results":[
    {
      "file_id":437,
      "file_name": "vip고객리스트",
      "status":"USING",
      "update_at":"2019-02-03 13:22:33",
      "schema": "{\"생년월일\":\"string\",\"성별\":\"string\",\"age\":\"number\"}"
    },
    ...
  ]
  
}
고객 관리: 고객파일에 사용자 추가
기본 정보
메서드	URL	인증 방식
POST	https://kapi.kakao.com/v1/talkchannel/update/target_users	REST API 키
서비스 앱 어드민 키
권한	사전 설정	카카오 로그인	동의항목
-	REST API 키
어드민 키
고객 관리 API 정책 동의	-	-

고객파일에 사용자 정보를 추가합니다. 한 번에 2,000명 이하의 고객 정보를 업로드할 수 있습니다. 각 사용자를 구분하는 값인 id는 회원번호(user_id)와 카카오톡 전화번호 중 하나여야 하고, 지정된 타입에 맞는 값을 입력해야 합니다. 스키마의 경우, 파일마다 다르게 지정되어 있으나 예제를 참고해 JSON 배열 형식으로 값을 전달합니다.

요청 성공 시, 어떤 고객파일에 대한 요청이었는지 알려주는 file_id와 고객파일에 추가 요청한 사용자 수, 실제로 추가된 사용자 수를 각각 받습니다. 추가 대상 사용자 정보가 유효하지 않거나 아래의 경우에는 고객파일에 사용자가 추가되지 않습니다. 따라서 추가 요청 사용자 수와 실제로 추가된 사용자 수는 차이가 날 수 있습니다.

참고: 고객파일에 일부 사용자가 추가되지 않은 경우 확인 항목
아래 내용을 확인합니다.

카카오톡 채널과 친구 상태인 사용자만 고객파일에 추가 가능합니다.
user_type이 app인 경우, ID 값이 카카오 로그인으로 발급된 회원번호(user id)여야 합니다. 즉, 해당 사용자가 카카오계정으로 서비스에 연결된 상태여야 합니다.
user_type이 phone인 경우, ID 값이 카카오톡에 가입되어 있는 전화번호여야 합니다.
요청
헤더
이름	설명	필수
Authorization	Authorization: KakaoAK ${APP_KEY}
인증 방식, REST API 키 또는 서비스 앱 어드민 키로 인증 요청	O
본문
이름	타입	설명	필수
file_id	Integer	파일 ID	O
channel_public_id	String	카카오톡 채널 프로필 ID

참고: 카카오톡 채널 프로필 ID 확인 방법	O
user_type	String	등록할 사용자 ID의 기준 값
app(회원번호) 또는 phone(카카오톡 전화번호) 중 하나	O
users	User[]	추가할 사용자 상세 정보 목록, ID와 스키마 값 포함	O
User
이름	타입	설명	필수
id	String	사용자 ID	O
field	JSON	지정된 스키마 대한 값
key, value 형태로 입력

참고: Number 또는 String 타입만 허용, String 타입인 경우 지정된 문자열만 사용 가능, 문자열은 카카오톡 채널 파트너센터 공지에 명시된 항목만 지정된 형식으로 변환해 입력 가능	O
응답
본문
이름	타입	설명
file_id	Integer	파일 ID
request_count	Integer	고객파일에 추가 요청한 사용자 수
success_count	Integer	고객파일에 추가된 사용자 수
예제
요청
curl -v -X POST "https://kapi.kakao.com/v1/talkchannel/update/target_users" \
    -H "Authorization: KakaoAK ${APP_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
            "file_id": 437,
            "channel_public_id": "_ZeUTxl",
            "user_type": "app",
            "users": [
            {
                "id": "12345",
                "field" : {
                    "생년월일": "2000-01-01",
                    "성별": "남자", 
                    "age": 19
                }
            },
            ...
        ]
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
 "file_id": 437,
 "request_count": 10,
 "success_count": 9
}
고객 관리: 고객파일의 사용자 삭제
기본 정보
메서드	URL	인증 방식
POST	https://kapi.kakao.com/v1/talkchannel/delete/target_users	REST API 키
서비스 앱 어드민 키
권한	사전 설정	카카오 로그인	동의항목
-	REST API 키
어드민 키
고객 관리 API 정책 동의	-	-

카카오톡 채널에 등록된 고객파일에서 특정 사용자를 삭제합니다. 고객파일에서 사용자를 삭제할 때는 성공 시에도 응답 본문이 없습니다. HTTP 상태 코드를 참고해 성공 여부를 판단합니다.

요청
헤더
이름	설명	필수
Authorization	Authorization: KakaoAK ${APP_KEY}
인증 방식, REST API 키 또는 서비스 앱 어드민 키로 인증 요청	O
본문
이름	타입	설명	필수
file_id	Integer	파일 ID	O
channel_public_id	String	카카오톡 채널 프로필 ID

참고: 카카오톡 채널 프로필 ID 확인 방법	O
user_type	String	삭제할 사용자 ID의 기준 값
app(회원번호) 또는 phone(카카오톡 전화번호) 중 하나	O
user_ids	JSON[]	삭제할 사용자 ID 목록	O
예제
요청
curl -v -X POST "https://kapi.kakao.com/v1/talkchannel/delete/target_users" \
    -H "Authorization: KakaoAK ${APP_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
            "file_id" : 437,
            "channel_public_id" : "_ZeUTxl",
            "user_type" : "app"
            "user_ids" : ["12345"]
        }'
응답
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8
더 보기