服务通知接入(服务端)
本文面向负责业务服务端、MCP Server 和通知策略的开发者,说明如何为豆包应用插件配置通知模板,并在业务事件发生后向指定用户发送服务通知。
服务通知是业务服务端主动调用平台 OpenAPI 的能力,不要求为每条通知新增 MCP Tool、Widget 或 Page。只有通知需要落地页、通知设置页或对话入口时,才需要同步开发前端或 MCP 能力。
接入目标
服务通知适合订单状态变化、预约提醒、审核结果、服务完成等“业务事实已经发生,需要主动提醒用户”的场景。完整接入需要解决四件事:
- 在
business-templates.yaml中声明通知标题、摘要、展示字段和变量; - 将模板同步到当前应用并完成审核上线;
- 业务服务端取得应用级 AccessToken 和目标用户 OpenID;
- 按业务事件生成稳定幂等键,调用服务通知 OpenAPI 并记录结果。
标准链路为:
- 业务事件发生后,按事件选择固定的
template_id; - 从可信账号绑定中取得目标用户 OpenID;
- 获取并缓存应用级 AccessToken;
- 构造模板变量和稳定的
out_msg_id; - 调用
push_send; - 当
code == 0且notice_id非空时,记录为“平台已接受”,否则分类失败并按策略重试; - 最后使用真机确认用户侧展示。
结果口径:接口返回
notice_id只表示平台已接受发送请求,不等于通知已经送达,也不等于用户侧已经展示。实际展示必须通过真机观察确认。
名词解释
接入前准备
AppSecret、AccessToken、完整 OpenID、完整通知正文和业务敏感字段只能存在于服务端安全边界,不得写入前端、Manifest、运行态 Skill、代码仓库或普通日志。
配置通知模板
标准项目布局:
通知模板示例:
字段说明
brief 应在用户不展开通知卡片时也能独立表达关键信息。只在 brief 中使用的变量同样必须加入 variable_list。
字段含义确定后,不要随意更改 keyword_key。同一事件如果用户授权语义或字段集合明显不同,应使用新的 template_id,不要用大量可选变量承载无关通知。
校验与同步模板
修改模板后先执行兼容校验:
只同步业务模板,不提交新的前端、Manifest 或 Skill 版本时:
显式同步要求项目根目录存在 business-templates.yaml;文件不存在时命令失败。执行 dbx build 创建完整版本时,该文件会自动参与严格校验和同步;文件缺失则跳过,不会清空远端。必须检查 config_sync_results 中每个模板的结果,不能只看版本提交成功或命令退出码。
从本地 YAML 中删除模板不代表平台模板被删除或下线。删除、下线必须使用平台明确提供的管理操作。
获取调用凭证和目标用户
应用级 AccessToken
业务服务端使用 AppID、AppSecret 调用应用级 Token 接口,并按 expires_in 缓存复用。不要在每次通知发送前重新获取 Token,也不要让多个业务模块各自并发刷新。
建议使用统一 Token Provider,提供:
- 缓存与提前刷新;
- 并发 single-flight;
- 原子换新;
- Token 明确失效时最多强制刷新并重试一次;
- 不在日志中输出 Token。
目标用户 OpenID
目标 OpenID 必须来自当前应用下的可信账号绑定记录。业务服务端根据业务事件和账号关系决定接收人,不接受客户端传入任意 OpenID。
缺少可信 OpenID 时应停止发送并记录可诊断错误,不能使用固定测试用户、默认 OpenID 或其它身份 fallback。
发送服务通知
基本信息
服务端 API 域名以 服务端 API 总览 中当前环境说明为准。
请求头
请求体
请求示例:
channel_info_list、biz_data 和 jump_data 在外层协议中都是 JSON 字符串。实现时应使用语言 JSON 库完成内外两层序列化,不能手工拼接转义文本。
jump_data 只能指向当前应用插件内部已注册的 Page,不允许透传用户提供的任意外部 URL。
响应
只有 code == 0 且 data.notice_id 非空时,才能把本次记录更新为“平台已接受”。HTTP 200 但业务码非 0 时仍是业务失败。
幂等、重试与可观测性
- 业务事件第一次进入发送流程时生成并持久化
out_msg_id; - 网络超时或可重试错误继续使用原
out_msg_id; - 模板、权限、变量等确定性错误不盲目重试;
- 限流或短暂网络错误使用有上限的指数退避;
- 保存模板 ID、脱敏用户标识、
out_msg_id、平台结果码、耗时和log_id; - 不记录 AccessToken、完整 OpenID、完整
biz_data或敏感通知正文。
建议将通知状态至少拆分为:
调试与验收
模拟器调试
启动 dbx dev 创建 Sandbox Session 时,CLI/平台会将当前 Manifest 与可选 business-templates.yaml 加入 Session 创建请求。模板变化后:
- 手动重新执行模板兼容校验;
- 在 Web 调试面板撤回并重建 Session;
- 使用模拟器链路实际注入的身份调用通知接口。
只刷新页面不会更新已有 Session。Session 创建成功也不代表模板已经正式同步,更不代表通知已在用户侧展示。
真机调试与正式上线
真机调试必须让 business-templates.yaml 与当前 Manifest、前端资源和其它产物一起进入该次调试包。模板单独同步或模拟器 Session 不能替代真机调试。
正式发送前必须确认:
- 模板已严格校验、同步成功、审核通过并处于可用状态;
- AppID、AppSecret、OpenID、AccessToken 和模板属于同一应用与环境;
- 接收范围、用户授权/关闭策略、频控和重试策略已明确;
- 使用受控测试账号验证,避免向真实用户批量发送测试通知。
常见问题
模板校验提示缺少 brief
每个通知模板都必须提供非空 brief。摘要中的占位符也必须加入 variable_list,运行时由 biz_data 提供。
接口提示变量不匹配
检查 biz_data 是否为字符串到字符串的 JSON 对象。所有声明变量都要提供,不能少传、多传,也不能传平台保留变量。
HTTP 200,但没有收到通知
先检查响应业务 code 和 notice_id。即使平台已接受,也要分别检查模板状态、目标环境、目标 OpenID、成功渠道和真机展示;不能把 HTTP 200 直接视为送达。
网络重试后出现重复通知
确认同一业务事件是否复用了持久化的 out_msg_id。每次重试生成新 ID 会失去幂等保护。
模拟器接口成功,但看不到通知
模拟器是否提供通知展示入口取决于当前版本。没有实际观察到入口时,应记录为 UNSUPPORTED 或 NOT VERIFIED,不能由接口成功推断用户侧已展示。
上线检查
business-templates.yaml与manifest.yaml路径关系正确;- 每个通知模板都有稳定且全局唯一的
template_id; brief非空,标题、摘要和关键词中的变量均正确声明;- 模板已完成严格校验、同步和审核上线;
- 应用级 Token 统一缓存和刷新,不在日志或前端暴露;
- OpenID 来自可信账号绑定;
- 同一业务事件使用稳定
out_msg_id; - 参数错误与短暂错误采用不同重试策略;
- 平台接受、实际送达和用户侧展示分别记录;
- 已使用受控账号完成真机验证。