사이드 메뉴
커뮤니케이션
API 제공
어드민 API
카카오톡 채널 메시지
REST API
이 문서는 채널 메시지 API를 안내합니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | 카카오http://kapi.kakao.com/v1/internal/talk/channels/message/send공동체 https://kapi.kakao.com/v1/internal/talk/channels/message/send배치 http://kapi.kakao.com/v1/internal/talk/channels/message/send/batch | 서비스 앱 어드민 키 위임 |
주의
같은 메시지 템플릿을 주기적으로 발송하는 경우, 또는 여러 사용자에게 동시에 발송하는 경우에는 배치 URL을 사용해야 합니다. 발송 방식에서 자세한 사항을 확인합니다.
[도구] > [메시지 템플릿]에 등록된 사용자 정의 템플릿으로 ID로 특정 가능한 사용자에게 채널 메시지를 발송합니다. 메시지 템플릿 심사가 완료된 템플릿만 사용할 수 있습니다.
앱 어드민 키를 헤더에 담아 파라미터와 함께 POST로 요청합니다. 타입을 지정한 1명 또는 복수의 수신자 ID를 포함해야 합니다.
요청 성공 시 응답은, 수신자가 1명인 경우 result_code의 값이 0인 JSON 객체, 여러명인 경우 발송에 성공한 ID 목록입니다. 요청 실패 시 에러 코드로 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| receiver_id | String | 메시지 수신자 ID, receiver_id_type이 phone_number인 경우 국가코드를 포함한 값(예: 8210XXXXXXXX)주의: receiver_ids 미포함 시 필수 | X |
| receiver_ids | String[] | 메시지 수신자 ID 목록 (최대 10명) 주의: receiver_id 미포함 시 필수 | X |
| receiver_id_type | String | receiver_id, receiver_ids 타입, 아래 중 하나
| X |
| template_id | String | [도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID | O |
| template_args | Map<String, String> | 메시지 템플릿에 정의한 사용자 인자에 대입할 키와 값 | X |
| channel_talk_id | Long | 메시지를 발송할 채널의 talk id주의: channel_public_id 미포함 시 필수 | X |
| channel_public_id | String | 메시지를 발송할 채널의 public id주의: channel_talk_id 미포함 시 필수 | X |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_id | String | 사용자 정의 템플릿 채널 메시지를 발송할 서비스 앱의 ID | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| receiver_id | String | 메시지 수신자 ID, receiver_id_type이 phone_number인 경우 국가코드를 포함한 값(예: 8210XXXXXXXX)주의: receiver_ids 미포함 시 필수 | X |
| receiver_ids | String[] | 메시지 수신자 ID 목록 (최대 10명) 주의: receiver_id 미포함 시 필수 | X |
| receiver_id_type | String | receiver_id, receiver_ids 타입, 아래 중 하나
| X |
| template_id | String | [도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID | O |
| template_args | Map<String, String> | 메시지 템플릿에 정의한 사용자 인자에 대입할 키와 값 | X |
| channel_talk_id | Long | 메시지를 발송할 채널의 talk id주의: channel_public_id 미포함 시 필수 | X |
| channel_public_id | String | 메시지를 발송할 채널의 public id주의: channel_talk_id 미포함 시 필수 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| result_code | Integer | 발송 성공 시 0 | O |
| successful_receiver_ids | String[] | 메시지 발송에 성공한 receiver_ids | X |
| failure_info | FailureInfo[] | 실패 정보 메시지 수신자가 1명인 경우 failure_info 없이 에러 코드 전달메시지 수신자가 2명 이상인 경우 HTTP 상태 코드 200과 함께 failure_info 전달, 예제 참고 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| code | Integer | 에러 코드 | O |
| msg | String | 에러 메시지 | O |
| receiver_ids | String[] | 메시지 발송에 실패한 메시지 수신자 ID 목록, 요청 receiver_id_type 유지 | O |
요청: 서비스 앱 어드민 키 방식
curl -v -X POST "http://kapi.kakao.com/v1/internal/talk/channels/message/send" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "template_id=${TEMPLATE_ID}" \-d "receiver_ids=${RECEIVER_IDS}" \-d "channel_talk_id=${CHANNEL_TALK_ID}" \-d 'template_args={"TITLE":"타이틀입니다."}'
요청: 위임 방식
curl -v -X POST "http://kapi.kakao.com/v1/internal/talk/channels/message/send" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_id=161496" \-d "template_id=${TEMPLATE_ID}" \-d "receiver_ids=${RECEIVER_IDS}" \-d "channel_talk_id=${CHANNEL_TALK_ID}" \-d 'template_args={"TITLE":"타이틀입니다."}'
응답: 1명의 수신자
// HTTP/1.1 200 OK{"result_code": 0}
응답: 여러명의 수신자
// HTTP/1.1 200 OK{"result_code": 0,"successful_receiver_ids": [1234567890, 2345678901] // ${RECEIVER_IDS}}
응답: 일부 실패, 여러명의 수신자
// HTTP/1.1 200 OK{"result_code": -500,"successful_receiver_ids": [1234567890], // ${RECEIVER_IDS}"failure_info": [{"code": -101,"msg": "...","receiver_ids": [2345678901] // ${RECEIVER_IDS}}]}