Awesome Message SDK for admin, messaging, and notification services
Node.js 환경에서 Awesome Message 서비스와 통합할 수 있는 TypeScript/JavaScript SDK입니다.
- 지원 환경
- 설치
- 주요 기능
- 클라이언트 목록
- 빠른 시작
- 에러 핸들링
- 브라우저에서 사용하려면?
- 주의사항
- ✅ Node.js 16.8.0 이상
- ✅ TypeScript 5.8+ 지원
- ❌ 브라우저 환경 미지원 (보안상 이유로 서버 사이드 전용)
``bash`
npm install @awesome-message/sdk또는
yarn add @awesome-message/sdk또는
pnpm add @awesome-message/sdk
- 관리자 기능: 클라이언트 생성 및 관리
- 카카오 비즈니스 메시지:
- 카카오 비즈니스 채널 관리 (등록, 인증, 조회, 삭제)
- 친구톡 이미지 업로드 및 관리
- 친구톡 템플릿 메시지 (생성, 수정, 삭제, 발송)
- 친구톡 자유형 메시지 발송 (텍스트, 이미지, 와이드, 커머스 등)
- 친구톡 메시지 발송 결과 조회
- 카카오 알림톡:
- 알림톡 일반/인증 메시지 발송
- 알림톡 템플릿 관리 (등록, 수정, 조회, 삭제)
- 알림톡 발송 실패 시 SMS Failback 설정
- Push 알림:
- FCM/APNs 토큰 관리
- UID/태그 기반 타겟팅 발송
- 예약/반복 발송 스케줄 관리
- 발송 통계/분석
- SMS:
- SMS/LMS/MMS 메시지 발송
- 템플릿 관리
- 태그 기반 타겟팅
- 첨부파일 관리
- 발신번호 관리
- 향후 지원 예정:
- 이메일
| 클라이언트 | 설명 | 문서 |
| -------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------- |
| 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 발신번호 관리 | 📖 문서 |
`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);
`
`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);
`
`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를 사용할 수 없습니다. 대신 다음과 같은 방식을 권장합니다:
`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 }
);
}
}
`
`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는 일관성 있게 사용하세요