ASP.NET Core SDK 가이드

ASP.NET Core에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 DI 확장 패키지

Sendgo.AspNetCore는 Sendgo.SDK 코어를 확장한 ASP.NET Core 전용 패키지입니다. IServiceCollection 확장 메서드로 SendgoClient를 싱글턴으로 등록하고, appsettings.json 또는 코드로 손쉽게 설정 바인딩을 제공합니다.

---

설치

dotnet add package Sendgo.AspNetCore

Sendgo.SDK 코어가 자동으로 함께 설치됩니다.

---

빠른 시작

1단계 — 설정 등록 (Program.cs)

var builder = WebApplication.CreateBuilder(args);

// appsettings.json의 "Sendgo" 섹션에서 바인딩
builder.Services.AddSendgo(builder.Configuration.GetSection("Sendgo"));

builder.Services.AddControllers();
var app = builder.Build();

2단계 — appsettings.json

{
  "Sendgo": {
    "AccessKey": "your_access_key",
    "SecretKey": "your_secret_key",
    "KakaoSenderKey": "your_kakao_key",
    "SmsSenderKey": "your_sms_key",
    "ApiVersion": "v2"
  }
}

BaseUrl을 지정하지 않으면 기본값 https://sendgo.io가 사용됩니다.

3단계 — 컨트롤러에서 주입받아 발송

using Microsoft.AspNetCore.Mvc;
using Sendgo;
using Sendgo.Models;

[ApiController]
[Route("orders")]
public class OrderController : ControllerBase
{
    private readonly SendgoClient _sendgo;

    public OrderController(SendgoClient sendgo) => _sendgo = sendgo;

    [HttpPost("{orderNo}/confirm")]
    public async Task<IActionResult> Confirm(string orderNo)
    {
        await _sendgo.SendAlimtalkAsync(new AlimtalkRequest
        {
            TemplateCode = "ORDER_CONFIRM_001",
            Contacts     = [new Contact { PhoneNumber = "01012345678", Var1 = orderNo }],
        });

        return Ok(new { success = true });
    }
}

---

설정 방법

appsettings.json 바인딩

호출 측에서 이미 스코프가 지정된 섹션을 전달합니다.

builder.Services.AddSendgo(builder.Configuration.GetSection("Sendgo"));

환경별 오버라이드는 appsettings.Development.json, 환경변수, User Secrets 등 ASP.NET Core의 표준 구성 소스를 그대로 활용할 수 있습니다.

# User Secrets로 민감 정보 관리 (개발 환경 권장)
dotnet user-secrets set "Sendgo:AccessKey" "your_access_key"
dotnet user-secrets set "Sendgo:SecretKey" "your_secret_key"

람다(코드)로 설정

builder.Services.AddSendgo(options =>
{
    options.AccessKey      = builder.Configuration["SENDGO_ACCESS_KEY"]!;
    options.SecretKey      = builder.Configuration["SENDGO_SECRET_KEY"]!;
    options.KakaoSenderKey = builder.Configuration["SENDGO_KAKAO_KEY"];
    options.SmsSenderKey   = builder.Configuration["SENDGO_SMS_KEY"];
    options.ApiVersion     = "v2";
});

두 방식 모두 SendgoClient를 싱글턴으로 등록하므로, 생성자에서 SendgoClient를 타입힌트로 주입받아 사용할 수 있습니다.

---

상세 사용법

알림톡

// 다건 발송
await _sendgo.SendAlimtalkAsync(new AlimtalkRequest
{
    TemplateCode = "ORDER_CONFIRM_001",
    Contacts =
    [
        new Contact { PhoneNumber = "01011111111", Name = "홍길동", Var1 = "ORD-001", Var2 = "29,000원" },
        new Contact { PhoneNumber = "01022222222", Name = "김철수", Var1 = "ORD-002", Var2 = "15,000원" },
    ],
});

친구톡

⚠️ 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 _sendgo.SendFriendtalkAsync(new
{
    content  = "안녕하세요! 7월 한정 특가 이벤트를 확인해보세요.",
    contacts = new[] { new { contact = "01012345678" } },
});

SMS / LMS / MMS

// SMS (90자 이하)
await _sendgo.SendSmsAsync(new SmsRequest
{
    Content  = "[Sendgo] 인증번호: 123456 (5분 이내 입력)",
    Contacts = [new Contact { PhoneNumber = "01012345678" }],
});

// LMS (장문, 2,000자 이하)
await _sendgo.SendLmsAsync(new SmsRequest
{
    Subject  = "[중요] 서비스 점검 안내",
    Content  = "안녕하세요. 서비스 점검이 예정되어 있습니다.",
    Contacts = [new Contact { PhoneNumber = "01012345678" }],
});

// MMS (이미지 포함)
await _sendgo.SendMmsAsync(new SmsRequest
{
    Subject  = "[이벤트] 7월 특가",
    Content  = "이번 달 특가 상품을 확인하세요!",
    Contacts = [new Contact { PhoneNumber = "01011111111" }],
});

---

서비스 클래스 패턴

SendgoClient가 싱글턴으로 등록되어 있으므로, 도메인 서비스에 그대로 주입할 수 있습니다.

// Services/NotificationService.cs
using Sendgo;
using Sendgo.Models;

public class NotificationService
{
    private readonly SendgoClient _sendgo;
    private readonly ILogger<NotificationService> _logger;

    public NotificationService(SendgoClient sendgo, ILogger<NotificationService> logger)
    {
        _sendgo = sendgo;
        _logger = logger;
    }

    public Task SendOrderConfirmAsync(string phone, string orderNo, int amount) =>
        _sendgo.SendAlimtalkAsync(new AlimtalkRequest
        {
            TemplateCode = "ORDER_CONFIRM_001",
            Contacts     = [new Contact { PhoneNumber = phone, Var1 = orderNo, Var2 = $"{amount:N0}원" }],
        });
}

// Program.cs
builder.Services.AddScoped<NotificationService>();

---

예외 처리

using Sendgo.Exceptions;

try
{
    await _sendgo.SendAlimtalkAsync(request);
}
catch (SendgoException e)
{
    _logger.LogError("Sendgo 발송 실패 (status={Status}, code={Code}, endpoint={Endpoint})",
        e.StatusCode, e.ErrorCode, e.Endpoint);
    throw;
}

---

설정 옵션

SendgoOptions (섹션 키: Sendgo):

키	기본값	설명
AccessKey	—	Sendgo 액세스 키 (필수)
SecretKey	—	Sendgo 시크릿 키 (필수)
KakaoSenderKey	null	카카오 발신프로필 키
SmsSenderKey	null	SMS 발신자 키
ApiVersion	v1	API 버전 (v1 | v2)
BaseUrl	https://sendgo.io	API 기본 URL

---

자주 묻는 질문 (FAQ)

Q. Sendgo.SDK와의 차이는 무엇인가요? A. Sendgo.SDK는 프레임워크 독립적인 순수 .NET 코어 패키지입니다. Sendgo.AspNetCore는 이를 확장해 IServiceCollection 확장 메서드, appsettings.json 설정 바인딩 등 ASP.NET Core 통합을 추가합니다.

Q. SendgoClient는 어떤 수명(lifetime)으로 등록되나요? A. 싱글턴으로 등록됩니다. SendgoClient는 내부적으로 HttpClient와 토큰을 재사용하도록 설계되어 있어 싱글턴이 적합합니다.

Q. DI를 쓰지 않고 직접 생성할 수도 있나요? A. 네, new SendgoClient(new SendgoOptions { ... })로 직접 생성할 수 있습니다. 이 패키지는 그 등록을 자동화할 뿐입니다.

Q. 테스트 시 Sendgo를 Mock 처리하려면? A. SendgoClient는 sealed이므로, 도메인 서비스가 의존하는 인터페이스를 별도로 두거나 통합 테스트에서 실제 클라이언트를 사용하는 것을 권장합니다.

---

브랜드메시지 · 짧은 URL

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

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

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

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

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

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

주입받은 SendgoClient 에 관리 API 가 그대로 붙어 있습니다. 콘솔에서만 되던 등록·심사를 컨트롤러나 IHostedService 에서 처리할 수 있습니다.

sendgo.io 콘솔에 들어올 일이 없습니다. 고객의 채널·발신번호·템플릿을 여러분 화면만으로 끝까지 처리할 수 있습니다. 휴대폰 발신번호는 콘솔의 PASS 본인인증 대신 신분증 사본(identityDocument)을 받아 sendgo 운영자가 대신 심사합니다.

사람이 개입하는 지점은 카카오 채널 인증번호 하나뿐이고, 그마저도 여러분 화면에서 입력받으면 됩니다 — 카카오가 관리자 휴대폰으로 직접 보내는 확인이라 없앨 수 없습니다.

심사가 붙는 것들은 비동기입니다. 등록 호출이 성공했다는 건 "접수됐다"는 뜻이지 "쓸 수 있다"는 뜻이 아닙니다 — 웹훅을 구독해 결과를 받으세요.

[ApiController]
[Route("onboarding")]
public class OnboardingController(SendgoClient sendgo) : ControllerBase
{
    /// 1단계 — 카카오가 관리자 휴대폰으로 인증번호를 SMS 발송한다.
    [HttpPost("channel/code")]
    public Task<Dictionary<string, object?>> RequestCode(string yellowId, string phone) =>
        sendgo.RequestKakaoChannelCodeAsync(yellowId, phone);

    /// 2단계 — 사용자가 입력한 인증번호로 발신프로필 생성.
    [HttpPost("channel")]
    public Task<Dictionary<string, object?>> CreateChannel(KakaoSenderCreateRequest request) =>
        sendgo.CreateKakaoSenderAsync(request);

    /// 발신번호 등록 신청 — 서류를 그대로 넘긴다.
    [HttpPost("senders")]
    public async Task<Dictionary<string, object?>> RegisterSender(
        [FromForm] string alias, [FromForm] string phone, IFormFile csu)
    {
        using var stream = new MemoryStream();
        await csu.CopyToAsync(stream);

        return await sendgo.RegisterSenderAsync(
            new SenderRegistrationRequest
            {
                SenderAlias = alias,
                SenderNumberType = "team_main",
                PhoneE164 = phone,
            },
            [new MultipartFile
            {
                FieldName = "csuCertificate",
                FileName = csu.FileName,
                ContentType = csu.ContentType,
                Content = stream.ToArray(),
            }]);
    }
}

SendgoClient 에는 이것들도 함께 붙어 있습니다.

메서드	하는 일
UploadKakaoImageAsync · UploadKakaoImagesAsync	카카오 이미지 업로드 — 브랜드메시지 템플릿용 URL 발급
GetRejectedNumbersAsync	수신거부(080) 번호 조회
SubscribeWebhookAsync · GetWebhookAsync · TestWebhookAsync	이벤트 웹훅 구독
SendgoClient.VerifyWebhookSignature	수신한 웹훅 서명 검증 (정적 메서드)

웹훅을 구독하면 폴링이 필요 없습니다.

app.MapPost("/hooks/sendgo", async (HttpRequest request) =>
{
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var raw = buffer.ToArray();

    // 파싱한 객체가 아니라 받은 바이트 그대로 검증한다.
    if (!SendgoClient.VerifyWebhookSignature(raw, request.Headers["X-Sendgo-Signature"], secret))
        return Results.Unauthorized();

    await queue.EnqueueAsync(raw);   // 처리는 큐로

    return Results.NoContent();
});

검수 결과는 비동기입니다. BackgroundService 로 폴링하세요 — 요청 핸들러 안에서 기다리면 안 됩니다.

public class TemplateInspectionPoller(SendgoClient sendgo, ILogger<TemplateInspectionPoller> log)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            foreach (var code in await PendingTemplateCodesAsync(ct))
            {
                var synced = await sendgo.SyncNoticeTemplateAsync(code, ct);
                // data.template.inspectionStatus 가 APR 이 되면 발송 가능
                log.LogInformation("템플릿 {Code} 검수 상태 확인", code);
            }

            await Task.Delay(TimeSpan.FromMinutes(30), ct);
        }
    }

    private Task<IReadOnlyList<string>> PendingTemplateCodesAsync(CancellationToken ct) =>
        Task.FromResult<IReadOnlyList<string>>([]);  // 앱의 저장소에서 읽어 온다
}

전체 파라미터는 Sendgo.SDK README 를 참고하세요.

---

변경 사항

1.3.0 (2026-09-11)

• 관리 API 노출 — 코어 1.3.0 의 채널 등록, 알림톡 템플릿 검수 요청, 브랜드메시지 템플릿, 발신번호 심사 접수, 문자 상용구 템플릿을 주입받은 SendgoClient 에서 그대로 쓸 수 있습니다. IFormFile 을 MultipartFile 로 옮겨 서류를 그대로 올릴 수 있습니다.
• Sendgo.SDK 의존성을 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)

• Sendgo.SDK 의존을 1.1.0 으로 올림 — 1.0.1 로 고정돼 있어 짧은 URL 메서드가 노출되지 않았다.

라이선스

MIT License © 2026 Sendgo

---

패키지 정보

• 패키지: Sendgo.AspNetCore (NuGet)
• 저장소: send-go/aspnetcore
• 레지스트리: https://www.nuget.org/packages/Sendgo.AspNetCore
• 라이선스: MIT

API 키 발급 방법

샌드고에 로그인한 뒤 연동하기 → 연동 정보 메뉴에서 액세스 키와 시크릿 키를 발급받고, 같은 화면에서 호출을 허용할 IP 를 등록합니다 — 등록되지 않은 주소에서 온 요청은 거부됩니다. 알림톡·브랜드메시지를 사용하려면 발신프로필 관리 메뉴에서 발신프로필을 등록해 kakao_sender_key를 발급받고, 문자를 사용하려면 발신번호 관리 메뉴에서 발신번호를 등록해야 합니다.