샌드고 SDK 및 개발자 가이드

샌드고는 카카오 알림톡·브랜드메시지와 SMS/LMS/MMS 발송을 위한 언어·프레임워크용 공식 SDK 19종을 제공합니다. OpenAPI 명세는 별도로 제공하며 SDK 개수에 포함하지 않습니다. 어떤 언어를 쓰더라도 동일한 개념(액세스 키 발급 → 발신프로필 등록 → 발송)으로 연동할 수 있습니다.

3분 만에 시작하기

1. 키 발급 — 샌드고에 로그인해 API/SDK → API 연동 메뉴에서 액세스 키와 시크릿 키를 발급합니다.
2. 발신 정보 등록 — 알림톡·브랜드메시지는 카카오 채널 메뉴에서 발신프로필을, 문자는 발신번호 메뉴에서 발신번호를 등록합니다.
3. SDK 설치 — 사용하는 언어의 가이드를 열어 설치 명령 한 줄을 실행합니다.
4. 발송 — 템플릿 코드와 수신자 목록을 넘기면 끝입니다.

SDK 설계 방식

모든 SDK는 코어 + 프레임워크 확장 구조를 따릅니다.

코어	프레임워크 확장
sendgo/php	sendgo/laravel, sendgo/symfony, sendgo/wordpress
@sendgo/node	@sendgo/react, @sendgo/vue, @sendgo/nestjs
sendgo-python	sendgo-django, sendgo-fastapi
io.sendgo:sendgo-java	io.sendgo:sendgo-spring
sendgo (Ruby)	sendgo-rails
Sendgo.SDK	Sendgo.AspNetCore

코어는 프레임워크에 의존하지 않는 순수 클라이언트이고, 확장 패키지는 해당 프레임워크의 설정·의존성 주입·로깅 규칙에 맞춰 코어를 감쌉니다. 프레임워크 확장을 설치하면 코어는 의존성으로 함께 설치되므로 따로 설치할 필요가 없습니다.

공통 개념

• 인증 — 액세스 키와 시크릿 키로 토큰을 발급받고, 이후 요청은 Bearer 토큰으로 인증합니다. 모든 SDK가 토큰 발급·갱신을 자동으로 처리합니다.
• API 버전 — v2를 권장합니다. v2는 서명 기반 토큰(sgv2.{payload}.{signature})을 사용하며 유효기간은 24시간입니다.
• 발송 채널 — 알림톡(alimtalk), 브랜드메시지(brandMessage), 문자(sms / lms / mms), 친구톡(friendtalk, 2025-12-31 종료 — 요청은 브랜드메시지(자유형)로 자동 대체 발송됩니다).
• 브랜드메시지 — 친구톡의 후속 채널로, 채널 친구가 아닌 수신자에게도 보낼 수 있고 수신 동의한 전체 채널 친구에게 동보 발송할 수 있습니다. v2 전용.
• 짧은 URL — 메시지의 링크를 줄이고 클릭 반응(일별 추이·디바이스·유입경로·국가)을 집계합니다. v2 전용.
• 알림톡 실패 시 문자 대체 — replaceSms 옵션으로 알림톡 실패 시 문자로 자동 대체 발송할 수 있습니다.
• 예약 발송 — scheduleType: SCHEDULED 와 at 값으로 예약할 수 있습니다.
• 오류 처리 — 모든 SDK가 HTTP 상태 코드와 샌드고 오류 코드를 담은 예외를 던집니다.

서버 전용 SDK 주의사항

@sendgo/react, @sendgo/vue, sendgo_flutter는 서버사이드 전용입니다. 액세스 키와 시크릿 키는 브라우저나 모바일 앱 번들에 포함되면 안 되므로, 반드시 Next.js Server Action / Route Handler, Nuxt Server Route, Dart 백엔드 등 서버 환경에서만 사용하세요.

AI 코딩 에이전트용 리소스

바이브 코딩이나 AI 에이전트로 연동할 때 아래 리소스를 사용하면 정확한 코드를 얻을 수 있습니다.

• /llms.txt — 전체 문서 지도 (llmstxt.org 규격)
• /llms-full.txt — 모든 SDK 가이드 전문을 하나로 합친 파일
• /{언어}/sdk/{패키지}.md — 각 가이드의 마크다운 원문
• /openapi.yaml — OpenAPI 3.0.3 스펙