메시지 이해하기

이 페이지는 커뮤니케이션 API의 세부 규격을 보기 전에, 메시지 업무에서 먼저 이해해두면 좋은 핵심 개념을 정리한 안내 페이지입니다.

채널별 규격(SMS/LMS/MMS/RCS/비즈메시지)은 각각 필드가 다르지만, 실제 운영에서는 동보발송, 대체발송(Fallback), 치환메시지, 멱등성 키, 발신 식별코드 같은 공통 개념을 함께 이해해야 안정적으로 연동할 수 있습니다.

아래 항목은 실무에서 자주 묻는 기준을 중심으로 정리되어 있으며, 각 세부 규격 페이지에서 같은 용어를 만났을 때 바로 맥락을 이해할 수 있도록 구성했습니다.

동보발송(여러건 발송)

동보발송은 동일한 메시지를 다수 수신자에게 한 번에 발송하는 방식입니다.

• 요청 단위와 운영 정책에 맞게 분할합니다.
• 수신자 목록은 destinations 필드로 전달합니다.
• 스팸 방지 정책이나 개별 수신자 상태에 따라 분리 처리합니다.
• 한 번의 요청으로 최대 200개의 수신자 번호를 전달할 수 있습니다.
• 과도하게 빠른 연속 요청은 피하고, 운영 환경에 맞는 요청 간격을 두는 것을 권장합니다.
• 치환메시지를 사용하는 경우 수신자 번호별로 치환값이 각각 적용됩니다.
• 접수 응답도 수신자 번호별 결과로 분리되어 전달됩니다.

POST /api/omni
destinations: [{ to: "01000000000" }]
결과: 1건 접수 응답

POST /api/omni
destinations: [{ to: "01000000001" }, { to: "01000000002" }, ..., { to: "01000000200" }]
결과: 수신번호별 접수 응답(최대 200건)

Fallback 메시지(대체발송)

Fallback은 발송 요청의 messageFlow 순서에 따라 자동 대체 발송을 수행하는 기능입니다.

• messageFlow는 Array 형태로 메시지를 순서대로 담습니다.
• 앞 순서 메시지가 실패하면 다음 순서 메시지로 자동 전환됩니다.
• 채널별 메시지는 messageFlow 안에서 구분되므로 발송 요청 경로는 /api/omni로 동일합니다.

{
  "destinations": [{ "to": "01000000000" }],
  "messageFlow": [
    { "alimtalk": { "msgType": "AT", "text": "주문 안내 메시지입니다." } },
    { "sms": { "from": "01000000000", "text": "알림톡 대체 문자입니다." } }
  ]
}

{
  "destinations": [{ "to": "01000000000" }],
  "messageFlow": [
    { "alimtalk": { "msgType": "AT", "text": "안내 메시지입니다." } },
    { "rcs": { "serviceType": "RCS", "msgType": "RS", "content": { "description": "RCS 대체 메시지입니다." } } },
    { "mms": { "from": "01000000000", "subject": "대체 안내", "text": "RCS 실패 시 LMS 대체 발송입니다." } }
  ]
}

통합 RCS와 안드로이드 RCS

RCS는 크게 통합 RCS와 안드로이드 RCS 규격으로 나뉩니다. 별도 요구가 없다면 iOS와 안드로이드를 함께 지원하는 통합 RCS를 먼저 검토하는 것을 권장합니다.

치환메시지

치환메시지는 메시지 본문/제목에 치환 예약어를 지정하고, 수신자별 값으로 치환해 발송하는 방식입니다.

• 메시지 내용(text) 또는 제목(title) 안에 #{key} 형태의 치환 예약어를 지정합니다.
• 수신정보(destinations)의 replaceWords에 치환값을 JSON 형태로 입력합니다.
• 실제 단말에는 replaceWords 값으로 치환된 최종 문장이 전달됩니다.

메시지 내용(text)

안녕하세요 #{name}님,
#{orderName} 주문이 #{status} 상태입니다.

치환 변수(replaceWords)

{
  "name": "홍길동",
  "orderName": "무선 키보드",
  "status": "배송중"
}

최종 단말 메시지

안녕하세요 홍길동님,
무선 키보드 주문이 배송중 상태입니다.

멱등성 키

멱등성 키는 동일 요청의 중복 처리를 방지하기 위한 식별값입니다.

• 멱등성 키 필드: idempotencyKey
• 유효시간 필드: idempotencyTtl(초)
• 네트워크 재시도/타임아웃 상황에서도 같은 키로 재요청하면 중복 발송을 줄일 수 있습니다.
• 업무 단위(주문번호, 인증 트랜잭션 번호) 기반 키 생성을 권장합니다.

최초 발신사업자 식별코드

originCID는 인터넷 문자 전송 시 최초 발신사업자를 특정하기 위해 삽입하는 식별코드이며, 특수한 유형의 부가통신사업자 등록번호(9자리 숫자)를 사용합니다.

• 적용 위치: messageFlow[].sms.originCID, messageFlow[].mms.originCID
• 형식: length: 9
• 최초 발신사업자가 재판매사업자이면 최초 재판매사업자 등록번호가 수록됩니다.
• 재판매사업자를 통하지 않고 문자중계사로 발송하면 문자중계사 등록번호가 수록됩니다.

예1) 기업 → 재판매사업자1 → 재판매사업자2 → 문자중계사 → 이동통신사
재판매사업자1의 등록번호가 삽입됩니다.

예2) 기업 → 문자중계사 → 이동통신사
문자중계사의 등록번호가 삽입됩니다.