Awesome Message SDK

Node.js 환경에서 Awesome Message 서비스와 통합할 수 있는 TypeScript/JavaScript SDK입니다.

목차

- 지원 환경
- 설치
- 주요 기능
- 클라이언트 목록
- 빠른 시작
- 에러 핸들링
- 브라우저에서 사용하려면?
- 주의사항

지원 환경

- ✅ Node.js 16.8.0 이상
- ✅ TypeScript 5.8+ 지원
- ❌ 브라우저 환경 미지원 (보안상 이유로 서버 사이드 전용)

설치

``bash
npm install @awesome-message/sdk


또는

| 클라이언트 | 설명 | 문서 |
| -------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------- |
| AdminClient | 클라이언트 생성 및 관리 | 📖 문서 |
| KakaoChannelClient | 카카오 비즈니스 채널 관리 | 📖 문서 |
| KakaoFriendtalkImageClient | 친구톡 이미지 업로드 및 관리 | 📖 문서 |
| KakaoFriendtalkTemplateClient | 친구톡 템플릿 메시지 관리 및 발송 | 📖 문서 |
| KakaoFriendtalkFreestyleClient | 친구톡 자유형 메시지 발송 | 📖 문서 |
| KakaoFriendtalkResultClient | 친구톡 메시지 발송 결과 조회 | 📖 문서 |
| KakaoAlimtalkMessageClient | 알림톡 메시지 발송 및 결과 조회 | 📖 문서 |
| KakaoAlimtalkTemplateClient | 알림톡 템플릿 관리 | 📖 문서 |
| KakaoAlimtalkFailbackClient | 알림톡 SMS Failback 설정 | 📖 문서 |
| PushTokenClient | Push 토큰 관리 | 📖 문서 |
| PushMessageClient | Push 메시지 발송 | 📖 문서 |
| PushReservationClient | Push 예약/반복 발송 | 📖 문서 |
| PushTagClient | Push 태그 관리 | 📖 문서 |
| PushStatsClient | Push 통계 조회 | 📖 문서 |
| PushUidClient | Push UID 관리 | 📖 문서 |
| SmsClient | SMS/LMS/MMS 메시지 발송 | 📖 문서 |
| SmsTemplateClient | SMS 템플릿 관리 | 📖 문서 |
| SmsTagClient | SMS 태그 관리 | 📖 문서 |
| SmsAttachmentClient | SMS 첨부파일 관리 | 📖 문서 |
| SmsManagementClient | SMS 발신번호 관리 | 📖 문서 |

빠른 시작

$3

`typescript
import { AdminClient } from "@awesome-message/sdk";

const adminClient = new AdminClient({
accessKeyId: process.env.ACCESS_KEY_ID!,
secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

// externalId는 기존에 사용하던 고유 식별자를 사용합니다
// (브랜드, 사이트, 클라이언트, 프로젝트 단위 등 자유롭게 설정 가능)
const client = await adminClient.createClient({
externalId: "my-ecommerce-site",
name: "이커머스 사이트",
});

console.log("클라이언트 생성 완료:", client);
`

$3

`typescript
import { KakaoChannelClient } from "@awesome-message/sdk";

const kakaoChannelClient = new KakaoChannelClient({
accessKeyId: process.env.ACCESS_KEY_ID!,
secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

// 1. 채널 등록
const channel = await kakaoChannelClient.createChannel("my-ecommerce-site", {
plusFriendId: "@mycompany",
phoneNo: "01500000000",
categoryCode: "01800010001", // 카테고리는 getChannelCategories()로 조회 가능
});

// 2. 카카오톡 앱에서 받은 토큰으로 인증
const authenticatedChannel = await kakaoChannelClient.authenticateChannelToken(
"my-ecommerce-site",
{
plusFriendId: "@mycompany",
token: 123456, // 카카오톡 앱에서 받은 6자리 숫자
}
);

console.log("인증 완료된 채널:", authenticatedChannel);
`

$3

`typescript
import { KakaoFriendtalkFreestyleClient } from "@awesome-message/sdk";

const friendtalkClient = new KakaoFriendtalkFreestyleClient({
accessKeyId: process.env.ACCESS_KEY_ID!,
secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

// 자유형 텍스트 메시지 발송
const result = await friendtalkClient.sendFriendtalkTextMessage(
"my-ecommerce-site",
{
senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881", // 채널 인증 후 받은 발신키
content: "안녕하세요! 새로운 할인 이벤트를 시작합니다.",
recipientList: [
{ recipientNo: "01234567890" },
{ recipientNo: "01987654321" },
],
buttons: [
{
name: "이벤트 보기",
type: "WL",
linkMo: "https://example.com/event",
},
],
}
);

console.log("메시지 발송 결과:", result);
`

에러 핸들링

SDK는 HTTP 상태 코드에 따라 자동으로 적절한 예외 클래스로 변환합니다:

`typescript
import {
InvalidParameterException,
AccessDeniedException,
NotFoundException,
InternalServerErrorException,
} from "@awesome-message/sdk";

try {
const result = await adminClient.createClient({
externalId: "my-client",
name: "테스트 클라이언트",
});
} catch (error) {
if (error instanceof InvalidParameterException) {
console.error("잘못된 요청 파라미터:", error.message);
} else if (error instanceof AccessDeniedException) {
console.error("권한 없음:", error.message);
} else if (error instanceof NotFoundException) {
console.error("리소스를 찾을 수 없음:", error.message);
} else if (error instanceof InternalServerErrorException) {
console.error("서버 내부 오류:", error.message);
} else {
console.error("알 수 없는 오류:", error);
}
}
`

브라우저에서 사용하려면?

보안상의 이유로 브라우저에서는 직접 SDK를 사용할 수 없습니다. 대신 다음과 같은 방식을 권장합니다:

$3

`typescript
// pages/api/send-message.ts 또는 app/api/send-message/route.ts
import { KakaoFriendtalkFreestyleClient } from "@awesome-message/sdk";

const friendtalkClient = new KakaoFriendtalkFreestyleClient({
accessKeyId: process.env.ACCESS_KEY_ID!,
secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

export async function POST(request: Request) {
try {
const { recipients, message } = await request.json();

const result = await friendtalkClient.sendFriendtalkTextMessage(
"my-client",
{
senderKey: process.env.KAKAO_SENDER_KEY!,
content: message,
recipientList: recipients,
}
);

return Response.json({ success: true, result });
} catch (error) {
return Response.json(
{ success: false, error: error.message },
{ status: 500 }
);
}
}
`

$3

`typescript
import express from "express";
import { KakaoFriendtalkFreestyleClient } from "@awesome-message/sdk";

const app = express();
const friendtalkClient = new KakaoFriendtalkFreestyleClient({
accessKeyId: process.env.ACCESS_KEY_ID!,
secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

app.post("/api/send-message", async (req, res) => {
try {
const { recipients, message } = req.body;

const result = await friendtalkClient.sendFriendtalkTextMessage(
"my-client",
{
senderKey: process.env.KAKAO_SENDER_KEY!,
content: message,
recipientList: recipients,
}
);

res.json({ success: true, result });
} catch (error) {
res.status(500).json({ success: false, error: error.message });
}
});
``

주의사항

- 🔑 보안: 액세스 키와 시크릿 키는 환경변수로 관리하고 절대 클라이언트 사이드에 노출하지 마세요
- 🔄 비동기 처리: 모든 API 호출은 비동기(async/await)로 처리됩니다
- 🖥️ 서버 전용: Node.js 환경에서만 실행됩니다 (브라우저 사용 불가)
- 📋 타입 안정성: TypeScript를 사용하면 컴파일 타임에 타입 검사를 받을 수 있습니다
- 🏷️ externalId: 클라이언트 식별을 위한 externalId는 일관성 있게 사용하세요