사이드 메뉴
시작하기
로그인
커뮤니케이션
광고
제휴사 전용 API
이 문서는 제휴사 전용 카카오톡 채널 API 사용 방법을 안내합니다.
제휴사 전용
제휴사 전용 API는 별도 사용 협의가 완료된 서비스 앱에만 제공하는 기능입니다. 이 문서는 해당 기능 사용 권한이 있는 앱에 한해 유효한 정보를 담고 있습니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 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 |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| channel_public_id | String | 카카오톡 채널의 프로필 ID(Profile 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 |
curl -v -G GET "https://kapi.kakao.com/v1/api/talk/channels/profile" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d 'channel_public_ids=["_frxjem","_xnrxjem"]'
응답: 성공
[{"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
{"msg": "invalid channel ids. channel_public_ids=[${CHANNEL_PUBLIC_IDS}]","code": -2}
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | https://kapi.kakao.com/v1/api/talk/channels/add | 액세스 토큰 서비스 앱 어드민 키 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요 | 어드민 키 카카오 로그인 활성화 | 필요 | - |
특정 카카오톡 채널을 사용자의 친구로 추가합니다.
카카오톡 채널 친구 추가 문구 안내
카카오톡 채널 친구 추가 API를 사용해 사용자에게 카카오톡 채널을 친구로 추가하려는 경우, 정보통신망법 제50조를 기반으로 하는 KISA 가이드라인에 따라 반드시 지정된 문구로 안내해야 합니다.(참고) 사용 가능한 문구는 아래와 같습니다. 기본 문구: [카카오톡 채널 이름]의 광고와 마케팅 메시지를 카카오톡으로 받습니다.
- 축약형
- [카카오톡 채널 이름]의 광고와 마케팅 메시지를 카카오톡으로 받기
- [카카오톡 채널 이름]의 광고 메시지를 카카오톡으로 받기
사용자가 해당 카카오톡 채널을 차단한 상태일 경우, 차단을 해제하고 친구 추가합니다.
대상 카카오톡 채널은 아래 조건을 만족해야 합니다.
- 앱에 설정된 카카오톡 채널
- 공개된 카카오톡 채널
헤더에 원하는 인증 정보를 담아 POST로 요청하고, 성공 시 사용자의 친구로 추가된 카카오톡 채널의 정보를 받습니다. 여러 개의 카카오톡 채널을 추가하려면 요청 시 카카오톡 채널의 프로필 ID 목록(channel_public_ids)을 파라미터로 전달해야 합니다.
요청 시 channel_public_ids 값을 전달하지 않으면 앱과 연결 또는 수동 등록된 카카오톡 채널이 친구로 추가됩니다. 단, 앱과 연결 또는 수동 등록된 카카오톡 채널이 여러 개일 경우, 에러가 발생하므로 채널이 여러 개일 경우에는 반드시 channel_public_ids 값을 전달해야 합니다. 여러 개의 카카오톡 채널을 추가 요청한 경우, 앱에 연결된 채널 목록을 확인하여 모두 연결 또는 수동 등록되어 있는 카카오톡 채널인 경우에만 요청이 허용됩니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
- 여러 개의 카카오톡 채널을 추가 요청할 경우,
channel_public_ids파라미터를 필수로 전달해야 합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| channel_public_ids | String[] | 사용자의 친구로 추가할 카카오톡 채널의 프로필 ID 목록 참고: 카카오톡 채널 프로필 ID 확인 방법 | X |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 여러 개의 카카오톡 채널을 추가 요청할 경우,
channel_public_ids파라미터를 필수로 전달해야 합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 카카오톡 채널을 친구로 추가할 사용자의 ID | O |
| target_id_type | String | target_id의 타입, 아래로 고정: user_id: 회원번호 | O |
| channel_public_ids | String[] | 사용자의 친구로 추가할 카카오톡 채널의 프로필 ID 목록 참고: 카카오톡 채널 프로필 ID 확인 방법 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| user_id | Integer | 사용자 회원번호 | X |
| channels | Channel[] | 친구로 추가한 카카오톡 채널 정보 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| channel_uuid | String | 카카오톡 채널의 카카오톡 검색용 ID | O |
| channel_public_id | String | 사용자의 친구로 추가된 카카오톡 채널의 프로필 ID | O |
| result_msg | String | 친구 추가 성공 또는 실패 원인을 담은 메시지 | O |
요청: 액세스 토큰 방식
curl -v -X POST "https://kapi.kakao.com/v1/api/talk/channels/add" \-H "Authorization: Bearer ${ACCESS_TOKEN}" \-d 'channel_public_ids=["_frxjem","_xnrxjem"]'
요청: 서비스 앱 어드민 키 방식
curl -v -X POST "https://kapi.kakao.com/v1/api/talk/channels/add" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=1376016924426684995" \-d "target_id_type=user_id" \-d 'channel_public_ids=["_frxjem","_xnrxjem"]'
응답: 성공
{"user_id": 1376016924426879191,"channels": [{"channel_uuid": "@채널A","channel_public_id": "_frxjem","result_msg": "SUCCESS"},{"channel_uuid": "@채널B","channel_public_id": "_xnrxjem","result_msg": "SUCCESS"}]}
응답: 실패, 사용자가 카카오톡을 이용하지 않음
// HTTP/1.1 400 Bad Request{"code": -501,"msg": "given account is not connected to any talk user."}
응답: 실패, 미성년자 또는 본인인증 미완료 계정으로 연령제한 카카오톡 채널 추가
// HTTP/1.1 401 Unauthorized{"code": -406,"msg": "Unable to add to this channel. age verification is required."}