카카오톡 채널

REST API

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

이 문서에 포함된 기능 일부는 [도구] > [REST API 테스트]에서 사용해 볼 수 있습니다. 테스트 기능은 어드민 키로 호출할 수 없습니다.

카카오톡 채널 관계 조회

기본 정보

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

권한	사전 설정	카카오 로그인	동의항목
필요: 동의항목	어드민 키 카카오 로그인 활성화 동의항목 앱에 카카오톡 채널 연결	필요	필요: 카카오톡 채널 추가 상태 및 내역

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

신규 API 제공 안내

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

카카오톡 채널 웹훅

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

사용자 동의 요청

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

요청: 액세스 토큰 방식

헤더

이름	설명	필수
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": 1234567890, // ${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`	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
필요: 동의항목	어드민 키 카카오 로그인 활성화 동의항목 앱에 카카오톡 채널 연결	필요	필요: 카카오톡 채널 추가 상태 및 내역

앱에 연결된 카카오톡 채널과 여러 사용자의 친구 관계를 반환합니다.

카카오톡 채널 웹훅

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

요청

헤더

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

쿼리 파라미터

이름	타입	설명	필수
target_ids	`String`	회원번호 목록, 쉼표로 구분된 하나의 문자열로 구성(최대: 200명)	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": 1234567890, // ${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": 2345678901, // ${USER_ID_2}
    "channels": [
      {
        "channel_public_id": "_xnrxjem",
        "channel_uuid": "@플러스친구",
        "relation": "NONE"
      }
    ]
  }
  // ...
]

응답: 확인에 실패한 사용자 제외

// HTTP/1.1 200 OK
[
  {
    "user_id": 1234567890, // ${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)는 수정 불가
등록 성공 시 반환되는 파일 ID(file_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	O

예제

요청

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 정책 동의	-	-

카카오톡 채널에 등록된 고객파일 정보들을 반환합니다.

요청

헤더

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

쿼리 파라미터

이름	타입	설명	필수
channel_public_id	`String`	카카오톡 채널 프로필 ID 참고: 카카오톡 채널 프로필 ID 확인 방법	O

응답

본문

이름	타입	설명	필수
empty_slot	`Integer`	사용 가능한 슬롯 수	O
using_slot	`Integer`	사용 중인 슬롯 수	O
results	`Results[]`	카카오톡 채널에 등록된 고객파일들의 정보	O

Results

이름	타입	설명	필수
file_id	`Integer`	파일 ID	O
file_name	`String`	파일 이름	O
status	`String`	파일 상태, 아래 중 하나 `using`: 사용 중 `deleting`: 삭제 중 `failed`: 실패	O
update_at	`String`	파일이 업로드 된 시간	O
schema	`JSON`	파일에 등록된 데이터 항목과 항목의 종류	O

예제

요청

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 정책 동의	-	-

고객파일에 사용자 정보를 추가합니다.

참고: 고객파일에 일부 사용자가 추가되지 않은 경우 확인 항목

추가 대상 사용자 정보가 유효하지 않거나, 아래의 경우 고객파일에 사용자가 추가되지 않아 요청한 사용자와 추가된 사용자의 수가 다를 수 있습니다.

카카오톡 채널과 친구 상태인 사용자만 고객파일에 추가 가능합니다.
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와 스키마 값 포함(최대: 2,000명)	O

User

이름	타입	설명	필수
id	`String`	사용자 ID `user_type`에 따라 회원번호(user_id) 또는 카카오톡 전화번호 전달	O
field	`JSON`	지정된 스키마 대한 값 key, value 형태로 입력 참고: Number 또는 String 타입만 허용, String 타입인 경우 지정된 문자열만 사용 가능, 문자열은 카카오톡 채널 파트너센터 공지에 명시된 항목만 지정된 형식으로 변환해 입력 가능	O

응답

본문

이름	타입	설명	필수
file_id	`Integer`	파일 ID	O
request_count	`Integer`	고객파일에 추가 요청한 사용자 수	O
success_count	`Integer`	고객파일에 추가된 사용자 수	O

예제

요청

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 정책 동의	-	-

카카오톡 채널에 등록된 고객파일에서 특정 사용자를 삭제합니다.

요청

헤더

이름	설명	필수
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

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

REST API

카카오톡 채널 관계 조회

기본 정보

사용자 동의 요청

요청: 액세스 토큰 방식

헤더

쿼리 파라미터

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

헤더

쿼리 파라미터

응답

본문

Channels

예제

요청: 액세스 토큰 방식

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

응답: 성공

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

여러 사용자 카카오톡 채널 관계 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

TalkChannelsResult

TalkChannelRelation

예제

요청

응답

응답: 확인에 실패한 사용자 제외

고객 관리: 고객파일 등록

기본 정보

사용 조건

제약 사항: 스키마

요청

헤더

본문

응답

본문

예제

요청

응답

고객 관리: 고객파일 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

Results

예제

요청

응답

고객 관리: 고객파일에 사용자 추가

기본 정보

참고: 고객파일에 일부 사용자가 추가되지 않은 경우 확인 항목

요청

헤더

본문

User

응답

본문

예제

요청

응답

고객 관리: 고객파일의 사용자 삭제

기본 정보

요청

헤더