본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

관련사이트

사이드 메뉴

플랫폼 API

API 제공

전용 API

어드민 API

이 문서는 API 플랫폼 관리 REST API의 사용 방법을 안내합니다.

메서드URL인증 방식
POST카카오
http://kapi.kakao.com/v1/internal/user/create_or_update
공동체
https://kapi.kakao.com/v1/internal/user/create_or_update
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키필요: 연결 없음-

앱과 연결되지 않은 사용자에게 토큰 발급 시, 사용자를 연결 또는 연결 대기 상태로 변경하고 회원번호를 생성합니다. capri-oauth2에서 위임 방식으로 사용합니다. 이 API는 서비스 앱의 로그인 시 앱 자동 연결 설정에 따라 아래와 같이 동작합니다.

  • 자동 연결: 사용자를 연결(REGISTERED) 상태로 변경하고 회원번호 반환, 프로필 정보 덤프(Dump) 생성
    • 연령인증을 사용하는 앱은 자동 연결로 설정할 수 없음
    • 연령인증과 자동 연결이 함께 설정돼 있는 앱의 요청은 -405 또는 -406 에러가 발생할 수 있으며, KAUTH 서버로 에러 전달
  • 수동 연결: 사용자를 연결 대기(PREREGISTERED) 상태로 변경하고 회원번호 반환

헤더에 capri-oauth2 앱의 어드민 키를 담아 GET 또는 POST로 요청합니다. 파라미터로 사용자의 연결 상태, 동의 내역을 전달할 수 있습니다. 요청이 성공하면 응답은 사용자의 회원번호를 포함합니다.

  • 내부 URL 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
이름타입설명필수
target_app_keyString서비스 앱 키O
account_idString사용자의 카카오계정 IDO
account_typeString계정 타입, KAKAO로 고정O
user_statusString사용자의 연결 상태 지정
REGISTERED: 연결
PREREGISTERED: 연결 대기
X
allowed_scopesString[]사용자가 동의한 동의항목 ID 목록X
agreement_codesString[]사용자가 동의한 기타 동의항목 코드 목록X
allowed_service_termsString[]사용자가 동의한 서비스 약관 목록X
allowed_channel_talk_idsLong[]사용자가 카카오톡 채널 추가에 동의한 채널 ID 목록X
synchedBoolean서비스 앱의 카카오싱크 간편가입 설정 여부X
channelString1회성 제공 동의 타입
(예: bizplugin)
X
channel_extString1회성 제공 동의항목의 동의 내역을 앱의 동의항목 동의 내역과 함께 사용하는지 여부
merged_scope: 앱의 동의항목과 함께 사용
scope: 1회성 제공 동의항목만 사용
X
이름타입설명필수
idLong회원번호O
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 사용자 카카오계정 ID(account_id)
    • 계정 타입(KAKAO)
curl -v -X POST "http://kapi.kakao.com/v1/internal/user/create_or_update" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "account_id=2137162" \
-d "account_type=KAKAO"
// HTTP/1.1 200 OK
{
"id": 12345
}
메서드URL인증 방식
POST카카오
http://kapi.kakao.com/v2/internal/kakaolink/talk/message/generate
공동체
https://kapi.kakao.com/v2/internal/kakaolink/talk/message/generate
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키--

사용자 정의 템플릿의 설정을 바탕으로 메시지 템플릿 JSON 객체를 생성합니다. 나에게 사용자 정의 템플릿으로 메시지 발송과 같이 사용자 정의 템플릿의 ID로 메시지 전송을 요청할 경우, 실제 전송 가능한 메시지 템플릿 JSON 객체를 생성하는 데 사용합니다.

헤더에 플랫폼 앱 어드민 키를 담아 GET 또는 POST로 요청합니다. 사용자 인자를 포함한 사용자 정의 템플릿은 각 키에 해당하는 값을 전달해야 합니다. 요청이 성공하면 응답은 메시지 템플릿 JSON 객체를 반환합니다. 메시지 템플릿의 각 구성 요소는 사용자 정의 템플릿의 설정과 사용자 인자 값을 바탕으로 구성됩니다. 단, remaining_keys에 포함된 키는 메시지 발송 시 채팅 서버(BO)에서 값이 채워집니다.

  • 내부 URL 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
이름타입설명필수
target_app_keyString서비스 앱 키

중요: target_app_keytarget_app_id 한 가지 필수
O(Optional)
target_app_idString서비스 앱 ID

중요: target_app_keytarget_app_id 한 가지 필수
O(Optional)
link_verString카카오링크 버전
4.0으로 고정
O
template_idString사용자 정의 템플릿 IDO
template_argsJSON사용자 정의 템플릿에 사용된 사용자 인자의 키와 값, 또는 웹훅에 전달받을 키와 값을 포함한 JSON 객체
웹훅에 전달받을 키와 값을 포함할 경우, 키가 event_ 또는 EVENT_로 시작해야 함
(예: ${EVENT_ID}, ${event_sid})
X
app_verString통계용, 서비스 앱 버전X
sender_talk_user_idLong통계용, 메시지를 보내는 사용자의 카카오톡 회원번호O
receiver_chat_room_idLong통계용, 메시지를 받는 카카오톡 채팅방의 IDX
receiver_chat_room_mem_countInteger통계용, 메시지를 받는 채팅방 멤버 수
  • 0: 나와의 채팅방
  • 1: 1:1 채팅방
  • 1 이상 수: 그룹 채팅방
X
receiver_talk_user_idLong통계용, 메시지를 받는 사용자의 카카오톡 회원번호
1:1 채팅방인 경우에만 사용
X
extrasJSON통계용, 추가 정보
(예: network_type, caller_ip, chat_room_mem_count)

중요: lcba 키 포함 시, 해당 키 값을 포함해 카카오톡 공유 웹훅 전달
X
이름타입설명필수
complete_msgJSON메시지 템플릿 JSON 객체O
remaining_keysJSON[]채팅 서버(BO)에서 값이 채워질 키 목록X
callbackLinkCallbackInfo웹훅 정보X
이름타입설명필수
urlString웹훅을 받을 URLX
methodString웹훅에 사용해야 할 메서드, GET 또는 POSTX
argsJSON사용자 정의 템플릿 ID, 채팅방 타입, template_args로 전달했던 키와 값X
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 카카오링크 버전(link_ver)
    • 사용자 정의 템플릿 ID(template_id)
    • 메시지를 받는 사용자의 카카오톡 회원번호(receiver_talk_id)
    • 메시지를 받는 채팅방의 ID(receiver_chat_room_id)
    • 메시지를 받는 채팅방의 멤버 수(receiver_chat_room_mem_count)
    • 사용자 정의 템플릿에 사용된 사용자 인자의 키와 값(template_args)
    • 추가 정보(extras)
curl -v -X POST "http://kapi.kakao.com/v2/internal/kakaolink/talk/message/generate" \
-H "Authorization: KakaoAK add4119781bef3c4eee911d5ef0dadee" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "link_ver=4.0" \
-d "template_id=7863" \
-d "sender_talk_user_id=85510" \
-d "receiver_talk_id=700003427" \
-d "receiver_chat_room_id=111" \
-d "receiver_chat_room_mem_count=1" \
--data-urlencode 'template_args={"${iphoneAppParam}":"key1=value1", "${androidAppParam}":"key2=value2","${senderParam}":"Muji"}' \
--data-urlencode 'extras={"chat_type":"MemoChat","caller_ip":"::ffff:211.59.202.119","network_type":"WIFI"}'
// HTTP/1.1 200 OK
{
"complete_msg": {
"P": {
"TP": "Feed",
"ME": "${ME}",
"SID": "capri_259500",
"DID": "7863",
"SNM": "eagerlevel2_19_rich_board_game",
"SIC": "http://api1-kage.kakao.com/14/dn/ZSaDggnBui/P4OUogTxkSubXGUardt1ak/o.jpg",
"SST": {
"SR": "receiver",
"L": {
"LMO": "https://apps.kakao.com/feedblock?lang=${DENY_MESSAGE_LANG}&target_app_key=28c9e9852fc4102af29517b8b9b36c14",
"LAT": "inweb",
"LAA": true
}
},
"L": {
"LCA": "kakao28c9e9852fc4102af29517b8b9b36c14://kakaolink",
"LCI": "kakao28c9e9852fc4102af29517b8b9b36c14://kakaolink",
"LMO": "http://www.kakao.com"
},
"LA": "market://details?id=com.kakao.game.rich.test&from=feed",
"LI": "https://itunes.apple.com/app/id-1?from=feed",
"VA": "6.0.0",
"VI": "5.9.7",
"VW": "2.5.1",
"VM": "2.2.0",
"FW": true
},
"C": {
"TI": {
"TD": {
"T": "group chat message"
}
},
"BUL": [
{
"BU": {
"T": "앱으로 이동"
},
"L": {
"LCA": "kakao28c9e9852fc4102af29517b8b9b36c14://kakaolink?key2=value2",
"LCI": "kakao28c9e9852fc4102af29517b8b9b36c14://kakaolink?key1=value1"
}
}
]
}
},
"remaining_keys": ["${ME}"],
"callback": {
"url": "http://www.kakao.com",
"method": "POST",
"args": {
"EVENT_ID": "12",
"CHAT_TYPE": "MemoChat",
"event_sid": "ab12dsdggh",
"TEMPLATE_ID": 7863
}
}
}
메서드URL인증 방식
POST카카오
http://kapi.kakao.com/v2/internal/kakaolink/talk/message/checkquota
공동체
https://kapi.kakao.com/v2/internal/kakaolink/talk/message/checkquota
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키--

카카오톡 공유 요청에 대한 쿼터(Quota)를 확인합니다. 일반 채팅, 카카오톡 채널 채팅의 비즈니스 로직을 담당하는 채팅 서버(BO)가 사용합니다. 채팅 서버는 메시지 템플릿 JSON이 생성된 후, 메시지 전송이 가능한지 쿼터를 확인합니다.

헤더에 채팅 서버의 앱 어드민 키를 담아 GET 또는 POST로 요청합니다. 요청 성공 시 응답 본문은 비어있습니다. origin_json 키와 값이 올바르지 않으면 IllegalParamException이 발생할 수 있습니다.

  • 내부 URL 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
이름타입설명필수
origin_jsonJSON메시지 전송 요청이 전달된 경로
서버인 경우 ai, ti 키와 값 포함
클라이언트인 경우 ak, ti, lv, av 키와 값 포함
O
sender_talk_user_idLong통계용, 메시지를 보낸 사용자의 카카오톡 회원번호X
receiver_chat_room_idLong통계용, 메시지를 받는 채팅방의 IDX
receiver_chat_room_mem_countInteger통계용, 메시지를 받는 채팅방의 멤버 수
  • 0: 나와의 채팅방
  • 1: 1:1 채팅방
1 이상 수: 그룹 채팅방
X
receiver_talk_user_idLong통계용, 메시지를 받는 사용자의 카카오톡 회원번호
1:1 채팅방인 경우에만 사용
X
extrasJSON통계용, 추가 정보
(예: network_type, caller_ip, chat_room_mem_count)
X
  • 파라미터
    • 메시지 전송 요청이 전달된 경로(origin_json)
    • 메시지를 보낸 사용자의 카카오톡 회원번호(sender_talk_user_id)
    • 메시지를 받는 채팅방의 ID(receiver_chat_room_id)
curl -v -X POST "http://kapi.kakao.com/v2/internal/kakaolink/talk/message/checkquota" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-d 'origin_json={"ti":"123","ai":"345"}' \
-d "sender_talk_user_id=1234" \
-d "receiver_chat_room_id=1234"
HTTP/1.1 200 OK
// HTTP/1.1 401 Unauthorized
{
"msg": "need more information to authenticate",
"code": -401
}
메서드URL인증 방식
POST카카오
http://kapi.kakao.com/v1/internal/kakaolink/talk/oscontent/checkquota
공동체
https://kapi.kakao.com/v1/internal/kakaolink/talk/oscontent/checkquota
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키--

OS 공유 요청에 대한 쿼터(Quota)를 확인합니다. OS 공유 회수 제한을 초과하지 않았는지 쿼터를 확인합니다.

헤더에 플랫폼 앱 어드민 키를 담아 GET 또는 POST로 요청합니다. 요청 성공 시 응답 본문은 비어있습니다.

  • 내부 URL 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
이름타입설명필수
app_idInteger서비스 앱의 패키지명 또는 번들 ID
(예: com.kakao.sample)
O
api_verStringAPI 버전, 3.0으로 고정O
link_verString카카오링크 버전, 3.5-osc로 고정O
sender_talk_user_idInteger메시지를 보낸 사용자의 카카오톡 회원번호X
receiver_chat_room_idInteger메시지를 받는 채팅방의 IDX
receiver_chat_room_mem_countInteger통계용, 메시지를 받는 채팅방 멤버 수
  • 0: 나와의 채팅방
  • 1: 1:1 채팅방
1 이상 수: 그룹 채팅방
X
receiver_talk_user_idInteger메시지를 받는 사용자의 카카오톡 회원번호X
extrasJSON통계용, 추가 정보
(예: network_type, caller_ip, chat_room_mem_count)
X
typeString말풍선 로그 타입, 아래 중 하나
  • TEXT
  • PHOTO
  • VIDEO
  • AUDIO
  • FILE
X
objsJSON말풍선 로그에 포함할 데이터
type에 따라 지정된 키와 값 사용 가능
(참고: ChatLogTypes )
O
  • 파라미터
    • 서비스 앱의 ID(app_id)
    • API 버전(api_ver)
    • 카카오링크 버전(link_ver)
    • 메시지를 보낸 사용자의 카카오톡 회원번호(sender_talk_user_id)
    • 카카오링크 규격에 따라 정의된 키와 값(objs)
curl -v -X POST "http://kapi.kakao.com/v1/internal/kakaolink/talk/oscontent/checkquota" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-d "app_id=com.kakao.sample" \
-d "api_ver=3.0" \
-d "link_ver=3.5~osc" \
-d "sender_talk_user_id=1234" \
-d 'objs={"${KEY}":"${VALUE}"}'
HTTP/1.1 200 OK
메서드URL인증 방식
POST카카오
http://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/validate
공동체
https://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/validate
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키--

카카오톡 채널 메시지 발송 대상 목록의 유효성을 검증합니다. 카카오디벨로퍼스 채널 메시지 발송기에서 사용합니다.

헤더에 채널 메시지 발송기 앱의 어드민 키를 담아 POST로 요청합니다. 채널 메시지 전송에 쓸 사용자 정의 템플릿 ID와 발송 대상 목록을 반드시 전달해야 합니다. 요청이 성공하면 응답은 발송 대상 목록의 유효성 검증 결과를 포함합니다.

  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_app_keyString서비스 앱 키O
channel_talk_idInteger카카오톡 채널의 카카오톡 회원번호O
template_idInteger사용자 정의 템플릿 IDO
receiver_id_typeString발송 대상 ID 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O
receiver_file_urlString발송 대상 목록이 담긴 파일 URL
(예: /capri/chmsg/receiver_ids_100k.csv)
O
이름타입설명필수
total_countInteger발송 대상 목록의 총 발송 대상 수O
successful_countInteger발송 대상 목록 내 상위 100명 중 유효한 발송 대상 수O
failed_countInteger발송 대상 목록 내 상위 100명 중 유효하지 않은 발송 대상 수O
failed_receiversFailedReceivers[]유효하지 않은 발송 대상이 있는 경우, 각각의 원인X
이름타입설명필수
input_idLong발송 대상의 IDO
error_codeInteger에러 코드O
causeString에러 유형O
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 카카오톡 채널의 카카오톡 회원번호(channel_talk_id)
    • 사용자 정의 템플릿 ID(template_id)
    • 발송 대상 ID 타입(receiver_id_type)
    • 발송 대상 목록이 담긴 파일 URL(receiver_file_url)
curl -v -X POST "https://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/validate" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
--data-urlencode "target_app_key=${SERVICE_APP_KEY}" \
--data-urlencode "channel_talk_id=228697" \
--data-urlencode "template_id=1244" \
--data-urlencode "receiver_id_type=account_id" \
--data-urlencode "receiver_file_url=${URL}"
// HTTP/1.1 200 OK
{
"total_count": 100,
"successful_count": 98,
"failed_count": 2,
"failed_receivers": [
{
"input_id": 1111,
"error_code": -1,
"cause": "InternalErrorException"
},
{
"input_id": 1153,
"error_code": -1,
"cause": "InternalErrorException"
}
]
}
메서드URL인증 방식
POST카카오
http://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/send
공동체
https://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/send
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키--

다수의 발송 대상에 대한 채널 메시지 발송을 요청합니다. 카카오디벨로퍼스 채널 메시지 발송기에서 사용합니다.

헤더에 채널 메시지 발송기 앱의 어드민 키를 담아 POST로 요청합니다. 채널 메시지 전송에 쓸 사용자 정의 템플릿 ID와 발송 대상 목록을 반드시 전달해야 합니다. 요청이 성공하면 응답은 발송건에 대한 task_id를 포함합니다.

  • 내부 URL 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
이름타입설명필수
target_app_keyString서비스 앱 키O
channel_talk_idLong카카오톡 채널의 카카오톡 회원번호O
template_idInteger사용자 정의 템플릿 IDO
sender_developer_idLong채널 메시지 발송을 요청하는 개발자 계정 IDO
receiver_id_typeString발송 대상 ID 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O
receiver_file_urlString발송 대상 목록이 담긴 파일 URL
(예: /capri/chmsg/receiver_ids_100k.csv)
O
이름타입설명필수
task_idInteger발송 작업 고유 번호O
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 카카오톡 채널 프로필 ID(channel_talk_id)
    • 사용자 정의 템플릿 ID(template_id)
    • 채널 메시지 발송을 요청하는 개발자 계정 ID(sender_developer_id)
    • 발송 대상 ID 타입(receiver_id_type)
    • 발송 대상 목록이 담긴 파일 URL(receiver_file_url)
curl -v -X POST "http://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/send" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "channel_talk_id=111" \
-d "template_id=1234" \
-d "sender_developer_id=5555" \
-d "receiver_id_type=account_id" \
-d "receiver_file_url=${URL}"
// HTTP/1.1 200 OK
{
"task_id": 12
}
메서드URL인증 방식
POST카카오
http://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/operation
공동체
https://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/operation
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키--

카카오톡 채널 메시지 대량 발송을 중단합니다. 카카오디벨로퍼스 채널 메시지 발송기에서 사용합니다.

헤더에 채널 메시지 발송기 앱의 어드민 키를 담아 POST로 요청합니다. 메시지 대량 발송 응답으로 받은 task_id를 반드시 포함해야 합니다. operationSTOP으로 지정합니다. 요청이 성공하면 응답은 중단된 발송 작업의 task_id를 포함합니다.

  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
이름타입설명필수
target_app_keyString서비스 앱 키O
task_idInteger발송 작업 고유 번호O
operationString요청할 동작, STOP으로 고정O
이름타입설명필수
task_idInteger발송 작업 고유 번호O
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 발송 작업 고유 번호(task_id)
    • 요청할 동작(operation): STOP
curl -v -X POST "http://kapi.kakao.com/v1/internal/talk/channels/broadcast/message/operation" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
--data-urlencode "target_app_key=${SERVICE_APP_KEY}" \
--data-urlencode "task_id=91" \
--data-urlencode "operation=STOP"
// HTTP/1.1 200 OK
{
"task_id": 12
}
// HTTP/1.1 400 Bad Request
{
"code": -2,
"msg": "IllegalParamException"
}
메서드URL인증 방식
GET카카오
http://kapi.kakao.com/v1/internal/friends/sdk
공동체
https://kapi.kakao.com/v1/internal/friends/sdk
외부
https://kapi.kakao.com/v1/friends/sdk
액세스 토큰
위임

피커로 제공할 사용자의 카카오톡 친구 목록을 가져옵니다. REST API로 제공하는 카카오톡 친구 목록 조회와는 아래와 같은 차이가 있습니다.

헤더에 원하는 인증 방식의 정보를 담아 GET으로 요청합니다. 요청 성공 시 응답은 사용자의 카카오톡 프로필과 고유 ID, 친구 목록을 포함합니다. 친구 목록 중 일부 사용자의 프로필은 앱의 권한, 필요한 동의항목 동의 여부에 따라 포함되지 않을 수 있습니다.

  • Kakao SDK for Android, iOS에서 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
KAKA: ${KEY}/${VALUE}
KA 헤더 정보
O
이름타입설명필수
friend_filterString친구 목록 필터링 옵션, 아래 중 하나
  • none: 전체 친구
  • registered: 앱에 연결된 친구
  • invitable: 앱에 연결되지 않은 친구
(기본값: none)
X
friend_orderString친구 목록 정렬 기준, 아래 중 하나
  • favorite: 즐겨찾기
  • nickname: 닉네임
(기본값: nickname)

참고: 카카오 리치보드게임의 경우, 별도 기준(age)을 적용해 미성년자 제외 및 성인 우선 정렬
X
offsetInteger가져올 친구 목록의 시작 지점(기본값: 0, 처음부터)X
limitInteger한 페이지에 가져올 친구의 수(기본값: 100, 최대 10000)X
orderString친구 리스트 정렬 순서, 아래 중 하나
  • asc: 오름차순
  • desc: 내림차순
(기본값: asc)
X
  • Kakao SDK for JavaScript에서 내부 URL 요청 시 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
KAKA: ${KEY}/${VALUE}
KA 헤더 정보
O
이름타입설명필수
target_access_tokenString사용자 액세스 토큰
JavaScript 키 및 REST API 키로 발급받은 액세스 토큰만 허용
O
target_app_keyString서비스 앱 키O
friend_filterString친구 목록 필터링 옵션, 아래 중 하나
  • none: 전체 친구
  • registered: 앱에 연결된 친구
  • invitable: 앱에 연결되지 않은 친구
(기본값: none)
X
friend_orderString친구 목록 정렬 기준, 아래 중 하나
  • favorite: 즐겨찾기
  • nickname: 닉네임
(기본값: nickname)

참고: 카카오 리치보드게임의 경우, 별도 기준(age)을 적용해 미성년자 제외 및 성인 우선 정렬
X
offsetInteger가져올 친구 목록의 시작 지점(기본값: 0, 처음부터)X
limitInteger한 페이지에 가져올 친구의 수(기본값: 100, 최대 10000)X
orderString친구 리스트 정렬 순서, 아래 중 하나
  • asc: 오름차순
  • desc: 내림차순
(기본값: asc)
X
return_urlString선택한 친구 정보를 받을 서비스 URLX
  • 일부 필드는 내부 URL 요청 시에만 제공됩니다.
이름타입설명
display_all_profileBoolean미동의 친구 목록 제공 여부
meMe사용자 정보
friendsFriends[]친구 목록
이름타입설명필수
idLong사용자 회원번호O
uuidString사용자 고유 IDO
profile_nicknameString카카오톡 프로필 닉네임
profile_thumbnail_imageString카카오톡 프로필 썸네일(Thumbnail) 이미지 URL
이름타입설명
elementsFriend[]친구 목록
total_countInteger친구 수
before_urlString친구 목록 이전 페이지 URL
after_urlString친구 목록 다음 페이지 URL
favorite_countInteger즐겨찾기 친구 수
이름타입설명필수
profile_nicknameString친구의 대표 프로필 닉네임

참고: 카카오톡 프로필 정보 우선순위
X
profile_thumbnail_imageString친구의 대표 썸네일(Thumbnail) 이미지 URL

참고: 카카오톡 프로필 정보 우선순위, 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리
X
uuidString사용자 고유 ID

참고: ID 종류
O
talk_osString카카오톡 가입 기기의 OS 정보, 아래 중 하나
  • android: 안드로이드
  • ios: iOS
X
account_idInteger카카오계정이 있는 친구의 카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유, 내부 URL 요청
X
talk_user_idLong친구의 카카오톡 회원번호

제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유, 내부 URL 요청
X
app_registeredBoolean앱 연결 여부
relationRelation카카오톡 사용자와 친구의 관계X
favoriteBoolean카카오톡의 친구 즐겨찾기 여부
* allowed_msg: Deprecated, 메시지 수신 허용 여부, 프로필 공개 설정 기능 추가에 따라 더 이상 사용되지 않음
이름타입설명필수
talkString친구와 내가 카카오톡 친구인지 여부, 아래 중 하나
  • friend: 친구
  • no_friend: 친구 아님
  • N/A: 카카오톡 친구 요청이 아니어서 알 수 없음
X
talk_friend_statusInt카카오톡 친구인 경우 친구와 나의 카카오톡의 친구 관계, 아래 중 하나
  • 3: MUTUAL, 서로 친구
  • 2: IN_CONTACT, 나에게만 친구 중 연락처에 있는 친구
  • 1: NOT_IN_CONTACT, 나에게만 친구 중 연락처에 없는 친구
카카오톡의 친구 관계 참고

제공 조건: 내부 URL 요청 시
X
  • 파라미터
    • 없음
curl -v -G "https://kapi.kakao.com/v1/friends/sdk" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "KA: sdk/1.0.32 sdk_type/swift os/ios-8.3 lang/ko-KR res/320x568 device/iPhone origin/com.sample.test"
  • 파라미터
    • 사용자 액세스 토큰(target_access_token)
    • 서비스 앱 키(target_app_key)
curl -v -G "http://kapi.kakao.com/v1/internal/friends/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "KA: sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com" \
-d "target_access_token=${ACCESS_TOKEN}" \
-d "target_app_key=${SERVICE_APP_KEY}"
// HTTP/1.1 200 OK
{
"display_all_profile": true,
"me": {
"profile_nickname": "Sample",
"profile_thumbnail_image": "",
"id": 143251,
"uuid": "Vm5fZ1VgTH1EcEB5SmZUZFJgU2Yu"
},
"friends": {
"elements": [
{
"profile_nickname": "피커테스트1",
"profile_thumbnail_image": "",
"allowed_msg": true,
"uuid": "VmdSYFBgVHhKeE10QHZaaFhuXG9aEQ",
"app_registered": false,
"relation": {
"talk": "friend",
"story": "N/A"
},
"favorite": false
}
// ...
],
"total_count": 10,
"after_url": null,
"favorite_count": 2
}
}
// HTTP/1.1 200 OK
{
"display_all_profile": true,
"me": {
"profile_nickname": "Sample",
"profile_thumbnail_image": "https://p.kakaocdn.net/th/talkp/wkf2zw13qr/ihkqX6mTuWqvNYtxSjPYjk/xv98j6_110x110_c.jpg",
"id": 1376016924429759243,
"uuid": "YlBhUmVUYlB8S3tLektyS39NYVhvWGhfbg0"
},
"friends": {
"elements": [
{
"profile_nickname": "Test",
"profile_thumbnail_image": "",
"talk_os": "android",
"allowed_msg": true,
"uuid": "YlptVGxca0dwQHBAckF3Q3NfZlFmVmFQBg",
"account_id": 879807,
"talk_user_id": 700023640,
"app_registered": false,
"relation": {
"talk": "friend",
"story": "N/A",
"talk_friend_status": 2
},
"favorite": false
}
// ...
],
"total_count": 5,
"after_url": null,
"favorite_count": 0
}
}
메서드URL인증 방식
GET카카오
http://kapi.kakao.com/v1/internal/talk/chat/list/sdk
공동체
https://kapi.kakao.com/v1/internal/talk/chat/list/sdk
위임

피커로 제공할 사용자의 카카오톡 채팅방 목록을 가져옵니다. REST API로 제공하는 인하우스 앱: 채팅방 목록 조회와는 아래와 같은 차이가 있습니다.

  • Kakao SDK 전용 API로, 요청 검증을 위한 KA 헤더 값 필수
  • 내부 URL 요청 시 return_url 파라미터 제공

헤더에 플랫폼 앱 어드민 키를 담아 GET으로 요청합니다. 요청 성공 시 응답은 사용자의 카카오톡 채팅방 목록을 포함합니다.

이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
KAKA: ${KEY}/${VALUE}
KA 헤더 정보
O
이름타입설명필수
target_access_tokenString사용자 액세스 토큰
JavaScript 키 및 REST API 키로 발급받은 액세스 토큰만 허용
O
target_app_keyString서비스 앱 키O
return_urlString선택한 채팅방 정보를 받을 서비스 URLX
이름타입설명필수
elementsChatInfo[]각 채팅방 정보로 구성된 목록X
total_countInteger전체 채팅방 수(최대 30)O
before_urlString채팅방 목록 현재 페이지의 이전 페이지 URLX
after_urlString채팅방 목록 현재 페이지의 다음 페이지 URLX
이름타입설명필수
idLong채팅방 IDO
titleString채팅방 이름X
title_sourceString채팅방 이름 타입, 아래 중 하나
  • user: 사용자가 설정한 이름
  • chat: 채팅방 생성 시 설정된 이름
  • default: 별도 설정 없음
O
image_urlString채팅방 이미지
채팅방에 지정된 이미지가 없어 응답에 포함되지 않은 경우 display_member_images를 참조할 것
X
member_countInteger채팅방 멤버 수X
display_member_imagesString[]채팅방 멤버 중 최대 5명의 썸네일 이미지 목록

중요: 멤버의 프로필이 존재하지 않을 경우 응답에 포함되지 않을 수 있음
X
chat_room_typeString채팅방 타입, 아래 중 하나
  • MemoChat: 나와의 채팅방
  • DirectChat: 다른 사용자와의 1:1 채팅방
  • MultiChat: 다른 사용자들과의 그룹 채팅방
  • OpenDirectChat: 1:1 오픈채팅방
  • OpenMultiChat: 그룹 오픈채팅방
O
  • 파라미터
    • 사용자 액세스 토큰(target_access_token)
    • 서비스 앱 키(target_app_key)
curl -v -G "http://kapi.kakao.com/v1/internal/talk/chat/list/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "KA: sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com" \
-d "target_access_token=${ACCESS_TOKEN}" \
-d "target_app_key=${SERVICE_APP_KEY}"
// HTTP/1.1 200 OK
{
"elements": [
{
"id": 355354313646591,
"title": "test",
"member_count": 2,
"display_member_images": [],
"chat_type": "regular",
"chat_room_type": "DirectChat",
"title_source": "default"
}
// ...
],
"total_count": 9,
"after_url": null
}
메서드URL인증 방식
GET카카오
http://kapi.kakao.com/v1/internal/talk/members/sdk
공동체
https://kapi.kakao.com/v1/internal/talk/members/sdk
위임

피커로 제공할 사용자의 특정 카카오톡 채팅방 멤버 목록을 가져옵니다. REST API로 제공하는 인하우스 앱: 채팅방 목록 조회와는 아래와 같은 차이가 있습니다.

  • Kakao SDK 전용 API로, 요청 검증을 위한 KA 헤더 값 필수
  • 내부 URL 요청 시 return_url 파라미터 제공

헤더에 플랫폼 앱 어드민 키를 담아 GET으로 요청합니다. 요청 성공 시 응답은 지정한 채팅방의 멤버 정보를 포함합니다.

이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
KAKA: ${KEY}/${VALUE}
KA 헤더 정보
O
이름타입설명필수
target_access_tokenString사용자 액세스 토큰
JavaScript 키 및 REST API 키로 발급받은 액세스 토큰만 허용
O
target_app_keyString서비스 앱 키O
chat_idLong채팅방 IDO
return_urlString선택한 채팅방 멤버 정보를 받을 서비스 URLX
이름타입설명필수
display_all_profileBoolean미동의 친구 목록 제공 여부O
chat_membersChatMembers채팅방 멤버 정보
active_members_countInteger채팅방 멤버 수X
active_friends_countInteger채팅방 멤버 중 카카오톡 친구의 수X
이름타입설명필수
idLong회원번호X
uuidString해당 앱에서의 사용자 고유 아이디, 연결 상태와 관계 없으며 일반적으로 메시지 전송 시 사용O
is_friendBoolean친구와 내가 카카오톡 친구인지 여부X
app_registeredBoolean앱 연결 여부X
nicknameString닉네임X
thumbnail_imageString썸네일 이미지

참고: 프로필 변경 시 기존 프로필 이미지 URL 삭제 처리
X
* msg_blocked: Deprecated, 메시지 수신 허용 여부, 프로필 공개 설정 기능 추가에 따라 더 이상 사용되지 않음
  • 파라미터
    • 사용자 액세스 토큰(target_access_token)
    • 서비스 앱 키(target_app_key)
    • 채팅방 ID(chat_id)
curl -v -G "http://kapi.kakao.com/v1/internal/talk/members/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "KA: sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com" \
-d "target_access_token=${ACCESS_TOKEN}" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "chat_id=355354313646591"
// HTTP/1.1 200 OK
{
"display_all_profile": true,
"chat_members": {
"type": "DirectChat",
"members": [
{
"id": 1376016924430969676,
"uuid": "YlBmU2NSZFxwR3dHdk58THRMYFluWWlebw0",
"is_friend": true,
"app_registered": false,
"msg_blocked": false,
"nickname": "test",
"thumbnail_image": ""
}
],
"active_friends_count": 1,
"active_members_count": 1
}
}
메서드URL인증 방식
GET카카오
http://kapi.kakao.com/v2/internal/user/scopes/sdk
공동체
https://kapi.kakao.com/v2/internal/user/scopes/sdk
외부
https://kapi.kakao.com/v2/user/scopes/sdk
서비스 앱 네이티브 앱 키
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키필요: 연결-

사용자가 필요한 동의항목에 동의했는지 확인합니다. Kakao SDK에서 피커로 선택된 친구 또는 채팅방 멤버의 동의 내역을 확인하는 데 사용합니다. 피커로 정보 제공 시 동의 내역 조회 과정은 아래와 같습니다.

  1. 피커 호출 시, 사용자의 필요한 동의항목 동의 여부를 확인하고 기능 제공
  2. 사용자가 선택한 친구 또는 채팅방 멤버의 응답 제공에 필요한 동의항목 동의 여부 확인
  3. 동의 여부에 따라 마스킹(Masking) 처리를 거쳐 친구 또는 채팅방 멤버의 정보 제공

원하는 인증 정보를 헤더에 담아 GET으로 요청합니다. 요청이 성공하면 응답은 각 대상의 필요한 동의항목 동의 여부가 포함됩니다.

이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_NATIVE_APP_KEY}
인증 방식, 서비스 앱 네이티브 앱 키로 인증 요청
O
이름타입설명필수
scope_groupString확인할 동의항목 종류
friend: 피커: 친구 조회
chat_member: 피커: 채팅방 멤버 조회
O
target_idsString[]확인 대상 사용자의 회원번호 목록O
total_selected_countInteger사용자가 피커에서 실제로 선택한 친구 또는 채팅방 멤버의 수X
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
KAKA: ${KEY}/${VALUE}
KA 헤더 정보
O
이름타입설명필수
target_app_keyString서비스 앱 키O
scope_groupString확인할 동의항목 종류
friend: 피커: 친구 조회
chat_member: 피커: 채팅방 멤버 조회
O
target_idsString[]확인 대상 사용자의 회원번호 목록O
이름타입설명필수
-Scope[]각 대상의 동의 여부O
이름타입설명필수
idBoolean회원번호O
profile_nicknameBoolean[프로필 정보(닉네임/프로필 사진) 또는 닉네임] 동의 여부O
profile_imageBoolean[프로필 정보(닉네임/프로필 사진) 또는 프로필 사진] 동의 여부O
friendsBoolean[카카오 서비스내 친구목록(즐겨찾기, 프로필사진, 닉네임 포함)] 동의 여부

제공 조건: scope_groupfriend로 지정한 경우
X
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 확인할 동의항목 종류(scope_group): friend
    • 확인 대상 사용자의 회원번호 목록(target_ids)
curl -v -G "https://kapi.kakao.com/v2/user/scopes/sdk" \
-H "Authorization: KakaoAK ${SERVICE_APP_KEY}" \
-H "KA: sdk/1.15.1 os/android-29 lang/ko-KR origin/1WjJ5tOJPBJU+Q22Cs+VFlvxYIQ= device/SM-G965N android_pkg/com.kakao.talk app_ver/9.4.2" \
-d "scope_group=friend" \
-d "target_ids=1376016924429759243,1376016924430421791"
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 확인할 동의항목 종류(scope_group): chat_member
    • 확인 대상 사용자의 회원번호 목록(target_ids)
curl -v -G "http://kapi.kakao.com/v2/internal/user/scopes/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "KA: sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "scope_group=chat_member" \
-d "target_ids=1376016924429759243,1376016924430421791"
// HTTP/1.1 200 OK
[
{
"id": 1376016924430421791,
"profile_nickname": true,
"profile_image": true,
"friends": true
},
{
"id": 1376016924429759243,
"profile_nickname": true,
"profile_image": true,
"friends": true
}
]
// HTTP/1.1 200 OK
[
{
"id": 1376016924430421791,
"profile_nickname": false,
"profile_image": false
},
{
"id": 1376016924429759243,
"profile_nickname": false,
"profile_image": false
}
]
메서드URL인증 방식
GET카카오
http://kapi.kakao.com/v2/internal/talk/channels/sdk
공동체
https://kapi.kakao.com/v2/internal/talk/channels/sdk
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키--

사용자가 특정 카카오톡 채널을 친구 추가할 수 있는지 확인합니다. Kakao SDK에서 제공하는 카카오톡 채널 간편 추가 기능의 내부 동작에 사용되며, capri-apps에서 호출합니다.

capri-apps 앱의 어드민 키를 헤더에 담아 GET으로 요청합니다. 요청이 성공하면 응답은 아래 정보를 포함합니다.

  • 사용자와 카카오톡 채널의 관계 확인
  • 사용자가 카카오톡 채널을 추가할 수 있는지 여부
    • 추가 불가능한 경우, 상세 원인
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_app_keyString서비스 앱 키O(Optional)
target_idString사용자 IDO(Optional)
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O(Optional)
account_idInteger카카오계정 IDO(Optional)
target_access_tokenString사용자 액세스 토큰O(Optional)
target_kakao_agentStringKA 헤더
Kakao SDK로부터 전달받은 값 사용
O
channel_public_idString카카오톡 채널 프로필 IDO
이름타입설명필수
account_idInteger카카오계정 ID

제공 조건: 플랫폼 앱이 카카오계정 ID 응답 권한 보유
X
user_idLong사용자 회원번호

제공 조건: 카카오 로그인 사용 서비스의 요청인 경우
X
addableBoolean카카오톡 채널 추가 가능 여부O
reasonReason카카오톡 채널 추가가 불가능한 경우, 상세 원인

제공 조건: addablefalse인 경우
X
channelTalkChannelInfo카카오톡 채널 정보O
channel_relationTalkChannelRelation사용자와 카카오톡 채널의 관계X
이름타입설명필수
codeInteger카카오톡 채널 추가가 불가능한 경우, 상세 원인 코드
응답 코드: KAPI와 동일
-541(NOT_EXIST_CHANNEL): 카카오톡 채널이 삭제, 삭제 중, 휴면 상태인 경우
-542(INVALID_CHANNEL): 카카오톡 채널 홈이 비공개 상태인 경우
-4(BLOCKED_CHANNEL): 제재된 카카오톡 채널인 경우
-406(UNDER_AGE_LIMIT): 성인 채널인 카카오톡 채널을 미성년자 또는 본인인증하지 않은 사용자가 추가 요청한 경우
-506(ALREADY_FRIEND): 사용자가 카카오톡 채널을 이미 추가한 경우
O
msgString카카오톡 채널 추가가 불가능한 경우, 상세 원인 메시지O
이름타입설명필수
channel_talk_idLong카카오톡 채널의 카카오톡 회원번호

제공 조건: 플랫폼 앱이 카카오톡 회원번호 응답 권한 보유
X
channel_public_idString카카오톡 채널 프로필 IDO
channel_profile_nameString카카오톡 채널 프로필 이름O
channel_thumbnail_image_urlString카카오톡 채널 프로필 이미지 URLX
channel_intro_messageString카카오톡 채널 홈 소개 문구X
is_openBoolean카카오톡 채널 홈 공개 여부
  • true: 공개
  • false: 비공개, 추가 불가능
O
is_blockedBoolean카카오톡 채널 제재 상태O
is_verifiedBoolean카카오톡 채널 인증 여부O
is_adult_channelBoolean성인 채널 여부O
statusString채널 프로필 상태
ACTIVATED: 정상
DEACTIVATED: 삭제 중, 또는 삭제
O
friend_countInteger카카오톡 채널 친구 수O
welcome_coupon_titleString대표 쿠폰 이름

제공 조건: 카카오톡 채널 추가 화면에 쿠폰 노출 설정 시
X
welcome_coupon_countInteger카카오톡 채널 추가 화면에 노출 설정된 쿠폰 갯수

제공 조건: 카카오톡 채널 추가 화면에 쿠폰 노출 설정 시
X
이름타입설명필수
relationString사용자와 카카오톡 채널의 관계
NONE: 친구 아님, 추가 가능
BLOCKED: 차단, 추가 가능
ADDED: 친구, 추가 불가
O
created_atString채널 추가 일자, YYYY-MM-DDThh:mm:ssZ 형식

제공 조건: relationADD인 경우
X
updated_atString채널 관계 변경 일자

제공 조건: relationNONE이 아닌 경우
X
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 사용자 ID(target_id)
    • target_id 타입(target_id_type)
    • 카카오톡 채널 프로필 ID(channel_public_id)
    • KA 헤더 정보(target_kakao_agent)
curl -v -G "http://kapi.kakao.com/v2/internal/talk/channels/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "target_id=1376016924429759243" \
-d "target_id_type=user_id" \
-d "channel_public_id=_xnrxjem" \
--data-urlencode "target_kakao_agent=sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com"
  • 파라미터
    • 사용자 액세스 토큰(target_access_token)
    • 카카오톡 채널 프로필 ID(channel_public_id)
    • KA 헤더 정보(target_kakao_agent)
curl -v -G "http://kapi.kakao.com/v2/internal/talk/channels/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-d "target_access_token=${ACCESS_TOKEN}" \
-d "channel_public_id=_xnrxjem" \
--data-urlencode "target_kakao_agent=sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com"
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 카카오계정 ID(account_id)
    • 카카오톡 채널 프로필 ID(channel_public_id)
    • KA 헤더 정보(target_kakao_agent)
curl -v -G "http://kapi.kakao.com/v2/internal/talk/channels/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "account_id=81825" \
-d "channel_public_id=_xnrxjem" \
--data-urlencode "target_kakao_agent=sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com"
// HTTP/1.1 200 OK
{
"user_id": 166959,
"addable": true,
"channel": {
"channel_public_id": "_xlExk",
"channel_profile_name": "개발자용채널01",
"channel_thumbnail_image_url": "https://p.kakaocdn.net/th/talkp/wkgyKLytCQ/KiDdzJhJZzULs3vbCTXQE1/d8doxd_110x110_c.jpg",
"status": "ACTIVATED",
"is_open": true,
"is_blocked": false,
"is_verified": true,
"is_adult_channel": false,
"friend_count": 0,
"welcome_coupon_title": "대표 쿠폰 이름",
"welcome_coupon_count": 5
},
"channel_relation": {
"relation": "NONE"
}
}
메서드URL인증 방식
POST카카오
http://kapi.kakao.com/v2/internal/talk/channels/add/sdk
공동체
https://kapi.kakao.com/v2/internal/talk/channels/add/sdk
위임
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용어드민 키--

사용자에게 특정 카카오톡 채널을 친구 추가합니다. Kakao SDK에서 제공하는 카카오톡 채널 간편 추가 기능의 내부 동작에 사용되며, capri-apps에서 호출합니다.

capri-apps 앱의 어드민 키를 헤더에 담아 POST로 호출합니다. 요청이 성공하면 응답은 카카오톡 채널 추가 결과를 포함합니다. 카카오톡 채널 추가에 실패한 경우, 에러 응답을 반환합니다.

  • 내부 URL 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 URL 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_app_keyString서비스 앱 키O(Optional)
target_idString사용자 IDO(Optional)
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O(Optional)
account_idInteger카카오계정 IDO(Optional)
target_access_tokenString사용자 액세스 토큰O(Optional)
target_kakao_agentStringKA 헤더
Kakao SDK로부터 전달받은 값 사용
O
channel_public_idString카카오톡 채널 프로필 IDO
include_couponBoolean카카오톡 채널 추가 화면의 쿠폰 노출 여부, 사용자가 쿠폰 노출 카카오톡 채널 추가 시 쿠폰 발급
  • true: 쿠폰 노출
  • false: 쿠폰 미노출(기본값)
X
이름타입설명필수
channelTalkChannelInfo카카오톡 채널 정보O
account_idInteger카카오계정 ID

제공 조건: 플랫폼 앱이 카카오계정 ID 응답 권한 보유
X
user_idLong사용자 회원번호

제공 조건: 카카오 로그인 사용 서비스의 요청인 경우
X
successBoolean카카오톡 채널 추가 여부
  • true: 성공
  • false: 실패
O
이름타입설명필수
channel_talk_idLong카카오톡 채널의 카카오톡 회원번호

제공 조건: 플랫폼 앱이 카카오톡 회원번호 응답 권한 보유
X
channel_public_idString카카오톡 채널 프로필 IDO
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 사용자 ID(target_id)
    • target_id 타입(target_id_type)
    • 카카오톡 채널 프로필 ID(channel_public_id)
    • 카카오톡 채널 추가 화면의 쿠폰 노출 여부(include_coupon)
    • KA 헤더 정보(target_kakao_agent)
curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "target_id=1376016924429759243" \
-d "target_id_type=user_id" \
-d "channel_public_id=_xnrxjem" \
-d "include_coupon=true" \
--data-urlencode "target_kakao_agent=sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com"
  • 파라미터
    • 사용자 액세스 토큰(target_access_token)
    • 카카오톡 채널 프로필 ID(channel_public_id)
    • KA 헤더 정보(target_kakao_agent)
curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
-d "target_access_token=${ACCESS_TOKEN}" \
-d "channel_public_id=_xnrxjem" \
--data-urlencode "target_kakao_agent=sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com"
  • 파라미터
    • 서비스 앱 키(target_app_key)
    • 카카오계정 ID(account_id)
    • 카카오톡 채널 프로필 ID(channel_public_id)
    • KA 헤더 정보(target_kakao_agent)
curl -v -X POST "http://sandbox-kapi.kakao.com/v2/internal/talk/channels/add/sdk" \
-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
-H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
-d "target_app_key=${SERVICE_APP_KEY}" \
-d "account_id=81825" \
-d "channel_public_id=_xnrxjem" \
--data-urlencode "target_kakao_agent=sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com"
// HTTP/1.1 200 OK
{
"channel": {
"channel_public_id": "_xlExk"
},
"user_id": 166959,
"success": true
}
메서드URL인증 방식
POST외부
https://kapi.kakao.com/v1/app/validate/sdk
서비스 앱 네이티브 앱 키
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용---

올바른 서비스 앱으로 Kakao SDK를 사용하고 있는지 KA 헤더 값으로 확인합니다. Kakao SDK가 카카오톡 채널 추가 API, 카카오톡 채널 채팅 API 호출 시 커스텀 URL 스킴 실행 전 올바른 호출인지 검증하기 위해 사용합니다.

서비스 앱 네이티브 앱 키를 헤더에 담아 GET으로 요청합니다. 요청이 성공하면 응답은 KA 헤더 검증에 성공한 서비스 앱 ID를 포함합니다.

이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_NATIVE_APP_KEY}
인증 방식, 서비스 앱 네이티브 앱 키로 인증 요청
O
KAKA: ${KEY}/${VALUE}
KA 헤더 정보
O
이름타입설명필수
quota_propertiesQuotaPropertiesKA 헤더 검증 후 실행할 기능에 대한 정보O
이름타입설명필수
uriStringKA 헤더 검증 후 실행할 기능의 URL
/sdk/channel/add: 카카오톡 채널 추가
/sdk/channel/chat: 카카오톡 채널 채팅
O
channel_public_idString카카오톡 채널 프로필 IDO
이름타입설명필수
app_idInteger서비스 앱 IDO
  • 파라미터
    • KA 헤더 검증 후 실행할 기능에 대한 정보(quota_properties)
curl -v -X POST "https://kapi.kakao.com/v1/app/validate/sdk" \
-H "Authorization: KakaoAK ${SERVICE_APP_KEY}" \
-H "KA: sdk/1.15.1 os/android-29 lang/ko-KR origin/1WjJ5tOJPBJU+Q22Cs+VFlvxYIQ= device/SM-G965N android_pkg/com.kakao.talk app_ver/9.4.2" \
--data-urlencode 'quota_properties={"uri":"/sdk/channel/chat","channel_public_id":"_xlExk"}'
// HTTP/1.1 200 OK
{
"app_id": 208313
}
메서드URL인증 방식
GET외부
https://kapi.kakao.com/v1/user/check_access_token
액세스 토큰
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용---

주기적 토큰 갱신을 위해 액세스 토큰의 만료 시간을 확인합니다. Kakao SDK for Android, iOS는 주기적으로 토큰을 갱신하고 관리해주는 기능인 토큰 매니저를 제공합니다. 토큰 매니저가 저장된 액세스 토큰의 만료 시간을 확인하기 위해 이 API를 호출합니다.

액세스 토큰과 KA 헤더 정보를 헤더에 담아 GET으로 요청합니다. 네이티브 앱 키로 발급된 액세스 토큰만 사용 가능합니다. 요청 성공 시 응답은 액세스 토큰의 만료 시간을 포함합니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
KAKA: ${KEY}/${VALUE}
KA 헤더 정보
O
이름타입설명필수
idLong사용자 회원번호O
app_idInteger앱 IDO
expires_inInteger액세스 토큰 만료까지 남은 시간(단위: 초)O
  • 파라미터
    • 없음
curl -v -G "https://kapi.kakao.com/v1/user/check_access_token" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "KA: sdk/1.15.1 os/android-29 lang/ko-KR origin/1WjJ5tOJPBJU+Q22Cs+VFlvxYIQ= device/SM-G965N android_pkg/com.kakao.talk app_ver/9.4.2"
// HTTP/1.1 200 OK
{
"id": 143251,
"expires_in": 3557,
"app_id": 206235
}
메서드URL인증 방식
GET카카오
http://kapi.kakao.com/v1/internal/system/health_check
공동체
https://kapi.kakao.com/v1/internal/system/health_check
-
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용---

카카오 오픈 API(KAPI) 및 연관 PAPI의 상태를 확인합니다. 확인 가능 APIkapi.kakao.com 호스트를 사용하는 일부 API의 상태를 제공합니다. 이 API의 응답은 현재 상태 조회의 API 상태 확인 결과에 사용됩니다.

GET으로 요청합니다. 요청이 성공하면 응답은 각 API의 동작 및 상태 확인 결과를 포함합니다.

이름타입설명필수
datetimeString상태 확인을 수행한 시각, UTC*O
serviceString확인 대상 서비스, kapi로 고정O
elementsStatus[]API별 상태 확인 결과O
* UTC: RFC3339 internet date/time 형식
이름타입설명필수
uriStringAPI URIO
response_timeIntegerAPI 상태 확인 결과 응답 시간

제공 조건: resultSUCCESS인 경우
O
resultStringAPI 상태 확인 결과, 아래 중 하나
  • SUCCESS: API 동작 확인에 성공한 경우
  • FAILURE: API 동작 확인에 실패한 경우
  • DELAYED: API 동작 확인이 지정된 처리 시간을 초과한 경우
  • ISSUE: API 동작 확인은 성공했으나, 일부 응답이 누락된 경우
  • UNKNOWN: 알 수 없음
O
error_codeString에러 코드, 아래 중 하나
  • DB_ISSUE: 데이터베이스 접근에 실패한 경우
  • PAPI_ISSUE: PAPI 응답을 받는 데 실패한 경우
  • SLOW_EXECUTION: API 동작 확인이 지정된 처리 시간을 초과한 경우, resultDELAYED에 해당
  • RESPONSE_INCOMPLETE: 일부 응답이 누락된 경우, resultISSUE에 해당
  • UNCHECKED: 동작 확인을 하지 않은 경우, resultUNKNOWN에 해당
  • INTERNAL_ISSUE: 기타 문제가 발생한 경우

제공 조건: result 값이 SUCCESS가 아닌 경우
X
error_messageString에러 메시지

제공 조건: result 값이 SUCCESS가 아닌 경우
X
  • 파라미터
    • 없음
curl -v -G "http://kapi.kakao.com/v1/internal/system/health_check"
// HTTP/1.1 200 OK
{
"datetime": "2023-12-27 09:45:13Z",
"service": "kapi",
"elements": [
{
"uri": "/v2/user/scopes",
"response_time": 0,
"result": "SUCCESS"
},
{
"uri": "/v1/user/shipping_address",
"response_time": 1,
"result": "SUCCESS"
},
{
"uri": "/v2/api/talk/channels/multi",
"response_time": 28,
"result": "SUCCESS"
},
{
"uri": "/v2/user/service_terms",
"response_time": 2,
"result": "SUCCESS"
},
{
"uri": "/v1/talkchannel/target_user_file",
"response_time": 19,
"result": "SUCCESS"
},
{
"uri": "/v2/api/talk/channels",
"response_time": 27,
"result": "SUCCESS"
},
{
"uri": "/v1/user/ids",
"response_time": 1,
"result": "SUCCESS"
},
{
"uri": "/v2/app/users",
"response_time": 2,
"result": "SUCCESS"
},
{
"uri": "/v1/oidc/userinfo",
"response_time": 9,
"result": "SUCCESS"
},
{
"uri": "/v2/user/me",
"response_time": 18,
"result": "SUCCESS"
}
]
}
메서드URL인증 방식
GET카카오
http://kapi.kakao.com/v1/internal/system/health_check/dapi
공동체
https://kapi.kakao.com/v1/internal/system/health_check/dapi
-
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용---

DAPI의 상태를 확인합니다. 확인 가능 APIdapi.kakao.com 호스트를 사용하는 일부 API의 상태를 제공합니다. 이 API의 응답은 현재 상태 조회의 API 상태 확인 결과에 사용됩니다.

GET으로 요청합니다. 요청이 성공하면 응답은 각 API의 동작 및 상태 확인 결과를 포함합니다.

이름타입설명필수
datetimeString상태 확인을 수행한 시각, UTC*O
serviceString확인 대상 서비스, dapi로 고정O
elementsStatus[]API별 상태 확인 결과O
* UTC: RFC3339 internet date/time 형식
이름타입설명필수
uriStringAPI URI
(${PROVIDER_ID}/${API_ID} 형식)
O
response_timeIntegerAPI 상태 확인 결과 응답 시간

제공 조건: resultSUCCESS인 경우
O
resultStringAPI 상태 확인 결과, 아래 중 하나
  • SUCCESS: API 동작 확인에 성공한 경우
  • FAILURE: API 동작 확인에 실패한 경우
  • DELAYED: API 동작 확인이 지정된 처리 시간을 초과한 경우
  • UNKNOWN: 알 수 없음
O
error_codeString에러 코드, 아래 중 하나
  • SLOW_EXECUTION: API 동작 확인이 지정된 처리 시간을 초과한 경우, resultDELAYED에 해당
  • UNCHECKED: 동작 확인을 하지 않은 경우, resultUNKNOWN에 해당
  • INTERNAL_ISSUE: API 응답의 HTTP 상태 코드가 200이 아닌 경우

제공 조건: result 값이 SUCCESS가 아닌 경우
X
error_messageString에러 메시지

제공 조건: result 값이 SUCCESS가 아닌 경우
X
  • 파라미터
    • 없음
curl -v -G "http://kapi.kakao.com/v1/internal/system/health_check/dapi"
// HTTP/1.1 200 OK
{
"datetime": "2023-09-11 06:10:43Z",
"service": "dapi",
"elements": [
{
"uri": "122/1694",
"error_code": "SLOW_EXECUTION",
"error_message": "time out 4000ms",
"result": "DELAYED"
},
{
"uri": "122/1691",
"error_code": "INTERNAL_ISSUE",
"error_message": "UNEXPECTED ISSUE : request gateway timeout",
"result": "FAILURE"
},
{
"uri": "115/1678",
"response_time": 131,
"result": "SUCCESS"
},
{
"uri": "115/1677",
"error_code": "UNCHECKED",
"error_message": "unchecked",
"result": "UNKNOWN"
}
// ...
]
}
메서드URL인증 방식
GET외부
https://api-status.kakao.com/api/health/current
-
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용---

카카오 오픈 API의 현재 상태를 확인합니다. 상태 정보는 5분마다 갱신됩니다. 이 API는 KAPI 상태 조회DAPI 상태 조회의 결과를 반영한 종합적인 상태 정보를 제공합니다. 요청 및 응답 정보는 현재 상태 조회를 참고합니다.

메서드URL인증 방식
GET외부
https://api-status.kakao.com/api/health/history
-
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용---

카카오 오픈 API 상태의 이력을 확인합니다. 이력은 일 단위로 제공하고, 요청일 기준으로 최대 30일 전까지 조회 가능합니다. 카카오 오픈 API 상태 페이지에서 사용합니다. 요청 및 응답 정보는 이력 조회를 참고합니다.

메서드URL인증 방식
GET카카오
http://capri-status.onkakao.net/api/maintenance
공동체
https://capri-status.onkakao.net/api/maintenance
-
권한사전 설정카카오 로그인동의항목
API플랫폼 내부 전용---

카카오 오픈 API의 점검 일정을 확인합니다. 점검 일정은 카카오 API 플랫폼 내부에서 관리하고, 주요 점검 일정은 데브톡 공지로도 안내합니다. 이 API를 사용해 등록된 점검 일정을 확인할 수 있습니다.

GET으로 요청합니다. 요청 시 조회 기간, 조회 대상 제품, 언어를 지정할 수 있습니다. 요청이 성공하면 응답은 카카오 오픈 API 제품별 점검 일정 목록을 포함합니다.

이름설명필수
userAuthorization: Basic ${AUTH_INFO}
인증 정보, ${AUTH_INFO}점검 일정 관리에서 확인 가능(조회 권한 필요)
O
이름타입설명필수
productString상태를 확인할 제품, 쉼표로 구분된 하나의 문자열
미지정 시 모든 제품의 상태 확인
(예: login,message)
X
startString시작일, yyyy-MM-dd 형식
(기본값: 요청일 기준 1주일 전)
X
endString종료일, yyyy-MM-dd 형식
(기본값: 요청일 기준 1달 후)
X
langString응답 언어, 아래 중 하나
  • ko: 한국어
  • en: 영어
(기본값: ko)
X
이름타입설명필수
-Maintenance[]점검 일정 목록X
이름타입설명필수
productString제품 IDO
apiString[]해당 제품의 API ID 목록O
startString시작일, yyyy-MM-dd HH:mm:ssZ 형식O
endString종료일, yyyy-MM-dd HH:mm:ssZ 형식O
  • 파라미터
    • 조회 기간: start, end
    • 제품: product
curl -v -G "http://capri-status.onkakao.net/api/maintenance" \
-H "Authorization: Basic ${AUTH_INFO}" \
-d "start=2023-12-01" \
-d "end=2023-12-15" \
-d "product=${PRODUCT}"
// HTTP/1.1 200 OK
[
{
"product": "${PRODUCT}",
"api": ["${API}",...]
"start": "2023-12-01 00:00:00Z"
"end": "2023-12-01 00:05:00Z"
},
// ...
]

도움이 되었나요?