페이지 이동경로
  • 문서>
  • 카카오톡 채널>
  • 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

더 보기