@awesome-message/sdk

Awesome Message SDK

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

목차

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

지원 환경

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

설치

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 발신번호 관리	📖 문서

빠른 시작

1. 클라이언트 생성

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);

2. 카카오 채널 등록 및 인증

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. 친구톡 메시지 발송

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 상태 코드에 따라 자동으로 적절한 예외 클래스로 변환합니다:

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를 사용할 수 없습니다. 대신 다음과 같은 방식을 권장합니다:

Next.js API Routes 예시

// 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 }
    );
  }
}

Express.js 예시

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는 일관성 있게 사용하세요