문자 메시지 발송결과 조회하기

전송한 문자 메시지의 발송결과를 간편하게 조회할 수 있습니다.

발송 결과는 성공 여부와 함께 메시지 상태, 실패 원인 등의 상세 정보를 제공합니다.

이 문서에서는 발송 결과를 조회하는 방법과 주요 필드에 대한 설명을 안내합니다.


발송 결과 조회

발송된 메시지의 상태와 세부 정보를 조회하여 결과를 확인할 수 있습니다.

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

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

// 문자 발송은 비동기 호출되기 때문에 발송 결과가 바로 리턴되지 않습니다.
// 사용자는 발송 결과를 조회하기 위하여 폴링 구조의 결과 확인 로직이 필요합니다.
let isPolling = true
const timeoutMs = 10 * 1000 // 최대 10초 대기
const startTime = Date.now()
while (isPolling) {
  if (Date.now() - startTime > timeoutMs) {
    console.error('타임아웃: 10초 동안 응답이 없어 조회를 중단합니다.')
    break
  }

  const result = await sendon.sms.find(smsResult.data.groupId)
  if (result.code === 404) {
    await sleep(1000)
    continue
  }
  console.log(result)
  isPolling = false
}
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));

// 발송요청의 groupId 생성될때까지 대기
// 웹훅 서비스 지원 전까지는 폴링 대기 필요해요 ;-(
sleep(5000);

GetGroup getGroup = sendon.sms.getGroup(sendSms.data.groupId);

Sendon SDK는 비동기 방식으로 메시지를 발송하여 효율적인 메시징 작업을 지원합니다.
하지만 비동기 전송 방식 특성상, 메시지 발송 직후에는 전송 결과가 확정되지 않을 수 있습니다. 개발자는 메시지 전송 후 일정한 간격으로 결과 조회 API를 호출하여 전송 상태를 모니터링하고 결과를 추적해야 합니다. 특히, 실패한 메시지에 대한 재시도 로직을 구현하여 안정적인 메시지 전송을 보장할 수 있습니다.

발송 결과 조회 전략

  1. 전송 완료 예상 시간 설정
    • 메시지 유형(SMS, LMS, MMS)에 따라 예상 전송 완료 시간을 고려하여 결과 조회를 시작합니다.
  2. 주기적인 API 호출
    • 일정 시간 간격으로 groupId를 사용해 결과 조회 API를 호출합니다.
  3. 실패한 메시지 처리
    • 조회 결과에서 FAILED 상태의 메시지에 대해 적절한 재시도 로직을 구현합니다.

자세한 코드 예제는 아래 문서를 참고하세요.

🔗 SDK SMS 발송 조회 가이드


발송 결과 예제

메시지 발송 결과 조회가 성공적으로 완료되면 아래와 같이 자세한 정보를 확인할 수 있습니다.

{
    "code": 200,
    "message": "성공",
    "data": {
        "groupId": "84db8cbb-db70-4e68-8ee7-c37704787e0d",
        "message": "안녕하세요. Sendon SDK Java를 이용한 테스트 메시지 입니다.(652)",
        "messageType": "SMS",
        "requestIp": "39.117.148.116",
        "sender": "010XXXXYYYY",
        "userId": "164",
        "isUseApi": true,
        "messageCount": 1,
        "succeededCount": 1,
        "failedCount": 0,
        "canceledCount": 0,
        "blockedCount": 0,
        "pointId": "94",
        "totalPoint": 9.24,
        "vatPoint": 0.84,
        "unitCost": 8.4,
        "groupStatus": "COMPLETED",
        "createdAt": "2024-11-17T14:02:46Z",
        "immediatelyAction": "SEND"
    }
}

발송 결과 주요 필드 설명

필드

설명

필수 여부

code

HTTP 상태 코드

필수

message

"성공" 또는 "실패"

필수

data

결과 데이터

필수

groupId

발송 요청에 대한 그룹 ID

필수

groupStatus

발송 요청 상태 (RESERVED, PROCESSING, COMPLETED, FAILED, CANCELED)

필수

message

발송 요청한 메시지 내용

필수

messageType

메시지 유형 (SMS, LMS, MMS)

필수

requestIp

발송 요청한 클라이언트 IP

필수

sender

발신 번호

필수

isUseApi

API 사용 여부 (true: API, false: WEB)

필수

messageCount

전체 수신 메시지 수

필수

succeededCount

발송 성공한 메시지 수

필수

failedCount

발송 실패한 메시지 수

필수

canceledCount

발송 취소된 메시지 수

필수

blockedCount

수신 거부된 메시지 수

필수

pointId

결제 포인트 고유 ID

필수

totalPoint

발송으로 인해 소모된 전체 포인트 (실패 포함)

필수

vatPoint

포인트 단가에 대한 부가세 포인트

필수

unitCost

포인트 단가

필수

refundPoint

수신 실패가 있을 경우 재적립된 포인트

선택

immediatelyAction

예약된 발송에 대해 즉시 발송 또는 예약 취소를 했을 때 상태

"SEND" : 즉시 발송 "CANCEL" : 예약 취소

선택