문자(SMS) 단건 발송하기

전화번호와 본문 텍스트만으로 단건 문자(SMS/LMS)를 발송하는 방법을 설명합니다. 블럭스 담당자에게 문의하여 발급받은 secret key를 사용해서 문자를 발송할 수 있습니다.

개요

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

전제 조건

1. 블럭스 콘솔에서 SMS 발신 프로필(sms_profile)을 등록하고 인포뱅크 발송 채널을 활성화해야 합니다.
2. 발신번호는 인포뱅크에 사전 등록·인증된 번호여야 합니다.
3. 본문 텍스트는 한글·영문·숫자·기본 특수문자만 사용 가능합니다(EUC-KR 호환).

발송 API

엔드포인트

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

인증

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

Authorization: {SECRET_KEY}

요청 본문

{
  "sms_profile_id": "string",
  "phone_number": "01012345678",
  "body": "주문이 완료되었습니다.",
  "title": "주문 완료"
}

필드 설명

필드	타입	필수	설명
sms_profile_id	string	필수	콘솔에서 등록한 SMS 발신 프로필 ID. 인포뱅크 발송이 활성화(is_infobank_enabled = true)되어 있어야 합니다
phone_number	string	필수	수신자 전화번호. 숫자 사이 -/공백 허용 (예: 01012345678, 010-1234-5678)
body	string	필수	본문 텍스트
title	string	선택	제목 (LMS 전용). 입력하면 type 지정과 무관하게 LMS로 발송됩니다
type	"sms" | "lms"	선택	메시지 타입. 미지정 시 본문이 EUC-KR 90바이트(한글 약 45자)를 초과하면 LMS, 그 외 SMS로 자동 결정. title이 있는 경우 항상 LMS. MMS는 지원하지 않습니다

광고성 문자 발송 시에는 정보통신망법에 따라 본문 시작에 [광고] 표기와 본문 끝에 무료 수신거부 안내(080-XXX-XXXX 등)를 직접 포함해야 합니다. 야간(21시~08시) 발송 금지 등 규제 준수 책임은 발송 측에 있습니다.

응답

성공 시 (HTTP 200 OK):

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

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

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

필드 설명

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

상태 코드

코드	errorCode	설명
200 OK	—	벤더 발송 요청 완료. 결과는 응답 본문의 status로 확인 (sent / failed)
400 Bad Request	(validation)	필수 필드 누락, 전화번호 형식 오류 등 잘못된 값 전달 시
400 Bad Request	ResourceNotFound	SMS 발신 프로필을 찾을 수 없는 경우
400 Bad Request	ResourceNotReady	SMS 발신 프로필의 인포뱅크 발송이 비활성(is_infobank_enabled !== true)인 경우
400 Bad Request	UnAuthorized	인증 실패 (secret key 오류)
429 Too Many Requests	TooManyRequests	호출 한도 초과 (발송 한도 참고)
500 Internal Server Error	—	서버 내부 오류

발송 한도

application별로 초당 200건까지 호출할 수 있습니다. 초과하면 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-sms \
  -H "Authorization: xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sms_profile_id": "65f0a8b1c4d3e2f1a0b9c8d7",
    "phone_number": "01012345678",
    "body": "주문이 완료되었습니다. 주문번호: 20260428-0001"
  }'

💬 200 OK 응답 본문의 status가 sent이면 벤더(인포뱅크)가 발송 요청을 정상 접수한 것이고, failed이면 거절된 것입니다. 단말기 수신 결과는 SMS 발송 결과 웹훅을 등록해 받아주세요.

자주 묻는 질문 (FAQ)

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

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

Q. 발신번호는 어디에 등록하나요? A. 콘솔의 SMS 발신 프로필 설정에서 등록할 수 있으며, 사전에 인포뱅크에 발신번호 인증을 완료해야 정상 발송됩니다.

Q. SMS와 LMS는 어떻게 구분되나요? A. 다음 우선순위로 결정됩니다:

1. title이 있으면 → 항상 LMS (type 지정 무시)
2. title이 없고 type 명시 → 명시된 타입 그대로
3. title이 없고 type 미지정 → 본문이 EUC-KR 90바이트(한글 약 45자)를 초과하면 LMS, 그 외 SMS

title	type	body 길이	결과
있음	(무관)	(무관)	LMS
없음	sms	≤ 90바이트	SMS
없음	lms	(≤ 2000바이트)	LMS
없음	(미지정)	≤ 90바이트	SMS
없음	(미지정)	> 90바이트	LMS

⚠️ type: sms 명시 + 본문 90바이트 초과는 거부됩니다(400). LMS로 보내려면 type을 빼거나 lms로 명시해 주세요.

---

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