발송

모든 채널은 통합 발송(omni) 하나로 보냅니다. 메시지를 여러 개 넣으면 앞 메시지가 실패할 때 다음 메시지로 대체발송됩니다. 아래 예시는 알림톡을 먼저 보내고, 실패하면 SMS로 대체발송합니다.

클라이언트 만들기와 API Key 설정은 설치를 참고하세요.

통합 발송과 대체발송

Java

import io.github.icommapi.bizgo.SendOptions;
import io.github.icommapi.bizgo.models.*;

SendResult result = client.send().omni(
        List.of(Destination.builder().to("01000000000").replaceWords(Map.of("name", "홍길동")).build()), // 최대 200명
        List.of(
                AlimtalkMessage.builder().senderKey("SENDER_KEY_EXAMPLE").templateCode("TEMPLATE_CODE_EXAMPLE")
                        .msgType("AT").text("#{name}님, 주문이 접수되었습니다.").build(),
                SmsMessage.builder().from("01000000000").text("#{name}님, 주문이 접수되었습니다.").build()), // 알림톡 실패 시
        SendOptions.builder()
                .idempotencyKey("order-20260923-0001") // 재시도해도 중복 발송되지 않음
                .ref("order-20260923-0001")            // 리포트에 그대로 돌아오는 참조값
                .build());

채널별 메시지 모델

모델 이름은 모든 SDK가 같습니다(Go만 SMSMessage처럼 약어를 대문자로 씁니다). 필드 이름은 API 이름(senderKey, from) 그대로이고, Python은 sender_key처럼 snake_case로도 쓸 수 있습니다(from은 예약어라 from_).

채널	모델	간편 메서드
SMS (90byte)	`SmsMessage`	`sms`
LMS (2,000byte)	`MmsMessage` (`fileKey` 없음)	`lms`
MMS	`MmsMessage` (`fileKey` 최대 3개)	`mms`
국제문자	`InternationalMessage`
RCS	`RcsMessage`
카카오 알림톡	`AlimtalkMessage`
카카오 브랜드메시지	`BrandMessage`
네이버 톡톡	`NaverTalkMessage`

SMS·LMS·MMS는 간편 메서드로 수신자와 본문만 넘겨 보낼 수 있습니다. 예시는 설치를 참고하세요.

보내기 전 검증

SDK는 요청을 보내기 전에 검사하고, 잘못되면 서버에 보내지 않고 검증 오류를 냅니다. 오류에는 필드 경로와 이유만 담기고, 전화번호 같은 입력값은 담기지 않습니다.

필수 필드, 모델에 없는 필드(오타), 허용 값, 수신자 200명 제한.
바이트 길이(SMS 90byte, LMS 2,000byte 등, EUC-KR 기준)와 EUC-KR 범위 밖 문자(이모지).
조건부 필수: 다른 필드 값에 따라 필수가 되는 필드. 알림톡은 아래 두 방식에 따라 필수 필드가 다릅니다.

알림톡 발송 방식	필요한 값
전문 발송 (`sendType` 없음)	`msgType`(`AT` 텍스트형, `AI` 이미지형)과 `text`. 빠지면 서버가 A523으로 거절하므로 SDK가 먼저 막습니다. `msgType`은 템플릿 조회 결과의 값을 그대로 쓰면 됩니다.
템플릿 자동 치환 (`sendType: template`)	`senderKey`·`templateCode`만 보내고, 모든 수신자에 `replaceWords`가 있어야 합니다.

중복 발송 막기 (idempotencyKey)

idempotencyKey를 주면 같은 키로 다시 보내도 중복 발송되지 않습니다. 네트워크 오류로 재시도할 때를 위해 넣기를 권장합니다.

비즈고는 키와 함께 idempotencyTtl(0~86400초)을 요구합니다(없으면 A309). TTL을 생략하면 SDK가 86400초(24시간)를 채워 보냅니다. 직접 준 값(0 포함)은 그대로 보내고, 키가 없으면 TTL도 보내지 않습니다.
같은 키로 이미 접수된 수신자는 결과의 duplicates에 들어가며(A301), 다시 발송되지 않습니다.

발송 결과 읽기

발송 결과는 접수 결과입니다. 최종 수신 결과는 리포트로 받습니다.

결과	의미
`msgKeys`	접수된 메시지 키. 리포트와 개별 조회에 씁니다.
`failed`	접수 단계에서 거절된 수신자 (없으면 빈 목록)
`duplicates`	같은 `idempotencyKey`로 이미 접수된 수신자 (A301, 다시 발송되지 않음)

언어별 이름은 Java getMsgKeys(), Python msg_keys, Go MsgKeys(), PHP msgKeys(), C# MsgKeys입니다.

이미지 메시지 (MMS)

이미지를 먼저 올려 fileKey를 받은 뒤 MMS로 보냅니다. MMS 이미지는 jpg, 최대 300KB이며, 넘으면 보내기 전에 오류가 납니다. RCS·브랜드메시지 이미지도 같은 방식으로 올립니다.

Java

FileUploadResult uploaded = client.files().uploadMms(Path.of("banner.jpg"));
client.send().mms("01000000000", "01000000000", "이미지 안내", List.of(uploaded.getFileKey()));

client.files().uploadRcs(Path.of("card.png"));                                // -> getMedia()
client.files().uploadBrandMessage(Path.of("wide.jpg"), BrandImageKind.WIDE);  // -> getImgUrl()

파일은 한 번만 읽어 재시도할 때 같은 내용을 다시 씁니다. 업로드는 HTTP 429일 때만 재시도합니다.