본문으로 건너뛰기

문자(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_idstring(필수) 콘솔에서 등록한 SMS 발신 프로필 ID. 인포뱅크 발송이 활성화(is_infobank_enabled = true)되어 있어야 합니다
phone_numberstring(필수) 수신자 전화번호. 숫자 사이 -/공백 허용 (예: 01012345678, 010-1234-5678)
bodystring(필수) 본문 텍스트
titlestring(선택) 제목 (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_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 RequestResourceNotFoundSMS 발신 프로필을 찾을 수 없는 경우
400 Bad RequestResourceNotReadySMS 발신 프로필의 인포뱅크 발송이 비활성(is_infobank_enabled !== true)인 경우
400 Bad RequestUnAuthorized인증 실패 (secret key 오류)
429 Too Many RequestsTooManyRequests호출 한도 초과 (발송 한도 참고)
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
titletypebody 길이결과
있음(무관)(무관)LMS
없음sms≤ 90바이트SMS
없음lms(≤ 2,000바이트)LMS
없음(미지정)≤ 90바이트SMS
없음(미지정)> 90바이트LMS

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



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