문자 메시지 발송하기

문자 메시지 발송은 SMS, LMS, MMS의 3가지 메시지 유형을 지원합니다.

단문 메시지(SMS) : 최대 90자 텍스트
장문 메시지(LMS) : 최대 2,000자 텍스트
멀티미디어 메시지(MMS) : 이미지를 포함한 텍스트 메시지 발송

또한, 메시지 발송 시 필요한 다양한 옵션을 제공합니다.

예약 발송 기능 : 특정 시간에 예약 메시지를 발송
다중 수신자 발송 기능 : 한 번의 API 호출로 여러 명에게 메시지 발송
수신자 맞춤 메시지 : 메시지 내용에 변수를 활용하여 각 수신자에게 맞춤형 메시지 발송

SMS

즉시 문자를 발송하여 사용자와 빠르게 소통할 수 있습니다. 단문 메시지(SMS)는 간단한 알림, 인증 코드 발송, 마케팅 메시지 등 다양한 용도로 활용될 수 있습니다. SDK는 사용자가 최소한의 코드로 메시지를 발송할 수 있도록 직관적으로 설계되었습니다. 다음은 SMS를 발송하는 기본적인 예제입니다.

const sendon = new Sendon({
    id: SENDON_EXAM_ACCOUNT,
    apikey: SENDON_EXAM_API_KEY,
    debug: false,
  })

const result = await sendon.sms.send({
  type: SmsMessageType.SMS,
  from: SENDON_EXAM_SMS_FROM_PHONE,
  to: [SENDON_EXAM_SMS_TO_PHONE],
  message: '단문 메시지(SMS)는 간단한 알림, 인증 코드, 마케팅 메시지 등 다양한 용도로 활용될 수 있습니다',
})

Sendon sendon = Sendon.getInstance(USER_ID, USER_APIKEY, true);

SendSms sendSms = sendon.sms.sendSms(new SmsBuilder()
																.setFrom(SMS_MOBILE_FROM)
                                .setTo(Arrays.asList(SMS_MOBILE_TO))
                                .setMessage("Hello, World!")
                                .setIsAd(false));

주요 필드 설명

필드	설명	필수여부
`type`	메시지 타입	필수
`from`	발신자 번호	필수
`to`	수신자 번호 (250KB 길이 제한)	필수
`message`	발송할 메시지, 광고성 메시지일 경우 message 가장 앞에 "(광고)" 필수 입력	필수
`isAd`	정보성/광고성 옵션 (`false`:정보성 / `true`:광고성)	선택
`useCredit`	크레딧 우선사용 여부	선택

⚠️ 주의 사항 발송하는 메시지가 정보성 안내라 하더라도, 내용 또는 URL에 영리목적의 내용이 포함된 경우 반드시 광고로 발송해야 합니다. 광고표기법을 준수하지 않으면 관련 기관으로부터 신고될 수 있으며, 광고문자는 반드시 사전 수신 동의를 받은 고객에게만 발송해야 합니다.

자세한 코드 설명은 아래 레시피에서 확인하세요:

🔗 SDK SMS 즉시발송 가이드

LMS

장문 메시지(LMS)는 최대 2,000자까지 발송 가능하며, 상세한 정보 제공, 공지, 프로모션 등 다양한 용도로 활용됩니다. LMS는 이미지 첨부가 없는 긴 메시지를 발송할 때 적합합니다.

LMS 발송 예제

const result = await sendon.sms.send({
  type: SmsMessageType.LMS,
  from: SENDON_EXAM_SMS_FROM_PHONE,
  to: [SENDON_EXAM_SMS_TO_PHONE],
  title: 'LMS 제목',
  message: 'LMS는 2,000자까지 전송이 가능하며, 상세한 정보 제공, 공지, 프로모션 등 다양한 용도로 활용됩니다',
})

Sendon sendon = Sendon.getInstance(USER_ID, USER_APIKEY, true);

SendSms sendSms = sendon.sms.sendLms(new LmsBuilder()
																.setFrom(SMS_MOBILE_FROM)
                                .setTo(Arrays.asList(SMS_MOBILE_TO))
                                .setTitle(TITLE)
                                .setMessage("Hello, World!")
                                .setIsAd(false));

필드	설	필수여부
`title`	메시지 제목 (한글 32자리, 영문 64자)	선택

MMS

멀티미디어 메시지(MMS)는 문자와 이미지를 함께 발송할 수 있는 기능입니다. MMS는 최대 3,000자까지 발송할 수 있으며, **이미지 파일(최대 5MB)**을 첨부할 수 있습니다. 업로드한 이미지는 이동통신사에서 허용하는 품질로 자동 변환됩니다.

MMS 발송 예제

const imageFile = new File(
  [fs.readFileSync(path.resolve(__dirname, '../../resources/sendon_image.png'))],
  'sendon.png',
  {
    type: 'image/png',
  },
)
const uploadedImages = await sendon.sms.uploadImages([imageFile])

const result = await sendon.sms.send({
  type: SmsMessageType.MMS,
  from: SENDON_EXAM_SMS_FROM_PHONE,
  to: [SENDON_EXAM_SMS_TO_PHONE],
  title: 'MMS 제목',
  message: 'MMS는 최대 3,000자까지 전송할 수 있으며, 이미지 파일(최대 5MB)을 첨부할 수 있습니다.',
  images: [uploadedImages.data.images[0].id],
})

List<File> images = Arrays.asList(new File("sendon_image.png"));
UploadImage uploadImage = sendon.sms.uploadImages(images);

SendSms sendSms = sendon.sms.sendMms(new MmsBuilder()
																.setFrom(SMS_MOBILE_FROM)
                                .setTo(Arrays.asList(SMS_MOBILE_TO))
                                .setTitle(TITLE)
                                .setMessage("Hello, World!")
                                .setReservation(reservation)
                                .setIsAd(true)
                                .setImages(Arrays.asList(images.get(0).id)));

이미지 업로드 필드 설명

필드	설명	필수여부
`images`	업로드한 이미지 파일 ID 리스트	선택

자세한 코드 설명은 아래 레시피에서 확인하세요:

🔗 SDK MMS 이미지 업로드 및 발송 가이드

메시지 발송 결과 조회

메시지 발송 요청이 성공적으로 완료되면 고유한 ID를 리턴받게 됩니다. 이 ID를 이용해 발송 결과를 조회할 수 있습니다. 발송 결과를 확인하려면 아래 API 문서를 참고하세요.

🔗 문자 메시지 발송 결과 조회

응답 예제

{
    "code": 200,
    "message": "성공",
    "data": {
        "groupId": "84db8cbb-db70-4e68-8ee7-c37704787e0d"
    }
}

수신자별 맞춤 메시지 발송 (변수 치환)

CSV 파일과 변수를 활용하면 수신자마다 서로 다른 내용의 메시지를 발송할 수 있습니다. 예를 들어 고객명, 결제 금액, 상품명 등을 수신자별로 다르게 설정하여 한 번의 요청으로 개인화된 메시지를 대량 발송할 수 있습니다.

변수 형식

메시지 본문에 #{변수명} 형식으로 변수를 삽입합니다.

안녕하세요 #{고객명}님, #{상품명} 결제 금액은 #{금액}원입니다.

발송 흐름

CSV 파일을 활용한 변수 치환 발송은 다음 3단계로 진행됩니다.

Step 1. CSV 업로드 URL 발급

먼저 CSV 파일을 업로드하기 위한 presigned URL을 발급받습니다.

curl -X POST https://api.sendon.io/v2/messages/sms/csv/presigned \
  -H "Authorization: Basic {base64(id:apiKey)}"

응답으로 업로드에 필요한 presignedUrl, bucket, key 값이 반환됩니다.

{
  "code": 200,
  "message": "성공",
  "data": {
    "presignedUrl": "https://s3.ap-northeast-2.amazonaws.com/...",
    "bucket": "bizmsg-message-sms-...",
    "key": "12345/csv/CSV..."
  }
}

Step 2. CSV 파일 작성 및 업로드

아래 형식에 맞춰 CSV 파일을 작성합니다.

첫 번째 컬럼은 반드시 연락처로 지정합니다.
두 번째 컬럼부터 #{변수명} 형식으로 변수를 정의합니다.
전화번호는 하이픈(-) 없이 숫자만 입력합니다.
파일은 UTF-8 인코딩으로 저장합니다.

연락처,#{고객명},#{금액},#{상품명}
01012345678,홍길동,50000,노트북
01087654321,김철수,30000,마우스
01011112222,이영희,120000,모니터

Step 1에서 발급받은 presignedUrl로 파일을 업로드합니다.

curl -X PUT "{presignedUrl}" \
  -H "Content-Type: text/csv" \
  --data-binary @recipients.csv

Step 3. 변수 포함 메시지 발송

메시지 본문에 CSV 헤더와 동일한 변수명을 사용하고, to 필드에 Step 1에서 받은 bucket과 key 값을 전달합니다.

curl -X POST https://api.sendon.io/v2/messages/sms \
  -H "Authorization: Basic {base64(apiKey:)}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "from": "01087654321",
    "to": [
      {
        "bucket": "bizmsg-message-sms-...",
        "key": "12345/csv/CSV..."
      }
    ],
    "message": "안녕하세요 #{고객명}님, #{상품명} 결제 금액은 #{금액}원입니다.",
    "isAd": false,
    "useCredit": false
  }'

{
  "code": 200,
  "message": "성공",
  "data": {
    "groupId": "GRP..."
  }
}

발송 결과 예시

위 요청을 실행하면 각 수신자에게 아래와 같이 개인화된 메시지가 발송됩니다.

수신자	발송 메시지
01012345678	안녕하세요 홍길동님, 노트북 결제 금액은 50000원입니다.
01087654321	안녕하세요 김철수님, 마우스 결제 금액은 30000원입니다.
01011112222	안녕하세요 이영희님, 모니터 결제 금액은 120000원입니다.

주의사항

메시지 본문의 변수명(#{고객명})은 CSV 헤더의 변수명과 정확히 일치해야 합니다.
같은 변수가 메시지 내에 여러 번 사용되면 모두 치환됩니다.
CSV에 해당 변수의 값이 비어 있으면 변수가 치환되지 않고 #{변수명} 그대로 표시됩니다.
SMS는 90바이트(한글 약 45자), LMS는 2,000바이트(한글 약 1,000자)까지 입력할 수 있으므로, 변수 치환 후 최종 메시지 길이에 주의해 주세요.
CSV 방식은 최대 500,000건까지 발송할 수 있습니다.