카카오톡 채널

REST API

이 문서는 카카오 또는 공동체 서비스용 카카오 소셜 REST API 사용법을 안내합니다.

카카오톡 채널 프로필 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/talk/channels/profile` 공동체 `https://kapi.kakao.com/v1/internal/talk/channels/profile` 외부 `https://kapi.kakao.com/v1/api/talk/channels/profile`	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
필요	어드민 키 카카오 로그인 활성화 동의항목 카카오톡 채널 설정	-	-

앱과 연결된 카카오톡 채널의 프로필 정보를 조회합니다.

앱 어드민 키(Admin key)를 헤더에 담아 GET으로 요청합니다. channel_public_ids에 카카오톡 채널의 프로필 ID를 지정하면 해당 카카오톡 채널의 프로필 정보만 응답에 포함됩니다.

요청 성공 시 응답은 앱과 연결된 카카오톡 채널의 프로필 정보를 포함한 배열입니다.

요청

헤더

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

쿼리 파라미터

이름	타입	설명	필수
channel_public_ids	`String[]`	프로필을 조회할 카카오톡 채널의 프로필 ID 목록 미포함 시 앱과 연결된 전체 카카오톡 채널 확인 참고: 카카오톡 채널 프로필 ID 확인 방법	X

응답

본문

이름	타입	설명	필수
TalkChannelProfile	`TalkChannelProfile[]`	카카오톡 채널의 프로필 정보 배열	O

TalkChannelProfile

이름	타입	설명	필수
channel_public_id	`String`	카카오톡 채널 프로필 ID	O
channel_profile_name	`String`	카카오톡 채널명	O
channel_profile_image_url	`String`	카카오톡 채널의 프로필 이미지 URL 640 px * 640 px	X
channel_thumbnail_image_url	`String`	카카오톡 채널의 썸네일 이미지 URL 110 px * 110 px	X
channel_intro_message	`String`	카카오톡 채널 소개 메시지	X
channel_uuid	`String`	카카오톡 채널의 카카오톡 검색용 ID	O
is_open	`Boolean`	카카오톡 채널 공개 여부 참고: 값이 `false`인 경우 카카오톡 채널 친구 추가 불가	O
is_blocked	`Boolean`	카카오톡 채널 제재 여부 참고: 값이 `true`인 경우 카카오톡 채널 친구 추가 불가	O
channel_home_url	`String`	카카오톡 채널 URL	O

예제

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

파라미터
- 카카오톡 채널의 프로필 ID 목록(channel_public_ids)

curl -v -G GET "https://kapi.kakao.com/v1/internal/talk/channels/profile" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d 'channel_public_ids=["_frxjem","_xnrxjem"]'

응답

// HTTP/1.1 200 OK
[
  {
    "channel_public_id": "_frxjem",
    "channel_profile_name": "연결채널A",
    "channel_profile_image_url": "https://p.kakaocdn.net/th/talkp/wkbZPRnplE/QlS4bqerAYSEBGkpnYHh91/6tfwkz_640x640_s.jpg",
    "channel_thumbnail_image_url": "https://p.kakaocdn.net/th/talkp/wkb8wjUOza/CKbZSPBZcmoivieMxUW8sk/gx9phu_110x110_c.jpg",
    "channel_uuid": "@채널A",
    "is_open": true,
    "is_blocked": false,
    "channel_home_url": "http://pf.kakao.com/_frxjem"
  },
  {
    "channel_public_id": "_xnrxjem",
    "channel_profile_name": "연결채널B",
    "channel_profile_image_url": "https://p.kakaocdn.net/th/talkp/wkbZPRnplE/QlS4bqerAYSEBGkpnYHh91/6tfwkz_640x640_s.jpg",
    "channel_thumbnail_image_url": "https://p.kakaocdn.net/th/talkp/wkbZPRnplE/QlS4bqerAYSEBGkpnYHh91/6tfwkz_110x110_c.jpg",
    "channel_uuid": "@채널B",
    "is_open": true,
    "is_blocked": false,
    "channel_home_url": "http://pf.kakao.com/_xnrxjem"
  }
]

응답: 실패, 잘못된 카카오톡 채널 프로필 ID

// HTTP/1.1 400 Bad Request
{
  "msg": "invalid channel ids. channel_public_ids=[${CHANNEL_PUBLIC_IDS}]",
  "code": -2
}

카카오톡 채널 관계 조회

기본 정보

메서드	URL	인증 방식
`GET` / `POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/channels` 공동체 `https://kapi.kakao.com/v2/internal/talk/channels` 외부 `https://kapi.kakao.com/v2/api/talk/channels` 배치 `http://kapi.kakao.com/v2/internal/talk/channels/batch`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
필요: 비즈 채널 앱 또는 공동체 앱	어드민 키 카카오 로그인 활성화 동의항목 카카오톡 채널 설정	필요: 연결, 연결 대기	필요: 카카오톡 채널 추가 상태 및 내역*

* 카카오페이의 경우, 별도 동의항목 사용(금융데이터 분석 및 활용을 위한 데이터 제공)

카카오톡 채널 웹훅

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

버전 업그레이드

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

사용자와 앱에 연결된 카카오톡 채널의 친구 관계를 확인합니다. 이 API를 사용해 사용자와 카카오톡 채널이 친구가 아닐 때 친구 추가 버튼을 노출하거나, 이미 친구일 때 친구 추가 요청을 하지 않도록 할 수 있습니다.

이 API로 한 명의 사용자와 여러 개의 카카오톡 채널 사이의 관계를 확인할 수 있습니다. 조회 대상인 사용자는 요청 대상 앱에 연결 또는 연결 대기 상태여야 하고, 카카오톡 채널은 앱에 연결 또는 수동 등록된 상태여야 합니다.

헤더에 원하는 인증 정보를 담아 GET 또는 POST로 요청하고, 성공 시 사용자와 카카오톡 채널의 관계 정보를 받습니다.

대상 카카오톡 채널을 직접 지정하려면 사용자와의 친구 관계를 확인할 카카오톡 채널의 ID 목록(channel_ids)을 파라미터로 전달해야 합니다. 요청 시 channel_ids 값을 전달하지 않으면 앱에 연결 또는 수동 등록된 모든 카카오톡 채널을 대상으로 관계를 확인합니다.

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

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

사용자의 카카오계정 ID(account_id)와 카카오톡 채널의 카카오톡 회원번호(channel_talk_id)는 앱에 응답 권한이 있는 경우 제공합니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
channel_ids	`String`	사용자와의 친구 관계를 확인할 카카오톡 채널 ID 목록 쉼표로 구분된 하나의 문자열로 전달 (기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록) 참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	`String`	카카오톡 채널 ID 유형, 아래 중 하나 `channel_public_id`: 카카오톡 채널의 프로필 ID `channel_talk_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`	카카오톡 채널과의 관계를 확인할 사용자 ID	O
target_id_type	`String`	`target_id`의 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
channel_ids	`String`	사용자와의 친구 관계를 확인할 카카오톡 채널 ID 목록 쉼표로 구분된 하나의 문자열로 전달 (기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록) 참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	`String`	카카오톡 채널 ID 유형, 아래 중 하나 `channel_public_id`: 카카오톡 채널의 프로필 ID `channel_talk_id`: 카카오톡 채널의 카카오톡 회원번호 (기본값: `channel_public_id`)	X

요청: 위임 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	요청 대상 사용자와 연결된 요청 앱의 키	O(Optional)
target_app_id	`String`	요청 대상 사용자와 연결된 요청 앱의 ID	O(Optional)
target_access_token	`String`	카카오톡 채널과의 관계를 확인할 사용자의 액세스 토큰 값	O(Optional)
target_id	`String`	카카오톡 채널과의 관계를 확인할 사용자 ID	O(Optional)
target_id_type	`String`	`target_id`의 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O(Optional)
channel_ids	`String`	사용자와의 친구 관계를 확인할 카카오톡 채널 ID 목록 쉼표로 구분된 하나의 문자열로 전달 (기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록) 참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	`String`	카카오톡 채널 ID 유형, 아래 중 하나 `channel_public_id`: 카카오톡 채널의 프로필 ID `channel_talk_id`: 카카오톡 채널의 카카오톡 회원번호 (기본값: `channel_public_id`)	X

응답

본문

이름	타입	설명	필수
user_id	`Long`	회원번호	X
account_id	`Integer`	카카오계정 ID 제공 조건: 카카오계정 ID(account_id) 응답 권한 보유, 내부 API 요청	X
channels	`ChannelRelation[]`	각 카카오톡 채널과 사용자의 관계 정보	X

ChannelRelation

이름	타입	설명	필수
channel_talk_id	`Long`	카카오톡 채널 ID 제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유, 내부 API 요청	X
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 참고

예제

요청: 액세스 토큰 방식

파라미터
- 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널 ID 타입(channel_id_type): 카카오톡 채널 프로필 ID(channel_public_id)

curl -v -G GET "http://kapi.kakao.com/v2/internal/talk/channels" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "channel_ids=_frxjem,_xnrxjem,_Brxjem" \
  -d "channel_id_type=channel_public_id"

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

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)
- 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널 ID 타입(channel_id_type): 카카오톡 회원번호(channel_talk_id)

curl -v -G GET "http://kapi.kakao.com/v2/internal/talk/channels" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=${USER_ID}" \
  -d "target_id_type=user_id" \
  -d "channel_ids=12345,23445,44552" \
  -d "channel_id_type=channel_talk_id"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)
- 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널 ID 타입(channel_id_type): 카카오톡 채널 프로필 ID(channel_public_id)

curl -v -G GET "http://kapi.kakao.com/v2/internal/talk/channels" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_key=${SERVICE_APP_KEY}" \
  -d "target_id=${ACCOUNT_ID}" \
  -d "target_id_type=account_id" \
  -d "channel_ids=_frxjem,_xnrxjem,_Brxjem" \
  -d "channel_id_type=channel_public_id"

요청: 위임 방식

파라미터
- 서비스 앱 ID(target_app_id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)
- 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널 ID 타입(channel_id_type): 카카오톡 채널 프로필 ID(channel_public_id)

curl -v -G GET "http://kapi.kakao.com/v2/internal/talk/channels" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_id=213685" \
  -d "target_id=${USER_ID}" \
  -d "target_id_type=user_id" \
  -d "channel_ids=_frxjem,_xnrxjem,_Brxjem" \
  -d "channel_id_type=channel_public_id"

요청: 위임 방식

파라미터
- 액세스 토큰(target_access_token)
- 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널 ID 타입(channel_id_type): 카카오톡 채널 프로필 ID(channel_public_id)

curl -v -G GET "http://kapi.kakao.com/v2/internal/talk/channels" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_access_token=${ACCESS_TOKEN}" \
  -d "channel_ids=_frxjem,_xnrxjem,_Brxjem" \
  -d "channel_id_type=channel_public_id"

응답

// HTTP/1.1 200 OK
{
  "user_id": 1376016924426879191,
  "account_id": 81820, // 카카오계정 ID 응답 권한 필요
  "channels": [
    {
      "channel_talk_id": 12345, // 카카오톡 회원번호 응답 권한 필요
      "channel_uuid": "@채널A",
      "channel_public_id": "_frxjem",
      "relation": "ADDED", // ADDED, BLOCKED, NONE 중 하나
      "created_at": "2018-02-18T03:17:05Z", // ADDED 상태일 때만 존재
      "updated_at": "2018-03-14T05:25:01Z" // ADDED, BLOCKED 상태일 때만 존재
    },
    {
      "channel_talk_id": 23445,
      "channel_uuid": "@채널B",
      "channel_public_id": "_xnrxjem",
      "relation": "ADDED",
      "created_at": "2018-02-18T03:15:05Z",
      "updated_at": "2018-02-20T05:27:07Z"
    },
    {
      "channel_talk_id": 44552,
      "channel_uuid": "@채널C",
      "channel_public_id": "_Brxjem",
      "relation": "NONE"
    }
  ]
}

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

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v2/internal/talk/channels/multi` 공동체 `https://kapi.kakao.com/v2/internal/talk/channels/multi` 외부 `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`	사용자 ID 목록, 쉼표로 구분된 하나의 문자열로 전달	O
target_id_type	`String`	사용자 ID 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 (기본값: `user_id`)	O
channel_ids	`String`	사용자와의 친구 관계를 확인할 카카오톡 채널의 ID 목록, 쉼표로 구분된 하나의 문자열로 전달 (기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록) 참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	`String`	카카오톡 채널 ID 타입, 아래 중 하나 `channel_public_id`: 카카오톡 채널의 프로필 ID `channel_talk_id`: 카카오톡 채널의 카카오톡 회원번호 (기본값: `channel_public_id`)	X

응답

본문

이름	타입	설명	필수
-	`TalkChannelsResult[]`	각 사용자의 카카오톡 채널별 친구 관계 목록	O

TalkChannelsResult

이름	타입	설명	필수
user_id	`Long`	회원번호	O
account_id	`Integer`	카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유, 내부 API 요청	X
channels	`TalkChannelRelation[]`	각 카카오톡 채널과 사용자의 관계 정보	X

TalkChannelRelation

이름	타입	설명	필수
channel_uuid	`String`	카카오톡 채널의 검색용 ID	O
channel_public_id	`String`	카카오톡 채널 프로필 ID	O
channel_talk_id	`Long`	카카오톡 채널의 카카오톡 회원번호 제공 조건: 카카오톡 회원번호 응답 권한 보유, 내부 API 요청	X
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 참고

예제

요청

파라미터
- 사용자 ID 목록(target_ids)
- 사용자 ID 타입(target_id_type)
- 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널 ID 타입(channel_id_type): 프로필 ID

curl -v -G GET "http://kapi.kakao.com/v2/internal/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}" \
  -d "channel_id_type=channel_public_id" \
  --data-urlencode 'channel_ids=_xnrxjem,_Brxjem'

응답

// HTTP/1.1 200 OK
[
  {
    "user_id": 1376016924430691663,
    "account_id": 2137162, // ${ACCOUNT_ID}, 카카오계정 ID 응답 권한 필요
    "channels": [
      {
        "channel_public_id": "_xnrxjem",
        "channel_uuid": "@플러스친구",
        "chananel_talk_id": 987654321, // ${TALK_ID}, 카카오톡 회원번호 응답 권한 필요
        "relation": "ADDED",
        "created_at": "2022-11-09T07:08:48Z",
        "updated_at": "2023-07-20T07:21:05Z"
      }
      // ...
    ]
  },
  {
    "user_id": 1376016924431192675,
    "account_id": 2137163, // ${ACCOUNT_ID}
    "channels": [
      {
        "channel_public_id": "_xnrxjem",
        "channel_uuid": "@플러스친구",
        "chananel_talk_id": 987654322, // ${TALK_ID}, 카카오톡 회원번호 응답 권한 필요
        "relation": "NONE"
      }
      // ...
    ]
  }
]

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

// HTTP/1.1 200 OK
[
  {
    "user_id": 1376016924430691663,
    "account_id": 2137162, // ${ACCOUNT_ID}, 카카오계정 ID 응답 권한 필요
    "channels": [
      {
        "channel_public_id": "_xnrxjem",
        "channel_uuid": "@플러스친구",
        "chananel_talk_id": 987654321, // ${TALK_ID}, 카카오톡 회원번호 응답 권한 필요
        "relation": "ADDED",
        "created_at": "2022-11-09T07:08:48Z",
        "updated_at": "2023-07-20T07:21:05Z"
      }
      // ...
    ]
  }
]

카카오톡 채널 친구 추가

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/channels/add` 공동체 `https://kapi.kakao.com/v2/internal/talk/channels/add` 외부 `https://kapi.kakao.com/v2/api/talk/channels/add`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
필요: 공동체 앱	어드민 키 카카오 로그인 활성화 동의항목 카카오톡 채널 설정	필요: 연결, 연결 대기	-

카카오톡 채널 친구 추가 문구 안내

오톡 채널 친구 추가 API를 사용해 사용자에게 카카오톡 채널을 친구로 추가하려는 경우, 정보통신망법 제50조를 기반으로 하는 KISA 가이드라인에 따라 반드시 지정된 문구로 안내해야 합니다.(참고) 사용 가능한 문구는 아래와 같습니다.

기본 문구: [카카오톡 채널 이름]의 광고와 마케팅 메시지를 카카오톡으로 받습니다. 축약형

[카카오톡 채널 이름]의 광고와 마케팅 메시지를 카카오톡으로 받기
[카카오톡 채널 이름]의 광고 메시지를 카카오톡으로 받기

버전 업그레이드

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

특정 카카오톡 채널을 사용자의 친구로 추가합니다. 사용자가 해당 카카오톡 채널을 차단한 상태일 경우, 차단을 해제하고 친구 추가합니다. 한 번에 여러 개의 채널을 친구로 추가할 수 있습니다.

대상 카카오톡 채널은 아래 조건을 만족해야 합니다.

앱에 연결된 카카오톡 채널
프로필이 공개된 카카오톡 채널

헤더에 원하는 인증 정보를 담아 POST로 요청하고, 성공 시 사용자의 친구로 추가된 카카오톡 채널의 정보를 받습니다. 여러 개의 카카오톡 채널을 추가하려면 요청 시 추가할 카카오톡 채널의 ID 목록(channel_ids)을 파라미터로 전달해야 합니다. 요청 시 channel_ids 값을 전달하지 않으면 앱과 연결 또는 수동 등록된 카카오톡 채널이 친구로 추가됩니다.

요청 성공 시 응답은 각 카카오톡 채널의 친구 추가 결과를 포함합니다. 친구 추가에 실패한 카카오톡 채널은 실패 원인을 channels.failure_msg로 안내합니다. 사용 조건을 만족하지 않는 채널에 대한 친구 추가 요청 시 에러가 발생합니다. 사용자의 카카오계정 ID(account_id)와 카카오톡 채널의 카카오톡 회원번호(channel_talk_id)는 앱에 응답 권한이 있는 경우 제공합니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
channel_ids	`String`	사용자의 친구로 추가할 카카오톡 채널 ID 목록 쉼표로 구분된 하나의 문자열로 전달 (기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록) 참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	`String[]`	카카오톡 채널 ID 유형, 아래 중 하나 `channel_public_id`: 카카오톡 채널의 프로필 ID `channel_talk_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

본문

이 인증 방식을 사용할 경우, 다른 서비스 앱을 대상으로 지정하는 channel_app_id 파라미터를 사용할 수 있습니다. 해당 파라미터 사용 시 요청을 보내는 앱과 서비스 앱에 권한이 필요합니다.
- 요청을 보내는 앱: PLUS_FRIEND_APP_ID_CALLER
- 요청 대상 카카오톡 채널과 연결 또는 수동 등록된 서비스 앱: PLUS_FRIEND_APP_ID_CALLEE

이름	타입	설명	필수
target_id	`String`	카카오톡 채널을 친구로 추가할 사용자의 ID	O
target_id_type	`String`	`target_id`의 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 (기본값: `user_id`)	O
channel_ids	`String`	사용자의 친구로 추가할 카카오톡 채널 ID 목록 쉼표로 구분된 하나의 문자열로 전달 (기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록) 참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	`String`	카카오톡 채널 ID 유형, 아래 중 하나 `channel_public_id`: 카카오톡 채널의 프로필 ID `channel_talk_id`: 카카오톡 채널의 카카오톡 회원번호 (기본값: `channel_public_id`)	X
channel_app_id	`Integer`	사용자의 친구로 추가할 카카오톡 채널과 연결된 서비스 앱 ID	X

요청: 위임 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

본문

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	카카오톡 채널 추가를 요청하는 서비스 앱의 키	O(Optional)
target_app_id	`String`	카카오톡 채널 추가를 요청하는 서비스 앱의 ID	O(Optional)
target_access_token	`String`	카카오톡 채널을 친구로 추가할 사용자의 액세스 토큰	O(Optional)
target_id	`String`	카카오톡 채널을 친구로 추가할 사용자의 ID	O(Optional)
target_id_type	`String`	`target_id`의 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 (기본값: `user_id`)	O(Optional)
channel_ids	`String`	사용자의 친구로 추가할 카카오톡 채널 ID 목록 쉼표로 구분된 하나의 문자열로 전달 (기본값: 앱과 연결된 모든 카카오톡 채널의 프로필 ID 목록) 참고: 카카오톡 채널 프로필 ID 확인 방법	X
channel_id_type	`String`	카카오톡 채널 ID 유형, 아래 중 하나 `channel_public_id`: 카카오톡 채널의 프로필 ID `channel_talk_id`: 카카오톡 채널의 카카오톡 회원번호 (기본값: `channel_public_id`)	X

응답

본문

이름	타입	설명	필수
user_id	`Long`	회원번호	O
account_id	`Integer`	카카오계정 ID 제공 조건: 카카오계정 ID(account_id) 응답 권한 보유, 내부 API 요청	X
channels	`Channel[]`	친구로 추가한 카카오톡 채널 정보	X

Channel

이름	타입	설명	필수
channel_talk_id	`Long`	카카오톡 채널 ID 제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유, 내부 API 요청	X
channel_public_id	`String`	사용자의 친구로 추가된 카카오톡 채널의 프로필 ID	O
channel_uuid	`String`	카카오톡 채널의 카카오톡 검색용 ID	O
success	`Boolean`	친구 추가 성공 여부 `true`: 성공 `false`: 실패	O
failure_msg	`String`	친구 추가 실패 원인을 담은 메시지 여러 개의 카카오톡 채널에 대한 친구 추가 요청 시에만 응답에 포함 `INVALID_CHANNEL`: 존재하지 않거나 삭제된 카카오톡 채널 `BLOCKED_CHANNEL`: 제재 상태인 카카오톡 채널 `UNDER_AGE_LIMIT`: 연령인증이 필요한 채널 `MAX_CHANNELS_LIMIT`: 사용자가 추가할 수 있는 카카오톡 채널의 최대 수를 넘어선 경우 `ERROR`: 카카오톡 채널 PAPI 내부 서버 오류 참고: 하나의 채널 추가 요청이 실패한 경우에는 응답의 에러 코드로 원인 확인	X

예제

요청: 액세스 토큰 방식

파라미터
- 사용자의 친구로 추가할 카카오톡 채널 ID 목록(channel_ids)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "channel_ids=_frxjem,_xnrxjem"

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

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오계정 ID(account_id)
- 사용자의 친구로 추가할 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널의 ID 타입(channel_id_type): 카카오톡 채널 프로필 ID(channel_public_id)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=2137163" \
  -d "target_id_type=account_id" \
  -d "channel_ids=_frxjem,_xnrxjem" \
  -d "channel_id_type=channel_public_id"

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

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)
- 사용자의 친구로 추가할 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널의 ID 타입(channel_id_type): 카카오톡 회원번호(channel_talk_id)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id=1376016924426684995" \
  -d "target_id_type=user_id" \
  -d "channel_ids=1234,2345" \
  -d "channel_id_type=channel_talk_id"

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

파라미터
- 대상 서비스 앱 ID(channel_app_id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)
- 사용자의 친구로 추가할 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널의 ID 타입(channel_id_type): 카카오톡 회원번호(channel_talk_id)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "channel_app_id=123456" \
  -d "target_id=1376016924426684995" \
  -d "target_id_type=user_id" \
  -d "channel_ids=1234,2345" \
  -d "channel_id_type=channel_talk_id"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)
- 사용자의 친구로 추가할 카카오톡 채널 ID 목록(channel_ids)
- 카카오톡 채널의 ID 타입(channel_id_type): 카카오톡 회원번호(channel_talk_id)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_key=${SERVICE_APP_KEY}" \
  -d "target_id=1376016924426684995" \
  -d "target_id_type=user_id" \
  -d "channel_ids=1234,2345" \
  -d "channel_id_type=channel_talk_id"

응답

// HTTP/1.1 200 OK
{
  "user_id": 10071,
  "account_id": 5279, //    카카오계정 ID 응답 권한 필요
  "channels": [
    {
      "channel_talk_id": 60896, // 카카오톡 회원번호 응답 권한 필요
      "channel_public_id": "_Bxkd",
      "channel_uuid": "@릴리",
      "success": true
    },
    {
      "channel_talk_id": 65282, // 카카오톡 회원번호 응답 권한 필요
      "channel_public_id": "_RQxl",
      "channel_uuid": "@jwp_",
      "success": true
    },
    {
      "channel_talk_id": 194285, // 카카오톡 회원번호 응답 권한 필요
      "channel_public_id": "_vxfxm",
      "channel_uuid": "@5460866932883",
      "success": false,
      "failure_msg": "BLOCKED_CHANNEL"
    }
  ]
}

응답: 실패, 앱에 설정되지 않은 카카오톡 채널을 대상으로 요청

// HTTP/1.1 400 Bad Request
{
  "msg": "invalid channel_ids. check out your Kakao Talk Channels on developers.kakao.com.",
  "code": -819
}

사이드 메뉴

오픈 문서

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

인공지능

플랫폼 API

API 제공

전용 API

어드민 API

더 보기

REST API

카카오톡 채널 프로필 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

TalkChannelProfile

예제

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

응답

응답: 실패, 잘못된 카카오톡 채널 프로필 ID

카카오톡 채널 관계 조회

기본 정보

요청: 액세스 토큰 방식

헤더

쿼리 파라미터

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

헤더

쿼리 파라미터

요청: 위임 방식

헤더

쿼리 파라미터

응답

본문

ChannelRelation

예제

요청: 액세스 토큰 방식

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

요청: 위임 방식

요청: 위임 방식

요청: 위임 방식

응답

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

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

TalkChannelsResult

TalkChannelRelation

예제

요청

응답

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

카카오톡 채널 친구 추가

기본 정보

요청: 액세스 토큰 방식

헤더

본문

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

헤더

본문

요청: 위임 방식

헤더

본문

응답

본문

Channel

예제

요청: 액세스 토큰 방식

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

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

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

요청: 위임 방식

응답