페이지 이동경로
  • 문서>
  • 카카오톡 채널>
  • REST API

카카오톡 채널

REST API

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

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

기본 정보

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

신규 API 제공 안내

2021년 5월 24일부터 카카오톡 채널 관계 확인하기 API를 신규 API로 제공합니다. 신규 API에는 요청 URL과 일부 파라미터명이 'channels'로 변경됩니다. 기존 API 정보는 별도 문서에서 확인할 수 있습니다. 자세한 사항은 데브톡 공지사항을 참고합니다.

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

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

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

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

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

Request: Access Token 사용

URL
GET /v1/api/talk/channels HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization 사용자 인증 수단, 액세스 토큰 값
Authorization: Bearer ${ACCESS_TOKEN}
O
Parameter
Name Type Description Required
channel_public_ids String[] 사용자와의 친구 관계를 확인할 카카오톡 채널의 프로필 ID 목록
채널 URL에서 https://pf.kakao.com/ 부분을 제외한 뒷자리 값
예) 채널 URL이 https://pf.kakao.com/_ZeUTxl인 경우, 카카오톡 채널의 프로필 ID는 _ZeUTxl
X

Request: Admin Key 사용

URL
GET /v1/api/talk/channels HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization 사용자 인증 수단, 앱 어드민 키
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String 사용자 ID 타입, user_id로 고정 O
target_id String 회원번호 O
channel_public_ids String[] 사용자와의 친구 관계를 확인할 카카오톡 채널의 프로필 ID 목록
채널 URL에서 https://pf.kakao.com/ 부분을 제외한 뒷자리 값
예) 채널 URL이 https://pf.kakao.com/_ZeUTxl인 경우, 카카오톡 채널의 프로필 ID는 _ZeUTxl
X

Response

Name Type Description Required
user_id Long 회원번호 O
channels Channels[] 카카오톡 채널 정보 X
Channels
Name Type Description Required
channel_uuid String 카카오톡 채널의 검색용 ID O
channel_public_id String 카카오톡 채널 프로필 ID O
relation String 카카오톡 채널과 사용자 관계
ADDED: 카카오톡 채널이 추가된 상태
BLOCKED: 카카오톡 채널이 차단된 상태
NONE: 카카오톡 채널이 추가되거나 차단된 적 없는 상태
O
updated_at Datetime 카카오톡 채널 상태 변경 시간, UTC*
카카오톡 채널이 추가(ADDED) 또는 차단(BLOCKED)된 상태일 경우만 포함
X

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

Sample

Request: 액세스 토큰 사용
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"]'
Request: 어드민 키 사용
curl -v -G GET "https://kapi.kakao.com/v1/api/talk/channels" \
    -H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=${USER_ID}" \
    --data-urlencode 'channel_public_ids=["_frxjem","_xnrxjem","_Brxjem"]'
Response: 성공
HTTP/1.1 200 OK
{
  "user_id": 1111111,
  "channels": [
    {
      "channel_uuid": "@테스트",
      "channel_public_id": "_ZeUTxl",
      "relation": "ADDED", // ADDED, BLOCKED, NONE 중 하나
      "updated_at": "2021-05-17T05:25:01Z" // ADDED, BLOCKED 상태일 때만 존재
    },
    ...
  ]
}
Response: 실패, 카카오톡 미사용자를 대상으로 요청한 경우
HTTP/1.1 400 Bad Request
{
    "msg": "given account is not connected to any talk user.",
    "code": -501
}

사용자가 서비스와 연결된 카카오톡 채널을 추가 또는 차단했을 때 알림을 받으려면, 카카오톡 채널 관계 알림 받기 기능을 사용합니다. 자세한 안내는 카카오톡 채널 관계 알림을 참고합니다.

고객 관리: 파일 등록하기

기본 정보

사전 설정
고객 관리 API 정책 동의

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

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

Request

URL
POST /v1/talkchannel/create/target_user_file HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
Name Type Description Required
channel_public_id String 카카오톡 채널 프로필 ID
채널 URL에서 https://pf.kakao.com/ 부분을 제외한 뒷자리 값
예) 채널 URL이 https://pf.kakao.com/_ZeUTxl인 경우, 카카오톡 채널의 프로필 ID는 _ZeUTxl
O
schema JSON 고객 파일에 등록되는 데이터 항목과 항목의 종류를 정의
키(Key)와 값(Value)의 JSON 자료형(Type)으로 구성
키: 생년월일, 국가, 지역, 성별, 연령, 구매금액, 포인트, 가입일, 최근 구매일, 응모일
값의 자료형: String 또는 Number
O
file_name Stirng 관리할 파일의 이름 O
주의: 스키마

카카오톡 채널 고객 관리 API를 이용하여 고객 파일을 등록할 경우, 반드시 지정된 스키마 규칙을 따라야 합니다. - 고객의 데이터가 문자열(String)일 경우, 지원하는 키 값만 사용할 수 있습니다: 생년월일, 국가, 지역, 성별, 연령, 구매금액, 포인트, 가입일, 최근 구매일, 응모일 - 기본적으로 제공하는 키 값 외에 새로운 키를 추가할 수 있지만, 이 경우 키 값의 자료형이 숫자(Number)여야 합니다. 데이터가 문자열일 경우, 데이터의 종류를 숫자로 변환하여 입력할 수 있도록 합니다. 자세한 사항은 카카오톡 채널 관리자센터 공지사항을 참고합니다.

Response

Name Type Description
file_id Integer 등록된 고객 파일 ID

Sample

Request
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"
        }
    }'
Response
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
  "file_id" : 437
}

고객 관리: 파일 보기

기본 정보

사전 설정
고객 관리 API 정책 동의

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

Request

URL
GET /v1/talkchannel/target_user_file HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
Name Type Description Required
channel_public_id String 카카오톡 채널 프로필 ID
채널 URL에서 https://pf.kakao.com/ 부분을 제외한 뒷자리 값
예) 채널 URL이 https://pf.kakao.com/_ZeUTxl인 경우, 카카오톡 채널의 프로필 ID는 _ZeUTxl
O

Response

Name Type Description
empty_slot Integer 사용 가능한 슬롯 수
using_slot Integer 사용 중인 슬롯 수
results JSON Array 카카오톡 채널에 등록된 고객 파일들의 정보
Results
Name Type Description
file_id Integer 파일 ID
file_name String 파일 이름
status String 파일 상태
using, deleting, failed 중 하나
update_at String 파일이 업로드 된 시간
schema JSON 파일에 등록된 데이터 항목과 항목의 종류

Sample

Request
curl -v -G GET "https://kapi.kakao.com/v1/talkchannel/target_user_file" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -d "channel_public_id=_ZeUTxl"
Response
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\"}"
    },
    ...
  ]
  
}

고객 관리: 사용자 추가하기

기본 정보

사전 설정
고객 관리 API 정책 동의

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

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

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

다음 내용을 확인합니다.

  • 카카오톡 채널과 친구 상태인 사용자만 고객 파일에 추가 가능합니다.
  • user_type이 app인 경우, ID 값이 카카오 로그인을 통해 발급된 회원번호(user id)여야 합니다. 즉, 해당 사용자가 카카오계정으로 서비스에 연결된 상태여야 합니다.
  • user_type이 phone인 경우, ID 값이 카카오톡에 가입되어 있는 전화번호여야 합니다.

Request

URL
POST /v1/talkchannel/update/target_users HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
Name Type Description Required
file_id Integer 파일 ID O
channel_public_id String 카카오톡 채널 프로필 ID
채널 URL에서 https://pf.kakao.com/ 부분을 제외한 뒷자리 값
예) 채널 URL이 https://pf.kakao.com/_ZeUTxl인 경우, 카카오톡 채널의 프로필 ID는 _ZeUTxl
O
user_type String 등록할 사용자 ID의 기준 값
app(회원번호) 또는 phone(카카오톡 휴대전화번호) 중 하나
O
users JSON[] 추가할 사용자 상세 정보 목록, ID와 스키마 값 포함 O
users
Name Type Description Required
id String 사용자 ID O
field JSON 지정된 스키마 대한 값
key, value 형태로 입력
O

Response

Name Type Description
file_id Integer 파일 ID
request_count Integer 고객 파일에 추가 요청한 사용자 수
success_count Integer 고객 파일에 추가된 사용자 수

Sample

Request
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
                }
            },
            ...
        ]
    }'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
 "file_id": 437,
 "request_count": 10,
 "success_count": 9
}

고객 관리: 사용자 삭제하기

기본 정보

사전 설정
고객 관리 API 정책 동의

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

Request

URL
POST /v1/talkchannel/delete/target_users HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
Name Type Description Required
file_id Integer 파일 ID O
channel_public_id String 카카오톡 채널 프로필 ID
채널 URL에서 https://pf.kakao.com/ 부분을 제외한 뒷자리 값
예) 채널 URL이 https://pf.kakao.com/_ZeUTxl인 경우, 카카오톡 채널의 프로필 ID는 _ZeUTxl
O
user_type String 삭제할 사용자 ID의 기준 값
app(회원번호) 또는 phone(카카오톡 휴대전화번호) 중 하나
O
user_ids JSON[] 삭제할 사용자 ID 목록 O

Sample

Request
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"]
        }'
Response
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8

더보기