--- updatedAt: 2026-03-25T09:03:13.000Z agentTools: projectIndex: https://sdk.sendon.io/llms.txt --- # 문자 메시지 발송하기 문자 메시지 발송은 SMS, LMS, MMS의 3가지 메시지 유형을 지원합니다. * **단문 메시지(SMS)** : 최대 90자 텍스트 * **장문 메시지(LMS)** : 최대 2,000자 텍스트 * **멀티미디어 메시지(MMS)** : 이미지를 포함한 텍스트 메시지 발송 또한, 메시지 발송 시 필요한 다양한 옵션을 제공합니다. * **예약 발송 기능** : 특정 시간에 예약 메시지를 발송 * **다중 수신자 발송 기능** : 한 번의 API 호출로 여러 명에게 메시지 발송 * **수신자 맞춤 메시지** : 메시지 내용에 변수를 활용하여 각 수신자에게 맞춤형 메시지 발송 *** ## **SMS** 즉시 문자를 발송하여 사용자와 빠르게 소통할 수 있습니다. 단문 메시지(SMS)는 간단한 알림, 인증 코드 발송, 마케팅 메시지 등 다양한 용도로 활용될 수 있습니다. SDK는 사용자가 최소한의 코드로 메시지를 발송할 수 있도록 직관적으로 설계되었습니다. 다음은 **SMS를 발송하는 기본적인 예제**입니다. ```typescript 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)는 간단한 알림, 인증 코드, 마케팅 메시지 등 다양한 용도로 활용될 수 있습니다', }) ``` ```java Java 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 즉시발송 가이드](https://sdk.sendon.io/recipes/sdk-sms-%EC%A6%89%EC%8B%9C%EB%B0%9C%EC%86%A1#/)** *** ## **LMS** 장문 메시지(LMS)는 **최대 2,000자까지 발송 가능**하며, **상세한 정보 제공, 공지, 프로모션** 등 다양한 용도로 활용됩니다. LMS는 이미지 첨부가 없는 긴 메시지를 발송할 때 적합합니다. ### **LMS 발송 예제** ```typescript 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자까지 전송이 가능하며, 상세한 정보 제공, 공지, 프로모션 등 다양한 용도로 활용됩니다', }) ``` ```java Java 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 발송 예제** ```typescript 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], }) ``` ```java List 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 이미지 업로드 및 발송 가이드](https://sdk.sendon.io/v0.9/recipes/sdk-mms-이미지-업로드-및-발송)** *** ## **메시지 발송 결과 조회** 메시지 발송 요청이 성공적으로 완료되면 **고유한 ID**를 리턴받게 됩니다. 이 ID를 이용해 발송 결과를 조회할 수 있습니다. 발송 결과를 확인하려면 아래 API 문서를 참고하세요. 🔗 **문자 메시지 발송 결과 조회** ### **응답 예제** ```json { "code": 200, "message": "성공", "data": { "groupId": "84db8cbb-db70-4e68-8ee7-c37704787e0d" } } ```
## 수신자별 맞춤 메시지 발송 (변수 치환) CSV 파일과 변수를 활용하면 수신자마다 서로 다른 내용의 메시지를 발송할 수 있습니다. 예를 들어 고객명, 결제 금액, 상품명 등을 수신자별로 다르게 설정하여 한 번의 요청으로 개인화된 메시지를 대량 발송할 수 있습니다.
### 변수 형식 메시지 본문에 `#{변수명}` 형식으로 변수를 삽입합니다. ``` 안녕하세요 #{고객명}님, #{상품명} 결제 금액은 #{금액}원입니다. ```
### CSV 업로드와 발송 흐름 CSV 파일(UTF-8만 지원)을 활용한 변수 치환 발송은 다음 3단계로 진행됩니다. #### Step 1. CSV 업로드 URL 발급 먼저 CSV 파일을 업로드하기 위한 presigned URL을 발급받습니다. ```bash curl -X POST https://api.sendon.io/v2/messages/sms/csv/presigned \ -H "Authorization: Basic {base64(id:apiKey)}" ``` 응답으로 업로드에 필요한 `presignedUrl`, `bucket`, `key` 값이 반환됩니다. ```json { "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 인코딩으로 저장합니다. ```csv 연락처,#{고객명},#{금액},#{상품명} 01012345678,홍길동,50000,노트북 01087654321,김철수,30000,마우스 01011112222,이영희,120000,모니터 ``` Step 1에서 발급받은 `presignedUrl`로 파일을 업로드합니다. ```bash curl -X PUT "{presignedUrl}" \ -H "Content-Type: text/csv" \ --data-binary @recipients.csv ``` 📢 업로드가 최종적으로 완료된 후 발송 API 가 호출되어야 정상 발송됩니다. 최종 업로드되지 않은 시점에 발송 API를 호출하면 응답은 정상처럼 보이지만, 최종 결과는 실패로 처리됩니다.
#### Step 3. 변수 포함 메시지 발송 메시지 본문에 CSV 헤더와 동일한 변수명을 사용하고, `to` 필드에 Step 1에서 받은 `bucket`과 `key` 값을 전달합니다. ```bash 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 }' ``` ```json { "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건까지 발송할 수 있습니다.