kakaosend API 매뉴얼

카카오 알림톡을 HTTP API 로 발송하고 결과를 바로 받습니다.

개요

호출 서버POST /v1/send
(최대 100건)
→
kakaosend토큰 검증 · 형식 검증
버튼 치환 · DB 기록
→
비즈엠알림톡 발송
(실패 시 문자 대체)
→
응답건별 결과를
바로 리턴
항목내용
Base URLhttps://kakaosend.cloud.ezadmin.co.kr
프로토콜HTTPS 전용, Content-Type: application/json, UTF-8
인증Authorization: Bearer <토큰>
1회 최대 건수100건 (발송·조회 공통)
권장 클라이언트 타임아웃30초

인증

모든 /v1/* 요청은 발급받은 토큰을 헤더에 넣어야 합니다.

Authorization: Bearer ks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
주의Swagger UI 의 Try it out 은 실제로 발송됩니다. 테스트는 본인 번호로만 하세요.

빠른 시작

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"
  }]
}

알림톡 발송

POST/v1/send

messages 배열로 1~100건을 한 번에 보냅니다. 결과는 요청 순서(index)대로 건별로 돌아옵니다.

요청 단위 vs 건 단위 한 건이라도 형식 오류(번호 형식, 필수값 누락, 101건 이상 등)가 있으면 요청 전체가 422 로 거부되고 아무것도 발송되지 않습니다. 형식이 맞으면 200 이 돌아오고, 발송 성공/실패는 각 건의 status 로 판단합니다.

요청 필드 — messages[]

필드타입설명
receiverstring필수*수신번호. 01012345678, 010-1234-5678 모두 가능 (숫자만 추출). *user_key 를 쓰면 생략
user_keystring선택개인정보플러그인용 userKey. 지정 시 receiver 대신 사용
template_codestring필수카카오 승인된 템플릿 코드
messagestring필수본문 (최대 1000자). 템플릿 변수(#{이름} 등)는 치환을 마친 내용을 보내야 합니다
ref_idstring선택·권장호출측 고유키 (최대 64자). 같은 값으로 재요청 시 재발송하지 않음. 재시도·중복 방지 참고
message_typestring선택at 알림톡(기본) / ai 이미지 알림톡
profile_keystring선택발신프로필키. 생략 시 토큰의 기본값. 토큰에 허용되지 않은 키면 해당 건 E_PROFILE 실패
titlestring선택강조표기형 템플릿의 제목
buttonsarray선택버튼 최대 5개. 비우면 서버가 템플릿 버튼을 자동으로 붙임 (서버 버튼 치환)
quick_repliesarray선택바로연결 최대 10개. 형식은 buttons 와 동일
image_urlstring선택이미지 알림톡 이미지 URL
image_linkstring선택이미지 클릭 시 이동 URL
fallbackobject선택알림톡 실패 시 문자 대체발송. 생략하면 대체발송 안 함
reserved_timestring선택예약발송 yyyyMMddHHmmss (예: 20261123090000)
domain, btn_url, misc1~misc4string선택서버 버튼 치환용. 아래 참고
auto_img_templateboolean선택기본 true. 승인된 이미지 템플릿(같은 코드 또는 코드_img)이 있으면 자동으로 이미지 알림톡으로 전환

버튼 — buttons[] / quick_replies[]

필드설명
name필수버튼명 (최대 28자)
type필수WL 웹링크, AL 앱링크, DS 배송조회, BK 봇키워드, MD 메시지전달, BC 상담톡전환, BT 봇전환, AC 채널추가, P1~P3 플러그인
url_mobile, url_pcWL웹링크 URL
scheme_ios, scheme_androidAL앱 스킴
plugin_id, relay_idP*플러그인 버튼

버튼은 템플릿에 등록된 것과 같아야 발송됩니다. 값이 빈 필드는 자동으로 빠집니다.

문자 대체발송 — 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[].statusSUCCESS / FAIL / UNKNOWN / PENDING — 상세
results[].code결과코드 (비즈엠 코드 또는 E_ 내부코드)
results[].message실패 사유
results[].kindK 알림톡 발송 / M 문자 대체발송
results[].duplicatedtrue 면 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 유무는 템플릿에 맞춰 자동 보정
misc1MULTI: a|b|주문번호 · CS: a_주문번호 · EZCHAIN: uuid|domain
misc2플러스친구 ID ([YELLOW_ID], 반품톡 plusid)
misc3서비스 구분: MULTI / CS / EZCALL / EZCHAIN / EZDESK 등
misc4EZCALL: 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 가 그대로 쓰이고 템플릿 조회는 하지 않습니다.

발송 결과 조회 (여러 건)

POST/v1/response

msg_ids 또는 ref_ids 로 최대 100건 조회합니다. 본인 토큰으로 보낸 건만 조회되며 없는 건은 결과에서 빠집니다.

{ "ref_ids": ["ORD1001-DELIVERY", "ORD1002-DELIVERY"] }
{ "msg_ids": ["ks1201", "ks1202"] }

응답은 {"total": n, "results": [...]} 이며 results 항목은 /v1/send 응답과 같습니다 (index 는 null).

발송 결과 조회 (단건)

GET/v1/response/{msg_id}

없으면 404.

결과 상태·코드

status

status의미호출측 처리
SUCCESS발송 성공 (알림톡 또는 문자 대체)완료
FAIL발송 실패. 비즈엠이 거부했거나 접수 전 오류code/message 확인. 템플릿·번호 문제는 재시도해도 실패
UNKNOWN비즈엠과 통신 오류로 실제 발송 여부를 알 수 없음자동 재발송하지 않습니다. 확인 후 필요하면 새 ref_id 로 재발송
PENDING접수됨, 아직 결과 없음 (처리 중 서버 중단 등)잠시 후 결과 조회

code

codestatus의미
K000SUCCESS알림톡 발송 성공
M000SUCCESS알림톡 실패 → 문자 대체발송 성공
R000SUCCESS성공
E_PROFILEFAILprofile_key 없음 또는 토큰에 허용되지 않은 profile_key
E_TEMPLATEFAIL템플릿 버튼 조회 실패 (서버 내부 DB 오류). 미발송 — 잠시 후 재시도 가능
E_NETWORKUNKNOWN비즈엠 통신 오류/타임아웃
E_NORESULTUNKNOWN비즈엠 응답에 해당 건 결과가 없음
그 외 (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)가 문제가 된 건의 위치입니다.

재시도·중복 방지

  1. 항상 ref_id 를 넣으세요. 주문번호+알림종류처럼 “이 알림은 한 번만 가야 한다”는 단위로 만듭니다. (예: ORD1001-DELIVERY)
  2. 타임아웃·5xx 로 응답을 못 받았다면 같은 ref_id 로 그대로 재요청하세요. 이미 처리된 건은 재발송되지 않고 duplicated: true 와 기존 결과가 옵니다.
  3. 같은 고객에게 같은 알림을 의도적으로 다시 보내려면 새 ref_id 를 쓰세요. (예: ORD1001-DELIVERY-2)
  4. UNKNOWN 은 실제로 발송됐을 수 있습니다. 중복 발송이 문제가 되는 알림이면 확인 후 재발송하세요.
ref_id 를 넣지 않으면재시도할 때마다 새로 발송되어 고객이 같은 알림을 여러 번 받을 수 있습니다.

언어별 예제

<?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']}"); }
}

FAQ

100건이 넘으면?

100건씩 나눠서 여러 번 호출하세요. 101건 이상은 422 로 거부됩니다.

발신프로필이 다른 메시지를 한 요청에 섞어도 되나요?

됩니다. 건마다 profile_key 를 지정하면 서버가 프로필별로 묶어서 보냅니다. 단, 토큰에 허용된 프로필키여야 합니다.

예약발송은 어떻게 하나요?

reserved_time 에 yyyyMMddHHmmss 로 넣습니다. 응답의 SUCCESS 는 비즈엠 접수 성공을 의미합니다.

결과가 나중에 바뀌나요?

아니요. 문자 대체발송 결과를 포함해 /v1/send 응답 시점에 결과가 확정됩니다. /v1/response 는 저장된 결과를 다시 조회하는 용도입니다.

템플릿 버튼이 안 붙어요

buttons/quick_replies 를 빈 배열이거나 아예 빼고 보냈는지, template_code 가 맞는지 확인하세요. [URL] 이 들어간 템플릿은 btn_url 이 필요합니다.