kakaosend API 매뉴얼
카카오 알림톡을 HTTP API 로 발송하고 결과를 바로 받습니다.
개요
(최대 100건)
버튼 치환 · DB 기록
(실패 시 문자 대체)
바로 리턴
| 항목 | 내용 |
|---|---|
| Base URL | https://kakaosend.cloud.ezadmin.co.kr |
| 프로토콜 | HTTPS 전용, Content-Type: application/json, UTF-8 |
| 인증 | Authorization: Bearer <토큰> |
| 1회 최대 건수 | 100건 (발송·조회 공통) |
| 권장 클라이언트 타임아웃 | 30초 |
인증
모든 /v1/* 요청은 발급받은 토큰을 헤더에 넣어야 합니다.
Authorization: Bearer ks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- 토큰은 API 관리자에게 발급 요청합니다. 발급 시 한 번만 전달되며 서버에는 해시만 저장되므로 분실 시 재발급해야 합니다.
- 토큰마다 허용 IP, 기본 발신프로필키(profile_key), 추가 허용 profile_key 가 지정됩니다.
- 토큰은 소스코드에 넣지 말고 설정 파일·환경변수로 관리하세요.
빠른 시작
curl -X POST https://kakaosend.cloud.ezadmin.co.kr/v1/send \
-H "Authorization: Bearer $KAKAOSEND_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messages": [{
"ref_id": "ORD1001-DELIVERY",
"receiver": "01012345678",
"template_code": "ORDER_DELIVERY",
"message": "[이지샵] 홍길동님, 주문하신 상품이 출고되었습니다.",
"domain": "shopA",
"btn_url": "shop.example.com/order/1001"
}]
}'
{
"total": 1, "success": 1, "fail": 0,
"results": [{
"index": 0, "ref_id": "ORD1001-DELIVERY", "msg_id": "ks1201",
"status": "SUCCESS", "code": "K000", "message": "", "kind": "K",
"duplicated": false, "receiver": "01012345678", "sent_at": "2026-11-22 15:30:12"
}]
}
알림톡 발송
messages 배열로 1~100건을 한 번에 보냅니다. 결과는 요청 순서(index)대로 건별로 돌아옵니다.
422 로 거부되고 아무것도 발송되지 않습니다.
형식이 맞으면 200 이 돌아오고, 발송 성공/실패는 각 건의 status 로 판단합니다.요청 필드 — messages[]
| 필드 | 타입 | 설명 | |
|---|---|---|---|
receiver | string | 필수* | 수신번호. 01012345678, 010-1234-5678 모두 가능 (숫자만 추출). *user_key 를 쓰면 생략 |
user_key | string | 선택 | 개인정보플러그인용 userKey. 지정 시 receiver 대신 사용 |
template_code | string | 필수 | 카카오 승인된 템플릿 코드 |
message | string | 필수 | 본문 (최대 1000자). 템플릿 변수(#{이름} 등)는 치환을 마친 내용을 보내야 합니다 |
ref_id | string | 선택·권장 | 호출측 고유키 (최대 64자). 같은 값으로 재요청 시 재발송하지 않음. 재시도·중복 방지 참고 |
message_type | string | 선택 | at 알림톡(기본) / ai 이미지 알림톡 |
profile_key | string | 선택 | 발신프로필키. 생략 시 토큰의 기본값. 토큰에 허용되지 않은 키면 해당 건 E_PROFILE 실패 |
title | string | 선택 | 강조표기형 템플릿의 제목 |
buttons | array | 선택 | 버튼 최대 5개. 비우면 서버가 템플릿 버튼을 자동으로 붙임 (서버 버튼 치환) |
quick_replies | array | 선택 | 바로연결 최대 10개. 형식은 buttons 와 동일 |
image_url | string | 선택 | 이미지 알림톡 이미지 URL |
image_link | string | 선택 | 이미지 클릭 시 이동 URL |
fallback | object | 선택 | 알림톡 실패 시 문자 대체발송. 생략하면 대체발송 안 함 |
reserved_time | string | 선택 | 예약발송 yyyyMMddHHmmss (예: 20261123090000) |
domain, btn_url, misc1~misc4 | string | 선택 | 서버 버튼 치환용. 아래 참고 |
auto_img_template | boolean | 선택 | 기본 true. 승인된 이미지 템플릿(같은 코드 또는 코드_img)이 있으면 자동으로 이미지 알림톡으로 전환 |
버튼 — buttons[] / quick_replies[]
| 필드 | 설명 | |
|---|---|---|
name | 필수 | 버튼명 (최대 28자) |
type | 필수 | WL 웹링크, AL 앱링크, DS 배송조회, BK 봇키워드, MD 메시지전달, BC 상담톡전환, BT 봇전환, AC 채널추가, P1~P3 플러그인 |
url_mobile, url_pc | WL | 웹링크 URL |
scheme_ios, scheme_android | AL | 앱 스킴 |
plugin_id, relay_id | P* | 플러그인 버튼 |
버튼은 템플릿에 등록된 것과 같아야 발송됩니다. 값이 빈 필드는 자동으로 빠집니다.
문자 대체발송 — fallback
| 필드 | 설명 | |
|---|---|---|
type | 선택 | SMS(기본) / LMS |
sender | 필수 | 발신번호 (사전 등록된 번호) |
message | 선택 | 문자 본문. 생략 시 알림톡 본문과 동일 |
title | 선택 | LMS 제목 |
대체발송된 경우 결과의 kind 가 M, code 가 M000 으로 옵니다.
응답
| 필드 | 설명 |
|---|---|
total / success / fail | 전체 / SUCCESS / 그 외(FAIL+UNKNOWN) 건수 |
results[].index | 요청 배열 위치 (0부터) |
results[].ref_id | 요청한 ref_id |
results[].msg_id | 발급된 메시지 ID (ks+숫자). 결과 조회에 사용. 접수 전 실패면 null |
results[].status | SUCCESS / FAIL / UNKNOWN / PENDING — 상세 |
results[].code | 결과코드 (비즈엠 코드 또는 E_ 내부코드) |
results[].message | 실패 사유 |
results[].kind | K 알림톡 발송 / M 문자 대체발송 |
results[].duplicated | true 면 ref_id 중복으로 이번에 발송하지 않고 기존 결과를 돌려준 것 |
results[].receiver | 수신번호(숫자만) 또는 user_key |
results[].sent_at | 발송 시각 yyyy-MM-dd HH:mm:ss |
서버 버튼 치환
buttons 와 quick_replies 를 둘 다 비워서 보내면, 서버가 template_code 에 등록된 버튼
(sys_kakao_template_btn)을 조회해 URL 을 치환한 뒤 붙입니다. 기존 알림톡 데몬과 같은 규칙이며,
기존 alim_queue 에 넣던 값을 같은 이름으로 보내면 됩니다.
| 필드 | 용도 |
|---|---|
domain | 반품톡(EL)·송장(TA/RP) 링크에 들어가는 도메인 |
btn_url | 템플릿 URL 의 [URL], [HTTP_NO_INCLUDE_URL] 치환값. http 유무는 템플릿에 맞춰 자동 보정 |
misc1 | MULTI: a|b|주문번호 · CS: a_주문번호 · EZCHAIN: uuid|domain |
misc2 | 플러스친구 ID ([YELLOW_ID], 반품톡 plusid) |
misc3 | 서비스 구분: MULTI / CS / EZCALL / EZCHAIN / EZDESK 등 |
misc4 | EZCALL: uuid|... · EZCHAIN: [UUID] 값 · EZDESK: 개인정보플러그인 |
misc3 별 동작
| misc3 | 치환 내용 |
|---|---|
EZCALL | [YELLOW_ID] ← misc2 (URL 인코딩), [UUID] ← misc4 의 | 앞 |
EZCHAIN | [URL] ← 결제 링크(misc1 기반), [YELLOW_ID], [UUID] ← misc4 |
EZDESK + misc4=개인정보플러그인 | 플러그인 버튼 (plugin_id, relay_id = user_key). 이 경우 user_key 로 보내야 함 |
| 그 외 (MULTI, CS 등) | 버튼 1~5 + 바로연결 1~10. [URL] 치환, 커스텀 버튼 EL(반품톡)/TA/RP(송장) 링크 생성 |
{
"messages": [{
"ref_id": "CS-777-RETURN",
"receiver": "01012345678",
"template_code": "RETURN_GUIDE",
"message": "[이지샵] 반품 신청 안내입니다.",
"domain": "shopA",
"misc1": "cs_777",
"misc2": "@ezshop",
"misc3": "CS"
}]
}
buttons 가 그대로 쓰이고 템플릿 조회는 하지 않습니다.발송 결과 조회 (여러 건)
msg_ids 또는 ref_ids 로 최대 100건 조회합니다. 본인 토큰으로 보낸 건만 조회되며 없는 건은 결과에서 빠집니다.
{ "ref_ids": ["ORD1001-DELIVERY", "ORD1002-DELIVERY"] }
{ "msg_ids": ["ks1201", "ks1202"] }
응답은 {"total": n, "results": [...]} 이며 results 항목은 /v1/send 응답과 같습니다 (index 는 null).
발송 결과 조회 (단건)
없으면 404.
결과 상태·코드
status
| status | 의미 | 호출측 처리 |
|---|---|---|
| SUCCESS | 발송 성공 (알림톡 또는 문자 대체) | 완료 |
| FAIL | 발송 실패. 비즈엠이 거부했거나 접수 전 오류 | code/message 확인. 템플릿·번호 문제는 재시도해도 실패 |
| UNKNOWN | 비즈엠과 통신 오류로 실제 발송 여부를 알 수 없음 | 자동 재발송하지 않습니다. 확인 후 필요하면 새 ref_id 로 재발송 |
| PENDING | 접수됨, 아직 결과 없음 (처리 중 서버 중단 등) | 잠시 후 결과 조회 |
code
| code | status | 의미 |
|---|---|---|
K000 | SUCCESS | 알림톡 발송 성공 |
M000 | SUCCESS | 알림톡 실패 → 문자 대체발송 성공 |
R000 | SUCCESS | 성공 |
E_PROFILE | FAIL | profile_key 없음 또는 토큰에 허용되지 않은 profile_key |
E_TEMPLATE | FAIL | 템플릿 버튼 조회 실패 (서버 내부 DB 오류). 미발송 — 잠시 후 재시도 가능 |
E_NETWORK | UNKNOWN | 비즈엠 통신 오류/타임아웃 |
E_NORESULT | UNKNOWN | 비즈엠 응답에 해당 건 결과가 없음 |
그 외 (E102, K1xx 등) | FAIL | 비즈엠 오류코드. message 에 사유가 함께 옵니다 |
HTTP 상태코드
| 코드 | 의미 | 응답 예 |
|---|---|---|
200 | 처리됨 — 건별 결과는 body 의 status 확인 | |
401 | 토큰 없음 / 무효 / 폐기됨 | {"detail":"유효하지 않은 토큰입니다"} |
403 | 토큰에 허용되지 않은 IP | {"detail":"허용되지 않은 IP: 1.2.3.4"} |
404 | 단건 조회 대상 없음 | {"detail":"해당 msg_id 없음"} |
422 | 요청 형식 오류 — 전체 거부, 미발송 | 아래 참고 |
5xx | 서버 오류 | 같은 ref_id 로 재시도 |
HTTP/1.1 422
{
"detail": "요청 형식 오류",
"errors": [
{ "loc": "body.messages.3.receiver", "msg": "Value error, 수신번호 형식 오류" }
]
}
loc 의 숫자(messages.3)가 문제가 된 건의 위치입니다.
재시도·중복 방지
- 항상
ref_id를 넣으세요. 주문번호+알림종류처럼 “이 알림은 한 번만 가야 한다”는 단위로 만듭니다. (예:ORD1001-DELIVERY) - 타임아웃·5xx 로 응답을 못 받았다면 같은 ref_id 로 그대로 재요청하세요. 이미 처리된 건은 재발송되지 않고
duplicated: true와 기존 결과가 옵니다. - 같은 고객에게 같은 알림을 의도적으로 다시 보내려면 새 ref_id 를 쓰세요. (예:
ORD1001-DELIVERY-2) UNKNOWN은 실제로 발송됐을 수 있습니다. 중복 발송이 문제가 되는 알림이면 확인 후 재발송하세요.
언어별 예제
<?php
function kakaosend($messages)
{
$token = getenv('KAKAOSEND_TOKEN');
$c = curl_init('https://kakaosend.cloud.ezadmin.co.kr/v1/send');
curl_setopt_array($c, array(
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization: Bearer ' . $token,
),
CURLOPT_POSTFIELDS => json_encode(array('messages' => $messages), JSON_UNESCAPED_UNICODE),
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 30,
));
$body = curl_exec($c);
$http = curl_getinfo($c, CURLINFO_HTTP_CODE);
$err = curl_error($c);
curl_close($c);
if ($body === false) throw new Exception("kakaosend 통신오류: $err"); // 같은 ref_id 로 재시도
$data = json_decode($body, true);
if ($http != 200) throw new Exception("kakaosend HTTP $http: $body");
return $data;
}
$res = kakaosend(array(
array(
'ref_id' => 'ORD1001-DELIVERY',
'receiver' => '01012345678',
'template_code' => 'ORDER_DELIVERY',
'message' => '[이지샵] 홍길동님, 주문하신 상품이 출고되었습니다.',
'domain' => 'shopA',
'btn_url' => 'shop.example.com/order/1001',
),
));
foreach ($res['results'] as $r) {
if ($r['status'] == 'SUCCESS') { /* 성공 */ }
else { error_log("알림톡 실패 {$r['ref_id']} {$r['code']} {$r['message']}"); }
}import os
import requests
def kakaosend(messages):
r = requests.post(
"https://kakaosend.cloud.ezadmin.co.kr/v1/send",
headers={"Authorization": f"Bearer {os.environ['KAKAOSEND_TOKEN']}"},
json={"messages": messages},
timeout=(5, 30),
)
r.raise_for_status()
return r.json()
res = kakaosend([{
"ref_id": "ORD1001-DELIVERY",
"receiver": "01012345678",
"template_code": "ORDER_DELIVERY",
"message": "[이지샵] 홍길동님, 주문하신 상품이 출고되었습니다.",
"domain": "shopA",
"btn_url": "shop.example.com/order/1001",
}])
for r in res["results"]:
if r["status"] != "SUCCESS":
print("실패", r["ref_id"], r["code"], r["message"])# 발송
curl -X POST https://kakaosend.cloud.ezadmin.co.kr/v1/send \
-H "Authorization: Bearer $KAKAOSEND_TOKEN" \
-H "Content-Type: application/json" \
-d '{"messages":[{"ref_id":"T-1","receiver":"01012345678","template_code":"TPL001","message":"테스트"}]}'
# 결과 조회 (ref_id)
curl -X POST https://kakaosend.cloud.ezadmin.co.kr/v1/response \
-H "Authorization: Bearer $KAKAOSEND_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ref_ids":["T-1"]}'
# 결과 조회 (msg_id 단건)
curl https://kakaosend.cloud.ezadmin.co.kr/v1/response/ks1201 \
-H "Authorization: Bearer $KAKAOSEND_TOKEN"FAQ
100건이 넘으면?
100건씩 나눠서 여러 번 호출하세요. 101건 이상은 422 로 거부됩니다.
발신프로필이 다른 메시지를 한 요청에 섞어도 되나요?
됩니다. 건마다 profile_key 를 지정하면 서버가 프로필별로 묶어서 보냅니다. 단, 토큰에 허용된 프로필키여야 합니다.
예약발송은 어떻게 하나요?
reserved_time 에 yyyyMMddHHmmss 로 넣습니다. 응답의 SUCCESS 는 비즈엠 접수 성공을 의미합니다.
결과가 나중에 바뀌나요?
아니요. 문자 대체발송 결과를 포함해 /v1/send 응답 시점에 결과가 확정됩니다. /v1/response 는 저장된 결과를 다시 조회하는 용도입니다.
템플릿 버튼이 안 붙어요
buttons/quick_replies 를 빈 배열이거나 아예 빼고 보냈는지, template_code 가 맞는지 확인하세요. [URL] 이 들어간 템플릿은 btn_url 이 필요합니다.