信服务号通知台

PUSH API · V1

用一个 HTTP 请求，
把服务进展送到微信。

为你的程序创建 SendKey，通过本平台的 API 发送、查询和管理服务通知。消息由平台配置的微信服务号模板投递给你绑定的接收账号。

当前 API 地址正在读取…

请只发送接收者合理预期中的真实服务通知。模板消息需符合服务号权限、模板规则和微信运营规范；接口受理不代表微信已投递或用户已阅读。

01 · 快速开始

准备 SendKey

  1. 登录控制台并完成邮箱验证，在概览页复制首次显示的 SendKey；如果没有密钥，可在控制台重新生成。
  2. 把密钥放进部署环境的 PUSH_SEND_KEY，不要写入浏览器代码、仓库、日志或 URL。
  3. 绑定并关注微信服务号。平台会把一条通知发送到该账户下所有有效接收账号。
最小请求

02 · POST

发送通知

POST/api/send

请求头使用 Authorization: Bearer <SendKey> 和 Content-Type: application/json。建议每个业务事件生成一个稳定幂等键，并在网络超时后用相同的键和相同内容重试。

title、desp 和 fields 是自定义请求内容。微信卡片的正文仍必须符合管理员配置的已获批服务号模板；管理员需为模板字段设置映射，缺少必需映射值时请求会报错。服务条款禁止把接口用于营销、骚扰或与真实服务无关的推送。

请求头

请求字段

字段类型规则
titlestring，必填非空，最多 200 个字符；不能换行或含控制字符。
despstring，可选最多 10,000 个字符。可用于自定义消息正文及管理员配置的模板字段映射。
fieldsobject，可选最多 20 个键；键为字母开头的字母/数字/下划线，值必须为字符串且最多 2,000 个字符。
urlstring，可选不含用户名/密码的 HTTPS 业务详情链接，最多 2,048 个字符。它显示在本平台的消息详情页中；微信卡片默认打开本站详情页。
X-Idempotency-Key请求头，可选1–128 个 ASCII 字母、数字、下划线、点、冒号或连字符。相同账户、键和内容返回已有结果；同键不同内容为冲突。
成功响应 · 新消息为 HTTP 202

用相同幂等键和相同请求重试时，返回 HTTP 200、existing: true 和原有 messageId。HTTP 202 表示进入队列；发送状态可稍后查询。避免在重试时生成新幂等键，否则可能重复通知。幂等记录随消息保留 30 天；超出窗口后重用旧键可能创建新通知。已撤销或过期的详情链接不会恢复，响应中的 detailUrl 为 null。

03 · GET

查询消息状态

SendKey 可通过 Bearer 读取本账户消息和消息详情。所有结果按账户隔离，不提供访问其他账户或管理接口的权限。

GET/api/messages?limit=20&before=<cursor>

limit 默认为 20，取值 1～100；使用上一页返回的 nextCursor 作为下一页的 before。没有更多记录时 nextCursor 为 null。

分页结果
GET/api/messages/<messageId>

详情端点只返回当前 SendKey 对应账户的消息；不属于该账户或不存在时返回 404。

按消息 ID 查询

常见状态包括 queued、sending、sent、delivered、failed、partial 和 uncertain。微信回执可能缺失；sent 或 delivered 不表示用户阅读。

04 · GET

查询额度

GET/api/quota

每日统计使用 Asia/Shanghai 时区。个人和全站每日额度按收件人投递数计数：发给 3 个接收账号会计 3 次，即使投递失败或取消也计入当日占用。每用户每分钟上限按消息请求数计算。

响应示例

05 · 详情链接

获取或撤销消息详情链接

新消息入队时平台生成随机详情 token。微信卡片默认打开本站详情页，持有链接即可读取这条消息，所以应像密码一样保护链接。详情页不公开索引；链接有效 30 天。

GET/api/messages/<messageId>/detail-link

使用 SendKey Bearer 读取已创建链接，响应含 detailUrl 和 expiresAt。链接不存在、过期或已撤销时返回 404 DETAIL_LINK_UNAVAILABLE；GET 不会创建或恢复链接。

DELETE/api/messages/<messageId>/detail-link

撤销链接仅允许控制台登录会话执行，并要求 CSRF token。SendKey 不可撤销详情链接，避免泄漏的密钥被用于破坏性操作。用户可在控制台对应消息记录中撤销链接。

06 · 限制与错误

处理错误响应

错误响应格式为 {"code":"…","message":"…"}。非 2xx 响应应记录请求上下文和消息，不要记录 SendKey。

HTTP常见错误码建议处理
400VALIDATION、MISSING_FIELD、NO_RECIPIENT、INVALID_CURSOR修正请求或先绑定接收账号；无效游标时刷新列表。
401INVALID_KEY检查密钥是否完整、已轮换或已撤销。
403ACCOUNT_DISABLED联系平台运营者处理账户状态。
404NOT_FOUND、DETAIL_LINK_UNAVAILABLE确认消息属于当前账户；详情链接可能已过期或撤销。
409IDEMPOTENCY_CONFLICT同一幂等键已用于不同内容；为新的业务事件生成新键。
429RATE_LIMIT、LIMIT_RATE、LIMIT_DAILY、LIMIT_GLOBAL_DAILY退避后重试；每日额度于上海时区午夜重置。
502WECHAT_*微信接口或网络错误。先查询状态；结果不确定时不要换用新幂等键重发。
503WECHAT_NOT_CONFIGURED、TEMPLATE_NOT_CONFIGURED、SENDING_PAUSED服务号凭证/模板未配置或管理员暂时暂停发送。

每个账户、接收者和服务号有独立额度。不要通过轮换账户或 SendKey 绕过限制，也不要把服务号模板消息用于广告或无关推送。

07 · 示例

可运行客户端

示例只依赖 Node.js 22 自带的 fetch 或 Python 标准库，不需要 SDK 或第三方依赖。先设置 PUSH_BASE_URL 和 PUSH_SEND_KEY 环境变量；执行发送命令还须提供每个业务事件唯一且稳定的 PUSH_IDEMPOTENCY_KEY。标题、正文、模板自定义字段和业务 URL 可分别通过 PUSH_TITLE、PUSH_DESCRIPTION、JSON 对象 PUSH_FIELDS_JSON、PUSH_BUSINESS_URL 设置。

Node.js 客户端发送、分页读取、状态、额度与详情链接examples/node-client.mjs Python 标准库客户端同一接口与超时幂等重试示例examples/python-client.py
环境变量（不要提交密钥）

下载后可运行 node node-client.mjs quota、node node-client.mjs list [before]、node node-client.mjs status <messageId> 或 node node-client.mjs send。Python 对应命令为 python python-client.py …。发送脚本最多在同一进程中用原始幂等键和请求体重试一次；若最终仍超时，请保留这些值供后续重试，不要换键。