提醒推送

定位：用户触发后的服务通知。预约确认、开场提醒、退款结果、危机跟进能发； 促销、群发、与用户本次服务无关的内容不能发（微信会限流甚至封接口）。

通道与降级

顺序由设置项 msg_channel_pref 决定（默认 template → subscribe）。全部不可用时消息记 skipped 并把每一档的跳过原因拼全 —— 这不是错误，是"触达不到"，站点应当把它当作降级到短信/站内的信号。

发送 POST /api/v1/message/send

{ "event_key": "booking_remind",
  "openid": "oXXXX…",                    // 或 "unionid": "uXXXX…"
  "params": { "first": "您有一场咨询即将开始",
              "keyword1": "10月18日 14:00", "keyword2": "朱老师",
              "keyword3": "面询 · 60 分钟", "remark": "如需改期请提前 24 小时" },
  "url": "https://vip.onzx.cn/me/appt/3391",
  "miniprogram_appid": "",               // 填了则以小程序卡片形式跳转
  "page": "",
  "send_now": "0"                        // 1 = 同步发送并立即返回结果
}

{ "ok": true, "data": { "job_id": 812, "channel": "template", "status": "queued", "mode": "queued" } }

查结果 POST /api/v1/message/status

{ "job_ids": [812, 813] }
→ { "jobs": [ { "id":812, "status":"sent", "wechat_msgid":"…" },
              { "id":813, "status":"skipped", "skip_reason":"template：用户未关注该服务号" } ] }

订阅额度怎么攒

方式 1：中台引导页（省域名名额，推荐）

POST https://wx.onzx.cn/api/v1/message/grant-link
{ "event_key": "booking_remind", "return": "/me?sub=1" }
→ { "url": "wx.onzx.cn/subscribe/3f1c…", "template_ids": ["…"] }

# 站点在预约成功页 / 支付成功页把这个链接露出来，用户点进去再点「允许」

引导页跑在中台域名上，「JS 接口安全域名」因此只占用中台这 1 条名额。 页面文案已明确写"会收到什么、不会收到广告"，符合微信对诱导订阅的限制。

方式 2：站点自己弹窗后回报额度

POST https://wx.onzx.cn/api/v1/message/grant
{ "openid": "oXXXX…", "template_id": "…", "times": 1 }

额度是"用户同意次数"，不与具体内容绑定；后台会记录 剩余/已用， 微信用户 与 消息模板 页都能看到。

频控与合规红线

• 中台硬闸：同一收件人同一事件每日上限（hub_msg_rate_day，默认 8），超过直接 skipped。
• 微信口径：同类通知 7 天内不宜超过 3 条、两次推送间隔不宜小于 12 小时；无交互的冷启动推送属违规。
• 45009（日配额耗尽）自动退避到 1 小时后重试。不要手动狂点重发 —— 配额是全账号共享的，包括 edusoho 的用量。
• 模板消息行业类目里没有「心理咨询」，只能在现有类目（如教育）的模板库里挑。 api_set_industry 每月只能改 1 次，且改类目会删除原类目已申请的模板 —— 存量系统在用模板消息时千万不要改类目。

错误码速查

本页内容随代码一起版本化（V0.1.0）。发现文档与实际行为不一致，请当缺陷报告。