본문으로 건너뛰기

알림톡 단건 발송하기

전화번호와 알림톡 템플릿을 사용해 단건 알림톡을 발송하는 방법을 설명합니다. 블럭스 담당자에게 문의하여 발급받은 secret key를 사용해서 알림톡을 발송할 수 있습니다.

개요​

  • 캠페인 생성 없이 외부 시스템에서 직접 API를 호출하여 알림톡을 발송할 수 있습니다.
  • 회원/비회원 구분 없이 전화번호만 있으면 발송할 수 있어 주문/배송/문의 등 거래성 알림에 적합합니다.
  • 한 번의 호출로 한 명의 수신자에게 발송되며, 다수 수신자에게 발송하려면 호출을 반복하거나 캠페인을 사용하세요.

전제 조건​

  1. 블럭스 콘솔에서 알림톡 템플릿을 등록하고 카카오 비즈메시지 심사 승인을 완료해야 합니다.
  2. 템플릿에 사용된 변수(#{변수명})는 API 호출 시 template_params로 전달해야 합니다.
  3. 대체발송(SMS/LMS)을 사용하려면 다음 두 가지가 모두 필요합니다.
    • API 호출 시 resendParameter를 함께 전달합니다.
    • 발신 프로필에 발송 실패 설정이 미리 등록돼 있어야 합니다. 설정 없이 resendParameter만 전달하면 발송이 거절되어 응답의 status가 failed로 반환됩니다. 설정이 필요하면 블럭스 담당자에게 문의해 주세요.

발송 API​

엔드포인트​

POST https://api.blux.ai/prod/applications/{APPLICATION_ID}/notifications/send-alimtalk

인증​

요청 시 Authorization 헤더에 발급받은 secret key를 포함해야 합니다:

Authorization: {SECRET_KEY}

요청 본문​

{
  "alimtalk_template_id": "string",
  "phone_number": "01012345678",
  "template_params": {
    "변수명": "값"
  },
  "resendParameter": {
    "resendType": "LMS",
    "resendTitle": "string",
    "resendContent": "string",
    "resendSendNo": "0212345678"
  }
}

필드 설명​

필드타입설명
alimtalk_template_idstring(필수) 콘솔에서 등록한 알림톡 템플릿 ID
phone_numberstring(필수) 수신자 전화번호. 숫자 사이 -/공백 허용 (예: 01012345678, 010-1234-5678)
template_paramsobject(필수) 템플릿 변수에 매핑될 값. 키는 템플릿의 #{변수명}과 일치해야 합니다. 본문뿐 아니라 부가정보(extra)·버튼 URL/스킴 등에 포함된 모든 변수를 빠짐없이 채워야 하며, 누락 시 400 Bad Request (InvalidBodyParams, details.missing_variables)가 반환됩니다
resendParameterobject(선택) 알림톡 발송 실패 시 LMS로 대체 발송하기 위한 정보
  ↳ resendType"SMS" | "LMS"(선택) 대체 발송 채널 타입
  ↳ resendTitlestring(선택) 대체 발송 제목 (LMS/MMS)
  ↳ resendContentstring(선택) 대체 발송 본문
  ↳ resendSendNostring(선택) 대체 발송 시 발신 번호

응답​

성공 시 (HTTP 200 OK):

{
  "notification_id": "65f0a8b1c4d3e2f1a0b9c8d7",
  "status": "sent"
}

벤더(NHN)가 발송 요청을 거절한 경우에도 200 OK로 응답되며 status가 failed로 표시됩니다:

{
  "notification_id": "65f0a8b1c4d3e2f1a0b9c8d7",
  "status": "failed",
  "error_code": "FAILED_TO_SEND_NHN_KAKAO",
  "error_message": "..."
}

필드 설명​

필드타입설명
notification_idstring발송 요청에 대해 생성된 알림 ID
status"sent" | "failed"벤더 발송 요청이 성공(sent)했는지 거절(failed)됐는지. 단말기 수신 결과는 결과 웹훅으로 별도 전달
error_codestringstatus=failed인 경우만 포함. 거절 사유 코드
error_messagestringstatus=failed인 경우만 포함. 거절 사유 메시지

상태 코드​

코드errorCode설명
200 OK—벤더 발송 요청 완료. 결과는 응답 본문의 status로 확인 (sent / failed)
400 Bad Request(validation)필수 필드 누락, 전화번호 형식 오류 등 잘못된 값 전달 시
400 Bad RequestInvalidBodyParams템플릿이 요구하는 변수가 누락된 경우 (details.missing_variables 참고)
400 Bad RequestResourceNotFound알림톡 템플릿을 찾을 수 없는 경우
400 Bad RequestResourceNotReady템플릿이 발송 가능한 상태(카카오 비즈메시지 심사 승인 완료)가 아닌 경우
400 Bad RequestUnAuthorized인증 실패 (secret key 오류)
429 Too Many RequestsTooManyRequests호출 한도 초과 (발송 한도 참고)
500 Internal Server Error—서버 내부 오류

발송 한도​

application별로 초당 100건까지 호출할 수 있습니다. 초과하면 429 Too Many Requests 응답이 반환되며 Retry-After: 1 헤더가 포함됩니다.

{
  "code": 429001,
  "message": "TooManyRequests",
  "details": {
    "retry_after_seconds": 1
  }
}

대량 발송이 필요하면 호출을 분산하거나 API 트리거 캠페인을 사용해 주세요.

테스트 예시​

curl -X POST https://api.blux.ai/prod/applications/abcd1234/notifications/send-alimtalk \
  -H "Authorization: xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "alimtalk_template_id": "65f0a8b1c4d3e2f1a0b9c8d7",
    "phone_number": "01012345678",
    "template_params": {
      "고객명": "홍길동",
      "주문번호": "20260428-0001"
    }
  }'

💬 200 OK 응답의 status가 sent이면 NHN이 발송 요청을 정상 접수한 것이고, failed이면 거절된 것입니다. 단말기 수신 결과는 알림톡 발송 결과 웹훅을 등록해 받아주세요.

자주 묻는 질문 (FAQ)​

Q. 비회원에게도 발송할 수 있나요? A. 네. 회원 가입 여부와 무관하게 전화번호만 있으면 발송할 수 있습니다.

Q. 한 번에 여러 명에게 발송할 수 있나요? A. 본 API는 단건 발송 전용입니다. 다수 수신자에게 발송하려면 호출을 반복하거나 API 트리거 캠페인을 사용하세요.

Q. 템플릿이 카카오 심사 승인을 받지 못한 상태이면 어떻게 되나요? A. 400 Bad Request(ResourceNotReady) 응답이 반환되며 발송되지 않습니다. 콘솔에서 템플릿 상태를 먼저 확인해 주세요.



추가 문의는 블럭스 기술지원팀에 연락주세요.