@sendgo/nestjs

NestJS에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 NestJS 모듈

@sendgo/nestjs는 @sendgo/node 코어를 확장한 NestJS 전용 모듈입니다. DynamicModule 기반의 forRoot / forRootAsync 등록, 전역(Global) 프로바이더, 생성자 주입(DI)을 완벽하게 제공합니다.

목차

• 설치
• 빠른 시작
• 비동기 설정 (ConfigService)
• 상세 사용법
  • 알림톡
  • 친구톡
  • SMS / LMS / MMS
• 서비스 클래스 패턴
• 예외 처리
• 설정 옵션
• 자주 묻는 질문 (FAQ)
• 관련 패키지

설치

npm install @sendgo/nestjs @sendgo/node

@nestjs/common은 peerDependency이므로 NestJS 프로젝트에 이미 설치되어 있어야 합니다.

빠른 시작

1단계 — 모듈 등록 (app.module.ts)

import { Module } from '@nestjs/common';
import { SendgoModule } from '@sendgo/nestjs';

@Module({
  imports: [
    SendgoModule.forRoot({
      accessKey: process.env.SENDGO_ACCESS_KEY!,
      secretKey: process.env.SENDGO_SECRET_KEY!,
      kakaoSenderKey: process.env.SENDGO_KAKAO_KEY,
      smsSenderKey: process.env.SENDGO_SMS_KEY,
      apiVersion: 'v2',
    }),
  ],
})
export class AppModule {}

SendgoModule은 @Global()이므로 한 번만 등록하면 어느 모듈에서든 SendgoService를 주입할 수 있습니다.

2단계 — 서비스 주입 후 발송

import { Injectable } from '@nestjs/common';
import { SendgoService } from '@sendgo/nestjs';

@Injectable()
export class OrderService {
  constructor(private readonly sendgo: SendgoService) {}

  async confirm(phone: string, orderNo: string, amount: number) {
    await this.sendgo.alimtalk.send({
      templateCode: 'ORDER_CONFIRM_001',
      contacts: [
        { contact: phone, var1: orderNo, var2: `${amount.toLocaleString()}원` },
      ],
    });
  }
}

비동기 설정 (ConfigService)

환경변수를 @nestjs/config의 ConfigService로 주입해 설정을 구성할 수 있습니다.

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { SendgoModule } from '@sendgo/nestjs';

@Module({
  imports: [
    ConfigModule.forRoot(),
    SendgoModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        accessKey: config.getOrThrow('SENDGO_ACCESS_KEY'),
        secretKey: config.getOrThrow('SENDGO_SECRET_KEY'),
        kakaoSenderKey: config.get('SENDGO_KAKAO_KEY'),
        smsSenderKey: config.get('SENDGO_SMS_KEY'),
        apiVersion: config.get('SENDGO_API_VERSION') ?? 'v1',
      }),
    }),
  ],
})
export class AppModule {}

상세 사용법

모든 발송 메서드는 SendgoService의 게터(alimtalk, friendtalk, sms)를 통해 코어 클라이언트에 위임됩니다.

알림톡

// 다건 발송
await this.sendgo.alimtalk.send({
  templateCode: 'ORDER_CONFIRM_001',
  contacts: [
    { contact: '01011111111', name: '홍길동', var1: 'ORD-001', var2: '29,000원' },
    { contact: '01022222222', name: '김철수', var1: 'ORD-002', var2: '15,000원' },
  ],
});

// 예약 발송
await this.sendgo.alimtalk.send({
  templateCode: 'PROMO_SUMMER_2026',
  scheduleType: 'SCHEDULED',
  at: '2026-07-28 09:00:00',
  contacts: [{ contact: '01012345678', var1: '여름 한정 50% 할인' }],
});

// SMS 자동 대체 발송
await this.sendgo.alimtalk.send({
  templateCode: 'DELIVERY_START_001',
  replaceSms: 'Y',
  smsSubject: '[배송 시작 안내]',
  smsContent: '주문하신 상품이 출고되었습니다.\n송장번호: #{var2}',
  contacts: [{ contact: '01012345678', var1: 'ORD-001', var2: '1234567890' }],
});

친구톡

⚠️ Deprecated — 친구톡은 카카오 정책에 따라 2025-12-31 종료되었습니다. 2026-01-01 부터 친구톡 발송 요청은 카카오 측에서 브랜드메시지(자유형) 로 자동 대체 발송됩니다. 호출은 계속 성공하며, 자유 본문 타입(FT/FI/FW)을 개별 수신자에게 보내는 경로는 현재 이것뿐이므로 기존 코드를 당장 바꿀 필요는 없습니다.

다음의 경우에는 브랜드메시지를 사용하세요.

• 템플릿 기반 리치 타입 (FL/FC/FM/FP/FA)
• 채널 친구가 아닌 수신자 (targeting = N / I)
• 수신 동의한 전체 채널 친구 동보 (targeting = F)

메시지 타입은 1:1 대응되며 변환은 서버가 처리합니다 — FT→BT, FI→BI, FW→BW, FL→BL, FC→BC, FM→BM, FP→BP, FA→BA.

// 텍스트형
await this.sendgo.friendtalk.send({
  content: '안녕하세요! 7월 한정 특가 이벤트를 확인해보세요.',
  contacts: [{ contact: '01012345678' }],
});

// 이미지형
await this.sendgo.friendtalk.send({
  messageType: 'FI',
  content: '이번 주 특가 상품을 확인하세요!',
  imageUrl: 'https://cdn.example.com/banner.jpg',
  imageLink: 'https://example.com/event',
  contacts: [{ contact: '01012345678' }],
});

// 버튼 포함
await this.sendgo.friendtalk.send({
  content: '7월 쿠폰이 도착했습니다! 지금 바로 사용하세요.',
  buttons: [
    { name: '쿠폰 받기', type: 'WL', linkMo: 'https://example.com/coupon' },
    { name: '고객센터', type: 'WL', linkMo: 'https://example.com/cs' },
  ],
  contacts: [{ contact: '01012345678' }],
});

SMS / LMS / MMS

// SMS (90자 이하)
await this.sendgo.sms.sendSms({
  content: '[Sendgo] 인증번호: 123456 (5분 이내 입력)',
  contacts: [{ contact: '01012345678' }],
});

// LMS (장문, 2,000자 이하)
await this.sendgo.sms.sendLms({
  subject: '[중요] 서비스 점검 안내',
  content: '안녕하세요. 서비스 점검이 예정되어 있습니다.\n\n■ 일시: 2026-07-25 02:00 ~ 06:00',
  contacts: [{ contact: '01012345678' }],
});

// MMS (멀티미디어)
await this.sendgo.sms.sendMms({
  subject: '[이벤트] 7월 특가',
  content: '이번 달 특가 상품을 확인하세요!',
  contacts: [{ contact: '01011111111' }, { contact: '01022222222' }],
});

서비스 클래스 패턴

// notification.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { SendgoService, SendgoError } from '@sendgo/nestjs';

@Injectable()
export class NotificationService {
  private readonly logger = new Logger(NotificationService.name);

  constructor(private readonly sendgo: SendgoService) {}

  async sendVerificationCode(phone: string, code: string): Promise<void> {
    try {
      // 알림톡 우선, 실패 시 SMS 대체
      await this.sendgo.alimtalk.send({
        templateCode: 'VERIFY_CODE_001',
        replaceSms: 'Y',
        smsContent: `[인증] 인증번호: ${code} (5분 이내 입력)`,
        contacts: [{ contact: phone, var1: code }],
      });
    } catch (e) {
      if (e instanceof SendgoError) {
        this.logger.error(`Sendgo 인증번호 발송 실패: ${e.message}`);
      }
      throw e;
    }
  }
}

원본 코어 클라이언트가 필요하면 this.sendgo.client로 접근할 수 있습니다. 또한 Sendgo 클래스 토큰으로 코어 인스턴스를 직접 주입받는 것도 가능합니다.

import { Injectable } from '@nestjs/common';
import { Sendgo } from '@sendgo/node';

@Injectable()
export class OrderService {
  constructor(private readonly sendgo: Sendgo) {}
}

예외 처리

import { SendgoError } from '@sendgo/nestjs';

try {
  await this.sendgo.alimtalk.send({ /* ... */ });
} catch (e) {
  if (e instanceof SendgoError) {
    // e.errorCode, e.statusCode, e.endpoint 활용 가능
    switch (e.errorCode) {
      case 'INVALID_ACCESS_KEY':
      case 'INVALID_SECRET_KEY':
        // 인증키 오류 처리
        break;
      case 'INVALID_TEMPLATE_CODE':
        // 존재하지 않는 템플릿
        break;
      case 'PAYMENT_REQUIRED':
        // 크레딧 부족
        break;
      default:
        break;
    }
  }
  throw e;
}

설정 옵션

SendgoModule.forRoot() / forRootAsync()에 전달하는 SendgoConfig 값입니다.

| 키 | 타입 | 기본값 | 설명 | |----|------|--------|------| | accessKey | string | — | Sendgo 액세스 키 (필수) | | secretKey | string | — | Sendgo 시크릿 키 (필수) | | kakaoSenderKey | string | '' | 카카오 발신프로필 키 | | smsSenderKey | string | '' | SMS 발신자 키 | | apiVersion | 'v1' \| 'v2' | 'v1' | API 버전 | | baseUrl | string | 'https://sendgo.io' | API 기본 URL |

자주 묻는 질문 (FAQ)

Q. @sendgo/node와의 차이는 무엇인가요? A. @sendgo/node는 프레임워크 독립적인 순수 Node.js 코어 SDK입니다. @sendgo/nestjs는 이를 확장해 DynamicModule 등록, 전역 프로바이더, 생성자 주입 등 NestJS 통합을 추가합니다.

Q. NestJS 10, 11 모두 지원하나요? A. 네, @nestjs/common >=10.0.0을 peerDependency로 지원합니다.

Q. SendgoService 대신 코어 클라이언트를 직접 주입할 수 있나요? A. 네, Sendgo 클래스를 토큰으로 주입받으면 코어 인스턴스를 직접 사용할 수 있습니다.

Q. 테스트 시 Sendgo를 Mock 처리하려면? A. 테스트 모듈에서 SendgoService 또는 Sendgo 프로바이더를 mock 값으로 오버라이드하면 됩니다.

관련 패키지

| 언어/프레임워크 | 패키지 | GitHub | |----------------|--------|--------| | Node.js (순수) | @sendgo/node | node | | React / Next.js | @sendgo/react | react | | Vue / Nuxt | @sendgo/vue | vue | | Laravel | sendgo/laravel | laravel | | 전체 목록 | — | send-go GitHub 조직 |

브랜드메시지 · 짧은 URL

이 패키지는 코어(@sendgo/node)의 클라이언트를 그대로 노출하므로, 코어에 있는 채널이 모두 그대로 쓸 수 있습니다. 두 기능 모두 v2 전용입니다.

| 기능 | 접근 | |------|------| | 카카오 브랜드메시지 (친구톡의 후속 채널) | sendgo.brandMessage | | 짧은 URL (단축 + 클릭 반응 분석) | sendgo.shortUrl |

브랜드메시지는 채널 친구가 아닌 수신자에게도 보낼 수 있고(targeting = N), 수신 동의한 전체 채널 친구에게 동보 발송할 수도 있습니다(targeting = F).

짧은 URL 은 메시지 본문의 링크를 줄이고 클릭 반응(일별 추이·디바이스·유입경로·국가)을 집계합니다.

사용 예시와 파라미터는 코어 README 와 SDK 가이드 를 참고하세요.

관리 API — 채널·템플릿·발신번호 등록 (v2 전용)

SendgoService 가 코어의 관리 서비스를 그대로 노출합니다. 콘솔에서만 되던 등록·심사를 주입받은 서비스에서 처리할 수 있습니다.

| 접근 | 하는 일 | 계정 | | --- | --- | --- | | sendgo.kakaoSenders | 카카오 채널 인증·등록·동기화, 브랜드메시지 M/N 신청 | 기업 | | sendgo.noticeTemplates | 알림톡 템플릿 CRUD, 검수 요청·취소, 승인 취소, 휴면 해제 | 기업 | | sendgo.brandTemplates | 브랜드메시지 템플릿 CRUD, 동기화, 가져오기 | 기업 | | sendgo.senderRegistration | 발신번호 등록 신청, 중복 확인, 유형 안내 | 개인·기업 | | sendgo.messageTemplates | 문자 상용구 템플릿 CRUD | 개인·기업 | | sendgo.kakaoImages | 카카오 이미지 업로드 — 템플릿용 URL 발급 | 기업 | | sendgo.rejectedNumbers | 수신거부(080) 번호 조회 | 개인·기업 | | sendgo.webhook | 이벤트 웹훅 구독 — 심사 결과 수신 | 개인·기업 |

sendgo.io 콘솔에 들어올 일이 없습니다. 휴대폰 발신번호는 PASS 대신 신분증 사본을 받아 sendgo 운영자가 대신 심사합니다. 사람이 개입하는 지점은 카카오 채널 인증번호 하나뿐이고, 그것도 여러분 화면에서 입력받으면 됩니다. 심사가 붙는 것들은 비동기라 웹훅으로 결과를 받으세요.

import { Injectable, Logger } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import { SendgoService } from '@sendgo/nestjs';

@Injectable()
export class OnboardingService {
  private readonly logger = new Logger(OnboardingService.name);

  constructor(private readonly sendgo: SendgoService) {}

  /** 1단계 — 카카오가 관리자 휴대폰으로 인증번호를 SMS 발송한다. */
  async requestChannelCode(yellowId: string, phone: string) {
    return this.sendgo.kakaoSenders.requestToken(yellowId, phone);
  }

  /** 2단계 — 사용자가 입력한 인증번호로 발신프로필 생성. */
  async completeChannel(yellowId: string, phone: string, code: string) {
    const created = await this.sendgo.kakaoSenders.create({
      token: code,
      yellowId,
      phoneNumber: phone,
      categoryCode: '001001',
    });

    return created.data.sender.kakaoSenderKey;
  }

  /** 표준 템플릿을 등록하고 검수를 요청한다. */
  async provisionTemplate(kakaoSenderKey: string) {
    const created = await this.sendgo.noticeTemplates.create({
      kakaoSenderKey,
      templateName: '주문 접수 안내',
      templateContent: '#{name}님, 주문 #{orderNo}이 접수되었습니다.',
      templateMessageType: 'BA',
      templateEmphasizeType: 'NONE',
      categoryCode: '001001',
      messagePurpose: 'order_delivery',
      legalBasis: 'transaction',
      benefitOrigin: 'none',
      expiryType: 'none',
      optInReviewConfirmed: true,
      ctaClearConfirmed: true,
      policyConfirmed: true,
    });

    const code = created.data.template.templateCode;
    await this.sendgo.noticeTemplates.requestInspection(code);

    return code;
  }

  /**
   * 승인 여부는 스케줄러로 확인한다. 검수는 30분~1영업일 걸리므로
   * 요청 스레드에서 기다리면 안 된다.
   */
  @Cron(CronExpression.EVERY_30_MINUTES)
  async pollPendingTemplates() {
    for (const code of await this.pendingTemplateCodes()) {
      const synced = await this.sendgo.noticeTemplates.sync(code);
      const status = synced.data.template.inspectionStatus;

      if (status === 'APR') this.logger.log(`템플릿 승인: ${code}`);
      if (status === 'REJ') this.logger.warn(`템플릿 반려: ${code}`);
    }
  }

  private async pendingTemplateCodes(): Promise<string[]> {
    return [];  // 앱의 저장소에서 읽어 온다
  }
}

발신번호 등록과 브랜드메시지 템플릿을 포함한 전체 파라미터는 @sendgo/node README 를 참고하세요.

변경 사항

1.3.0 (2026-09-11)

• 관리 API 노출 — SendgoService 에 kakaoSenders · noticeTemplates · brandTemplates · senderRegistration · messageTemplates 게터를 추가했습니다. 콘솔에서만 되던 채널 등록, 알림톡 템플릿 검수 요청, 발신번호 심사 접수를 주입받은 서비스에서 처리할 수 있습니다.
• @sendgo/node 를 ^1.3.0 으로 올렸습니다.
• 이벤트 웹훅 추가 — 발신번호 승인, 알림톡 검수 결과, 채널 차단, 브랜드메시지 타겟팅 결과를 구독해 받습니다. 서명은 받은 원본 바이트로 검증합니다(SDK 에 검증 헬퍼 포함).
• 카카오 이미지 업로드 추가 — 브랜드메시지 템플릿의 imageUrl 은 카카오가 호스팅하는 URL 이어야 하는데, 그 URL 을 얻는 길이 콘솔에만 있었습니다.
• 수신거부(080) 조회 추가 — 자기 DB 의 수신 상태를 맞출 수 있습니다.

1.2.1 (2026-08-14)

• 레지스트리 목록에 노출되는 패키지 설명에서 친구톡을 브랜드메시지로 교체했습니다. npm/PyPI/Packagist/Maven/NuGet/RubyGems 검색 결과에 그대로 찍히는 문자열이라 종료된 채널을 계속 홍보하고 있었습니다.
• 검색 키워드에 brand-message 를 추가했습니다 (friendtalk 은 유입 검색어라 유지).

1.2.0 (2026-08-14)

• 친구톡 Deprecated 표기 — 친구톡은 카카오 정책에 따라 2025-12-31 종료되었고, 2026-01-01 부터 발송 요청이 브랜드메시지(자유형)로 자동 대체 발송됩니다. 관련 API 에 각 언어의 표준 deprecation 표기를 달았습니다.
• 자유 본문 타입(FT/FI/FW)의 개별 발송 경로는 아직 친구톡 API 뿐이라는 점을 문서에 명시했습니다 — 브랜드메시지 API 는 그 조합에 NOT_A_BRAND_MESSAGE 를 반환합니다.
• 브랜드메시지 전환 안내와 메시지 타입 1:1 대응표를 README 에 추가했습니다.

1.1.0 (2026-08-11)

• SendgoService.shortUrl 게터 추가

라이선스

MIT License © 2026 Sendgo

키워드: 카카오 알림톡 NestJS, 카카오 친구톡 NestJS, SMS 발송 NestJS, 알림톡 NestJS 모듈, NestJS 카카오 API 연동, Sendgo NestJS SDK

계정 API (1.6.0)

코어 1.6.0의 계정·조직·API 키·허용 IP 관리 12개 API를 사용할 수 있습니다. 발송용 키 없이 에이전트 토큰만으로 구성할 수 있습니다.

발송용 accessKey/secretKey가 없는 단계에서 사용하는 별도 계정 클라이언트입니다. 콘솔에서 발급받은 에이전트 토큰(SENDGO_AGENT_TOKEN)으로 /api/v2/account를 호출합니다. 계정 조회에는 account:read, 키·허용 IP 변경에는 keys:write 권한이 필요합니다. 토큰 만료나 권한 부족(401/403)은 그대로 예외로 반환하며 자동 갱신·재시도하지 않습니다.

조직 선택은 서버에 저장되는 사용자 계정의 현재 조직을 바꿉니다. 같은 사용자로 여러 조직의 설정을 동시에 변경하지 마세요. 개인 계정으로 돌아가려면 조직 ID에 null(Python None, Ruby nil, Go nil) 또는 personal을 전달합니다. 키 발급 응답의 data.apiKey.secretKey는 한 번만 반환되므로 서버의 비밀 저장소에 보관하세요. 허용 IP가 하나라도 등록되면 목록 밖의 IP는 차단됩니다. 에이전트 토큰과 키는 브라우저·모바일 앱에 포함하거나 응답·로그에 출력하지 않습니다.

import { SendgoModule, AccountClient } from '@sendgo/nestjs';
// 모듈의 imports에 등록하면 AccountClient를 주입할 수 있습니다.
SendgoModule.forAccount({ agentToken: process.env.SENDGO_AGENT_TOKEN! });

템플릿 폴더 (1.6.0)

기업 계정의 발송용 API 키와 apiVersion=v2 설정으로 사용하는 서버 전용 API입니다. 폴더는 알림톡·브랜드메시지가 공유하며, 목록의 templateType은 notice 또는 brand입니다. 목록은 data.folders 트리와 total, uncategorised 개수를 반환합니다. templateCount는 하위 폴더를 제외한 해당 폴더의 템플릿 수입니다.

• 생성: name, 선택 parentUuid. 최대 5단계이며 같은 부모 아래 이름 중복은 409입니다.
• 이동: 동일 발신프로필의 templateCodes 1~100개. folderUuid는 필수이며 null이면 미분류로 이동합니다.
• 템플릿 목록: folderUuid=none은 미분류, UUID는 해당 폴더, 생략은 전체입니다.
• 템플릿 등록: 선택 필드 folderUuid로 폴더를 지정합니다. 기존 템플릿 수정 API 대신 폴더 이동 API를 사용하세요.

승인되지 않은 키의 403 ACCESS_KEY_NOT_APPROVED는 토큰 재발급·재시도 없이 반환합니다. 계정 API의 autoApprove는 서버 설정의 실제 승인 정책을 나타냅니다.

// 주입받은 SendgoService에 폴더 서비스가 공개됩니다.
await this.sendgo.templateFolders.list({ templateType: 'notice' });

코어 1.6.0 이상이 필요합니다. 전체 메서드는 코어 문서를 참고하세요.

1.6 이메일 API와 브랜드 타기팅

이메일은 서버 전용이며 클라이언트 설정에서 API 버전을 v2로 지정합니다. 브랜드 타기팅은 M(친구+비친구), N(비친구), I(친구교집합), O(친구만), F(동보)를 지원합니다. O는 SDK에서 바꾸지 않고 서버로 전달합니다.

이메일 발송·견적·조회·취소, 발신자·도메인 인증, 자격증명, 수신함·원본 EML, 템플릿·주소록·연락처·발신자 프로필·캠페인 API를 지원합니다. 일반 API는 기존 앱 Bearer 인증을 사용합니다. EmailService의 withCredentials / with_credentials / WithCredentials / Go NewEmailWithCredentials는 별도로 발급된 이메일 credential ID/password를 사용하며 /api/v2/email-service로 호출합니다. 이 인증은 auth, 발송·견적·조회·취소와 도메인 API에만 사용할 수 있습니다. 내부 email-gateway, 공개 서명 수신거부 URL은 SDK 관리 API가 아닙니다.

단건 to는 이메일 주소 하나입니다. send에는 idempotency_key를 반드시 지정하고 같은 발송의 재시도에는 같은 키를 재사용하세요. 캠페인 발송에는 견적 응답의 quote_hash와 idempotency_key가 필요합니다. SDK가 키를 임의 생성하거나 네트워크 오류·429·5xx를 자동 재시도하지 않습니다. Bearer 401만 최대 한 번 갱신하며, 이메일 권한 거부 403 및 Basic 인증 실패는 그대로 반환합니다. 마케팅 발송에는 sender_name, sender_address, sender_contact도 필요합니다. 첨부는 attachments: [{name, type, content}]이며 content는 base64입니다.

응답은 서버 JSON 객체 또는 배열을 그대로 반환하며 204는 null/nil/None입니다. 원본 EML은 바이트(PHP/Ruby는 바이트 문자열)로 반환합니다. Java/Go/.NET/Dart는 여러 응답 형태를 담는 Object/any/object/dynamic을 사용합니다(.NET JSON은 JsonElement). 모든 관리 요청 본문은 서버 필드명(snake_case)을 그대로 사용합니다.

접근 방법: 주입한 SendgoService.email. 코어 최소 버전은 1.6.0입니다.