카카오 브랜드 메시지 및 음성 메시지 발송 예제를 추가하고, 관련 스키마를 개선하여 메시지 전송 기능을 확장함. Next.js 예제의 패키지 의존성을 업데이트하여 최신 버전으로 유지함.

Author: Palbahngmiyine

examples/javascript/common/src/kakao/send/send_bms.js

@@ -0,0 +1,33 @@
+/**
+ * 카카오 브랜드 메시지 발송 예제
+ * 현재 targeting 타입 중 M, N의 경우는 카카오 측에서 인허가된 채널만 사용하실 수 있습니다.
+ * 그 외의 모든 채널은 I 타입만 사용 가능합니다.
+ */
+const {SolapiMessageService} = require('solapi');
+const messageService = new SolapiMessageService(
+  'ENTER_YOUR_API_KEY',
+  'ENTER_YOUR_API_SECRET',
+);
+
+// 단일 발송 예제
+messageService
+  .send({
+    to: '수신번호',
+    from: '계정에서 등록한 발신번호 입력',
+    kakaoOptions: {
+      pfId: '연동한 비즈니스 채널의 pfId',
+      templateId: '등록한 브랜드 메시지 템플릿의 ID',
+      variables: {},
+      // 템플릿 내 치환문구(변수)가 있는 경우 추가, 반드시 key, value 모두 string으로 기입해야 합니다.
+      /*
+      variables: {
+        "변수명": "임의의 값"
+      }
+      */
+      // 현재 BMS(브랜드 메시지)는 문자로의 대체발송이 비활성화 됩니다.
+      bms: {
+        targeting: 'I',
+      },
+    },
+  })
+  .then(res => console.log(res));

examples/javascript/common/src/voice/send_voice_message.js

@@ -0,0 +1,25 @@
+/**
+ * 음성 메시지 발송 예제
+ * 음성 메시지에 대한 자세한 내용은 아래 링크를 참고해주세요.
+ * @see https://developers.solapi.com/references/voice
+ * 문서상 DTMF는 유선 전화등에서 들을 수 있는 다이얼 신호들을 뜻합니다.
+ * @see https://en.wikipedia.org/wiki/DTMF_signaling
+ */
+const {SolapiMessageService} = require('solapi');
+const messageService = new SolapiMessageService(
+  'ENTER_YOUR_API_KEY',
+  'ENTER_YOUR_API_SECRET',
+);
+
+messageService.send({
+  to: '수신번호',
+  from: '발신번호',
+  text: '음성 메시지 테스트입니다, 실제 수신자에게 들리는 내용입니다.',
+  voiceOptions: {
+    voiceType: 'FEMALE', // 필수값, MALE 혹은 FEMALE만 선택 가능합니다
+    // headerMessage: '보이스 메시지 테스트', // 메시지 시작에 나오는 머릿말, 최대 135자까지 가능합니다.
+    // tailMessage: '보이스 메시지 테스트', // 통화가 끝나고 나오는 꼬릿말, 상담원 연결 시 나오지 않습니다, 머리말(headerMessage)이 있어야 적용됩니다.
+    // replyRange: 1, // 수신자가 누를 수 있는 다이얼 값의 범위, 1~9까지 가능하며 counselorNumber와 함께 사용할 수 없습니다.
+    // counselorNumber: '상담번호, 예) 029302266', // 수신자가 0번을 눌렀을 때 연결되는 상담번호, replyRange와 함께 사용할 수 없습니다.
+  },
+});

examples/nextjs/package.json

@@ -9,18 +9,18 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "@next/env": "^15.2.1",
-    "jotai": "^2.12.1",
-    "motion": "^12.4.10",
-    "next": "^15.2.1",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "solapi": "^5",
-    "zod": "^3.24.2"
+    "@next/env": "^15.3.5",
+    "jotai": "^2.12.5",
+    "motion": "^12.23.3",
+    "next": "^15.3.5",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "solapi": "latest",
+    "zod": "^4.0.5"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
-    "@types/node": "^20",
+    "@types/node": "^24",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "tailwindcss": "^4",

src/lib/effectErrorHandler.ts

@@ -124,12 +124,43 @@ export const runSafePromise = <E, A>(
   );
 };
 
+// MessageNotReceivedError의 프로퍼티를 포함한 확장 Error 타입
+interface MessageNotReceivedErrorCompat extends Error {
+  readonly failedMessageList: ReadonlyArray<
+    import('../models/responses/sendManyDetailResponse').FailedMessage
+  >;
+  readonly totalCount: number;
+}
+
 // Effect 에러를 기존 Error로 변환 (하위 호환성)
 export const toCompatibleError = (effectError: unknown): Error => {
+  // MessageNotReceivedError의 경우 특별 처리하여 원본 프로퍼티 보존
+  if (effectError instanceof EffectError.MessageNotReceivedError) {
+    const error = new Error(
+      effectError.message,
+    ) as MessageNotReceivedErrorCompat;
+    error.name = 'MessageNotReceivedError';
+    // failedMessageList와 totalCount 프로퍼티 보존
+    Object.defineProperty(error, 'failedMessageList', {
+      value: effectError.failedMessageList,
+      writable: false,
+      enumerable: true,
+      configurable: false,
+    });
+    Object.defineProperty(error, 'totalCount', {
+      value: effectError.totalCount,
+      writable: false,
+      enumerable: true,
+      configurable: false,
+    });
+    delete error.stack;
+    return error;
+  }
+
   const formatted = formatError(effectError);
   // 하위 호환성을 위해 여전히 Error 사용하지만 스택 제거
   const error = new Error(formatted);
-  error.name = 'ApplicationError';
+  error.name = 'FromSolapiError';
   delete error.stack;
   return error;
 };

src/models/base/kakao/kakaoOption.ts

@@ -16,13 +16,7 @@ export class VariableValidationError extends Data.TaggedError(
 }
 
 const kakaoOptionBmsSchema = Schema.Struct({
-  targeting: Schema.optional(
-    Schema.Enums({
-      M: 'M',
-      N: 'N',
-      I: 'I',
-    }),
-  ),
+  targeting: Schema.Literal('I', 'M', 'N'),
 });
 
 // Constants for variable validation

src/models/requests/voice/voiceOption.ts

@@ -1,12 +1,10 @@
 import {Schema} from 'effect';
 
 export const voiceOptionSchema = Schema.Struct({
-  voiceType: Schema.Literal('FEMALE', 'MALE').pipe(
-    Schema.optionalWith({default: () => 'FEMALE' as const}),
-  ),
+  voiceType: Schema.Literal('FEMALE', 'MALE'),
   headerMessage: Schema.optional(Schema.String),
   tailMessage: Schema.optional(Schema.String),
-  replyRate: Schema.optional(Schema.Literal(1, 2, 3)),
+  replyRange: Schema.optional(Schema.Literal(1, 2, 3, 4, 5, 6, 7, 8, 9)),
   counselorNumber: Schema.optional(Schema.String),
 });