메시지 발송 예제

해당 페이지에서는 COOLSMS Java/Kotlin SDK를 이용하여 메시지를 발송하는 방법에 대해 가이드하고 있습니다. Java/Kotlin SDK를 통해 빠르고 쉽게 메시지를 발송해보세요!

정보

• 해당 페이지에서 작성된 모든 코드는 Java로 작성되었습니다.
  • 해당 코드에서의 기반은 Spring Framework로 작성하는 것을 전제하고 있습니다.
• 각 발송 예시에 대한 결과 값 표시 기능은 현재 준비중에 있습니다.
• 해당 예제는 Java/Kotlin SDK 4.2.7 버전을 기준으로 작성되었습니다.
• 여러 건 발송이나 더 다양한 예제를 확인해보고 싶으신 경우 SDK 샘플 코드 페이지를 확인해보세요!

주의

해당 페이지에서 안내되는 코드들은 import 구문이 제외되어 있습니다.

위험

• 발송 요청을 하실 때 반드시 발신번호와 수신번호는 01012345678 형식으로 요청하셔야 합니다!
• +, -, * 특수문자 등 삽입 불가

// 예시, 다른 파라미터 생략, json 형식
{
  "from": "029302266",
  "to": "029302266"
}

🔗 SDK Reference(send 메소드 명세 확인)

🔗 SDK 샘플 코드 페이지

환경설정

연동하실 프로젝트로 이동하신 다음 선호하시는 환경을 선택하여 아래 코드를 추가하여 SDK를 설치해보세요!

Maven

pom.xml

<dependency>
  <groupId>net.nurigo</groupId>
  <artifactId>sdk</artifactId>
  <version>4.2.7</version>
</dependency>

Gradle

build.gradle

implementation 'net.nurigo:sdk:4.2.7'

Gradle(Kotlin)

build.gradle.kts

implementation("net.nurigo:sdk:4.2.7")

문자 발송

Java/Kotlin으로 문자를 발송하는 방법에 대해 안내합니다.
연동하실 코드로 이동하신 다음, 아래의 각 유형별 문자 발송예시를 참고하셔서 원하시는 유형의 문자를 발송해보세요!

단문 문자(SMS) 발송

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");
// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setText("SMS는 한글 45자, 영자 90자까지 입력할 수 있습니다.");

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

장문 문자(LMS) 발송

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");
// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setText("한글 45자, 영자 90자 이상 입력되면 자동으로 LMS타입의 문자메시지가 발송됩니다. 0123456789 ABCDEFGHIJKLMNOPQRSTUVWXYZ");
// message.setSubject("문자 제목 입력"); // LMS, MMS 전용 옵션, SMS에서 해당 파라미터 추가될 경우 자동으로 LMS로 변환됩니다!

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

사진 문자(MMS) 발송

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");

// 메소드 정의 부분에서 throws IOException이 미리 선언되거나, try catch를 통해 예외처리를 진행하셔야 합니다.
ClassPathResource resource = new ClassPathResource("이미지 경로");
File file = resource.getFile();

// 예시는 ClassPathResource 객체를 변환하지만 File 객체를 그대로 전달하여도 동작합니다! 단, 200kb 이내의 jpg 파일을 업로드 해주세요.
String imageId = messageService.uploadFile(file, StorageType.MMS, null);

Message message = new Message();
// 발신번호 및 수신번호는 반드시 01012345678 형태로 입력되어야 합니다.
message.setFrom("발신번호 입력");
message.setTo("수신번호 입력");
message.setText("MMS는 한글 45자, 영자 90자 이상을 입력할 수 있습니다. 0123456789 ABCDEFGHIJKLMNOPQRSTUVWXYZ");
message.setImageId(imageId);

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

해외 문자(SMS 전용) 발송

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");
// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setText("SMS는 한글 45자, 영자 90자까지 입력할 수 있습니다.");
message.setCountry("1"); // 미국 국가번호, 국가번호 뒤에 추가로 번호가 붙는 국가들은 붙여서 기입해야 합니다. 예) 1 441 -> "1441"

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

카카오 알림톡/친구톡 발송

Java/Kotlin으로 알림톡/친구톡을 발송하는 방법에 대해 안내합니다.

연동하실 코드로 이동하신 다음, 아래의 각 유형별 문자 발송예시를 참고하셔서 원하시는 유형의 알림톡/친구톡을 발송해보세요!

알림톡 발송

주의

알림톡 발송 시 text 항목에 데이터를 기입하지 않아야 합니다.

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");

KakaoOption kakaoOption = new KakaoOption();
kakaoOption.setPfId("연동한 비즈니스 채널의 pfId");
kakaoOption.setTemplateId("등록한 알림톡 템플릿의 ID");

// disableSms를 true로 설정하실 경우 문자로 대체발송 되지 않습니다.
// kakaoOption.setDisableSms(true);

// 치환문구(예) #{변수명})가 있을 경우 아래의 코드를 추가해보세요!
 /*
HashMap<String, String> variables = new HashMap<>();
variables.put("#{변수명1}", "치환문구 값 입력");
variables.put("#{변수명2}", "치환문구 값 입력2");
kakaoOption.setVariables(variables);
*/

// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setKakaoOptions(kakaoOption);

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

카카오톡 해외 번호 가입자에 대한 알림톡 발송방법

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");

KakaoOption kakaoOption = new KakaoOption();
kakaoOption.setPfId("연동한 비즈니스 채널의 pfId");
kakaoOption.setTemplateId("등록한 알림톡 템플릿의 ID");

// disableSms를 true로 설정하실 경우 문자로 대체발송 되지 않습니다.
// kakaoOption.setDisableSms(true);

// 치환문구(예) #{변수명})가 있을 경우 아래의 코드를 추가해보세요!
 /*
HashMap<String, String> variables = new HashMap<>();
variables.put("#{변수명1}", "치환문구 값 입력");
variables.put("#{변수명2}", "치환문구 값 입력2");
kakaoOption.setVariables(variables);
*/

// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setKakaoOptions(kakaoOption);

// 해당 수신번호의 국가번호를 입력, 예) 미국: "1", 일본: "81"
// 국가번호 뒤에 추가로 번호가 붙는 국가들은 붙여서 기입해야 합니다. 예) 1 441 -> "1441"
message.setCountry("국가번호 입력");

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

친구톡 발송

친구톡에서는 버튼과 이미지를 모두 포함하여 발송하실 수 있습니다.
아래의 예제등을 통해 친구톡을 발송해보세요!

단순 텍스트 친구톡 발송

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");

KakaoOption kakaoOption = new KakaoOption();
kakaoOption.setPfId("연동한 비즈니스 채널의 pfId");
kakaoOption.setVariables(null);


// disableSms를 true로 설정하실 경우 문자로 대체발송 되지 않습니다.
// kakaoOption.setDisableSms(true);

// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setText("2,000 byte 이내의 메시지 입력");
message.setKakaoOptions(kakaoOption);

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

버튼을 포함한 친구톡 발송

위험

친구톡 버튼은 최대 5개 까지만 삽입하실 수 있습니다.

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");

KakaoOption kakaoOption = new KakaoOption();
kakaoOption.setPfId("연동한 비즈니스 채널의 pfId");
kakaoOption.setVariables(null);

// disableSms를 true로 설정하실 경우 문자로 대체발송 되지 않습니다.
// kakaoOption.setDisableSms(true);

ArrayList<KakaoButton> kakaoButtons = new ArrayList<>();
// 웹링크 버튼
KakaoButton kakaoWebLinkButton = new KakaoButton(
        "테스트 버튼1", KakaoButtonType.WL,
        "https://example.com", "https://example.com",
        null, null
);

// 앱링크 버튼
KakaoButton kakaoAppLinkButton = new KakaoButton(
        "테스트 버튼2", KakaoButtonType.AL,
        null, null,
        "exampleapp://test", "exampleapp://test"
);

// 봇 키워드 버튼, 버튼을 클릭하면 버튼 이름으로 수신자가 발신자에게 채팅을 보냅니다.
KakaoButton kakaoBotKeywordButton = new KakaoButton(
        "테스트 버튼3", KakaoButtonType.BK, null, null, null, null
);

// 메시지 전달 버튼, 버튼을 클릭하면 버튼 이름과 친구톡 메시지 내용을 포함하여 수신자가 발신자에게 채팅을 보냅니다.
KakaoButton kakaoMessageDeliveringButton = new KakaoButton(
        "테스트 버튼4", KakaoButtonType.MD, null, null, null, null
);

/*
 * 상담톡 전환 버튼, 상담톡 서비스를 이용하고 있을 경우 상담톡으로 전환. 상담톡 서비스 미이용시 해당 버튼 추가될 경우 발송 오류 처리됨.
 * 아래의 링크를 참고하셔서 상담톡 딜러사를 확인해보세요! COOLSMS는 상담톡 서비스를 제공하지 않습니다.
 * https://business.kakao.com/info/bizmessage/
 */
/*KakaoButton kakaoBotCustomerButton = new KakaoButton(
        "테스트 버튼6", KakaoButtonType.BC, null, null, null, null
);*/

// 봇전환 버튼, 해당 비즈니스 채널에 카카오 챗봇이 없는 경우 동작안함.
// KakaoButton kakaoBotTransferButton = new KakaoButton("테스트 버튼7", KakaoButtonType.BT, null, null, null, null);

kakaoButtons.add(kakaoWebLinkButton);
kakaoButtons.add(kakaoAppLinkButton);
kakaoButtons.add(kakaoBotKeywordButton);
kakaoButtons.add(kakaoMessageDeliveringButton);

kakaoOption.setButtons(kakaoButtons);

// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setText("2,000 byte 이내의 메시지 입력");
message.setKakaoOptions(kakaoOption);

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

이미지를 포함한 친구톡 발송

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");

// 해당 예제는 ClassPathResource로 예시가 되어있지만 File 객체로 대체하여도 동작합니다!
ClassPathResource resource = new ClassPathResource("이미지 경로");
File file = resource.getFile();
// 이미지 크기는 가로 500px 세로 250px 이상이어야 하며 가로 세로 비율이 반드시 2:1로 유지되어야 합니다, 링크도 필수로 기입해주세요.
String imageId = messageService.uploadFile(file, StorageType.KAKAO, "링크 입력");

KakaoOption kakaoOption = new KakaoOption();
kakaoOption.setPfId("연동한 비즈니스 채널의 pfId");
kakaoOption.setVariables(null);

// disableSms를 true로 설정하실 경우 문자로 대체발송 되지 않습니다.
// kakaoOption.setDisableSms(true);

// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setText("2,000 byte 이내의 메시지 입력");
message.setKakaoOptions(kakaoOption);

try {
  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}

예약 발송

예약 발송은 모든 발송 수단(문자, 알림톡 등)에서 사용할 수 있는 기능입니다.
예약 발송 기능은 앞서 안내된 각 코드의 send 메소드에서 두 번째 파라미터로 날짜(Java Instant 또는 Kotlin Instant(kotlinx datetime) 타입 허용)를 입력하면 해당 날짜로 예약 접수가 진행됩니다.

주의

예약 날짜가 현재 시각보다 더 과거의 시간일 경우 즉시 발송 접수가 진행됩니다.

발송 예시

발송 예시는 SMS(단문 문자)만 제공되지만, 모든 발송수단에서 사용할 수 있습니다!

Java

DefaultMessageService messageService =  NurigoApp.INSTANCE.initialize("API 키 입력", "API 시크릿 키 입력", "https://api.coolsms.co.kr");
// Message 패키지가 중복될 경우 net.nurigo.sdk.message.model.Message로 치환하여 주세요
Message message = new Message();
message.setFrom("계정에서 등록한 발신번호 입력");
message.setTo("수신번호 입력");
message.setText("SMS는 한글 45자, 영자 90자까지 입력할 수 있습니다.");

try {
  // Java LocalDateTime, Instant 기준, Kolintx의 datetime 내 Instant 타입을 넣어도 동작합니다!
  LocalDateTime localDateTime = LocalDateTime.parse("2022-05-30 00:00:00", DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
  ZoneOffset zoneOffset = ZoneId.systemDefault().getRules().getOffset(localDateTime);
  Instant instant = localDateTime.toInstant(zoneOffset);

  // send 메소드로 ArrayList<Message> 객체를 넣어도 동작합니다!
  messageService.send(message, instant);
} catch (NurigoMessageNotReceivedException exception) {
  // 발송에 실패한 메시지 목록을 확인할 수 있습니다!
  System.out.println(exception.getFailedMessageList());
  System.out.println(exception.getMessage());
} catch (Exception exception) {
  System.out.println(exception.getMessage());
}