샌드고 SDK 및 개발자 가이드

Sendgo 为 Kakao 通知消息（알림톡）、品牌消息（브랜드메시지）以及 SMS/LMS/MMS 提供 19 个官方语言与框架 SDK 软件包。OpenAPI 规范单独提供，不计入 SDK 数量。 无论使用哪种语言，对接流程都相同：签发密钥 → 登记发送者 → 发送。

三分钟上手

1. 签发密钥 — 登录后打开 API/SDK → API 对接，创建访问密钥（access key）与私密密钥（secret key）。
2. 登记发送者 — 通知消息／品牌消息需在 Kakao 渠道 登记发送者资料；短信需在 发送号码 登记主叫号码。
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

核心是不依赖任何框架的纯客户端；扩展包在其之上适配各框架的配置、依赖注入与日志约定。 安装扩展包时会自动带入核心，因此无需分别安装。

各 SDK 通用的概念

• 认证 — 使用访问密钥与私密密钥换取令牌，随后以 Bearer 令牌调用。令牌的签发与续期由各 SDK 自动处理。
• API 版本 — 建议使用 v2。v2 采用签名式令牌（sgv2.{payload}.{signature}），有效期 24 小时。
• 发送渠道 — 通知消息（alimtalk）、品牌消息（brandMessage）、短信（sms）、好友消息（friendtalk，已于 2025-12-31 停止服务 —— 请求会自动以品牌消息（自由形式）发出）。
• 品牌消息 — 好友消息的后继渠道，可触达非频道好友的接收者，也可向已同意接收的全部频道好友群发。
• 短链接 — 缩短消息中的链接并统计点击反应（按日趋势、设备、来源、国家）。仅 v2 支持。
• 短信回退 — 使用 replaceSms，Kakao 消息发送失败时自动回退为短信。
• 预约发送 — 通过 scheduleType: SCHEDULED 与 at 指定时间。
• 错误处理 — 所有 SDK 都会抛出携带 HTTP 状态码与 Sendgo 错误代码的异常。完整代码列表见 REST API 文档。

仅限服务端使用的 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 — 各指南的 Markdown 原文
• /openapi.yaml — REST API 的 OpenAPI 3.0.3 规范