페이지 이동경로
- 문서>
- 카카오톡 채널>
- REST API
카카오톡 채널
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 |
쿼리 파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| 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 |
쿼리 파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| 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 키 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| - | 고객 관리 API 정책 동의 | - | - |
새로운 고객 파일을 만듭니다. 새 파일 이름은 file_name, 적용할 필터링 기준은 schema에 각각 정의합니다. 한 번 정의한 스키마(Schema)는 수정할 수 없으니 주의합니다.
새 고객 파일을 만드는 데 성공하면 file_id 값으로 등록된 파일 ID가 반환됩니다. 파일 ID는 해당 파일에 사용자를 추가하거나 제외할 때 사용합니다.
제약 사항: 스키마
카카오톡 채널 고객 관리 API를 이용하여 고객 파일을 등록할 경우, 반드시 지정된 스키마 규칙을 따라야 합니다.
- 고객의 데이터가 문자열(
String)인 경우, 지원하는 키만 사용 가능- 생년월일, 국가, 지역, 성별, 연령, 구매금액, 포인트, 가입일, 최근 구매일, 응모일
- 새로운 키 추가 시 "앱유저아이디" 또는 "전화번호" 키 사용 불가, 키에 해당하는 값은 숫자(
Number) 자료형만 허용 - 스키마는 최대 30개 항목 포함 가능
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_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 ${REST_API_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 키 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| - | 고객 관리 API 정책 동의 | - | - |
카카오톡 채널에 등록된 고객 파일 정보들을 확인합니다. 어떤 카카오톡 채널에 등록된 파일 정보들을 알고 싶은지 channel_public_id 파라미터의 값을 명시하여 요청합니다. 요청 성공 시 해당 카카오톡 채널에 등록된 고객 파일들의 정보를 받습니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_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 ${REST_API_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 키 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| - | 고객 관리 API 정책 동의 | - | - |
고객 파일에 사용자 정보를 추가합니다. 한 번에 2,000명 이하의 고객 정보를 업로드할 수 있습니다. 각 사용자를 구분하는 값인 id는 회원번호(user_id)와 카카오톡 전화번호 중 하나여야 하고, 지정된 타입에 맞는 값을 입력해야 합니다. 스키마의 경우, 파일마다 다르게 지정되어 있으나 예제를 참고해 JSON 배열 형식으로 값을 전달합니다.
요청 성공 시, 어떤 고객 파일에 대한 요청이었는지 알려주는 file_id와 고객 파일에 추가 요청한 사용자 수, 실제로 추가된 사용자 수를 각각 받습니다. 추가 대상 사용자 정보가 유효하지 않거나 다음의 경우에는 고객 파일에 사용자가 추가되지 않습니다. 따라서 추가 요청 사용자 수와 실제로 추가된 사용자 수는 차이가 날 수 있습니다.
참고: 고객 파일에 일부 사용자가 추가되지 않은 경우 확인 항목
다음 내용을 확인합니다.
- 카카오톡 채널과 친구 상태인 사용자만 고객 파일에 추가 가능합니다.
- user_type이 app인 경우, ID 값이 카카오 로그인을 통해 발급된 회원번호(user id)여야 합니다. 즉, 해당 사용자가 카카오계정으로 서비스에 연결된 상태여야 합니다.
- user_type이 phone인 경우, ID 값이 카카오톡에 가입되어 있는 전화번호여야 합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_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 ${REST_API_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 키 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| - | 고객 관리 API 정책 동의 | - | - |
카카오톡 채널에 등록된 고객 파일에서 특정 사용자를 삭제합니다. 고객 파일에서 사용자를 삭제할 때는 성공 시에도 응답 본문이 없습니다. HTTP 상태 코드를 참고해 성공 여부를 판단합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_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 ${REST_API_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