ADAPTER DOCUMENTATION

短信适配器接入指南

选择你正在使用的短信工具,复制配置并完成一次真实短信验收。

01 / 开始之前

先确认网关可以访问

sms-link 的统一接入网关是 https://api.sms.cooldev.cn。Webhook 不使用管理后台 Token, 按下方对应适配器的地址配置即可。

网关健康检查地址
https://api.sms.cooldev.cn/health
接入成功的统一判据

Webhook 返回 HTTP 202,响应中的 msg 为 accepted,随后可在管理后台短信列表看到记录。

02 / 已实现

双卡助手

已支持入站

双卡助手是第三方 Android 应用。使用它的“网络转发”,以 POST JSON 将收到的短信交给 sms-link。

双卡助手 Webhook 地址
https://api.sms.cooldev.cn/hook/sms/smshelper
  1. 新增网络转发在双卡助手中进入网络转发配置,新增一条短信转发规则。
  2. 选择 POST 方式网络地址填写上方 Webhook,Body 使用 JSON。
  3. 粘贴请求模板保留双花括号变量,App 会在转发时替换为真实短信数据。
  4. 保存并发送测试短信让手机实际收到一条短信,再检查请求结果和管理后台。
双卡助手 POST JSON Body
{
  "title": "{{title}}",
  "address": "{{address}}",
  "body": "{{body}}",
  "nickname": "{{nickname}}",
  "card_name": "{{card_name}}",
  "msg_time": "{{msg_time}}",
  "timestamp": "{{timestamp}}",
  "udid": "{{udid}}",
  "cid": "{{cid}}"
}

最小关键字段是 address、body、timestamp 和 udid;其余推荐字段用于联系人、卡槽和设备排障。

暂时不要直接开启 smshelper 的 SMS_ADAPTER_SECRETS

双卡助手原生 sign/full_sign 使用 MD5 规则,与网关当前 HMAC-SHA256 校验不兼容。原生签名字段目前只会随消息留存。

03 / 已实现

SmsForwarder

已支持入站

SmsForwarder 是第三方开源项目。创建一条短信转发规则,以 POST JSON 调用 sms-link。以下模板适用于 SmsForwarder 3.3.1 及以上英文变量标签。

SmsForwarder Webhook 地址
https://api.sms.cooldev.cn/hook/sms/smsforwarder
  1. 新增短信转发规则转发类型选择 Webhook,触发来源选择短信。
  2. 填写请求信息使用 POST,Content-Type 选择 application/json,并填写上方地址。
  3. 粘贴自定义模板使用官方英文变量标签,避免手机语言切换导致旧标签不再替换。
  4. 执行测试让设备收到短信,确认 HTTP 202,再到管理后台查看 smsforwarder 记录。
SmsForwarder POST JSON Body
{
  "from": "{{FROM}}",
  "sms": "{{SMS}}",
  "receive_time": "{{RECEIVE_TIME}}",
  "device_name": "{{DEVICE_NAME}}",
  "card_slot": "{{CARD_SLOT}}",
  "card_subid": "{{CARD_SUBID}}"
}
当前只支持入站

SmsForwarder 云上直连出站已经下线。管理侧显式指定它发送短信时会返回 smsforwarder_outbound_disabled。

04 / 即将支持

Air700E / 724

接入中

接入中,敬请期待

当前仓库只有 AT 短信解析和 sidecar HTTP 桥接框架,尚未完成真实硬件验证,因此暂不提供正式配置教程。

05 / 排障

常见问题

域名或 /health 无法访问

先在手机浏览器打开网关健康检查地址。无法访问时检查 DNS、HTTPS 证书、Coolify 域名绑定和反向代理。

400 empty_payload

请求没有携带查询参数或 Body。确认转发规则已填写 JSON Body,并实际替换了模板变量。

400 invalid_json

Body 不是合法 JSON。检查双引号、逗号和换行,建议重新复制本页模板。

401 missing_signature

网关为该适配器启用了 SMS_ADAPTER_SECRETS,但请求没有携带兼容的 HMAC-SHA256 签名。

401 invalid_signature

请求签名与网关配置不一致。双卡助手原生 MD5 签名不能直接用于这里的 HMAC-SHA256 校验。

返回成功但后台没有数据

确认响应为 HTTP 202 且 msg 为 accepted,再登录管理后台,清空搜索条件并选择对应适配器。

SmsForwarder 主动发送被拒绝

当前只保留 SmsForwarder 入站 webhook;显式使用它出站会返回 smsforwarder_outbound_disabled。