For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/backend-development/service-notification.md.

服务通知接入(服务端)

本文面向负责业务服务端、MCP Server 和通知策略的开发者,说明如何为豆包应用插件配置通知模板,并在业务事件发生后向指定用户发送服务通知。

服务通知是业务服务端主动调用平台 OpenAPI 的能力,不要求为每条通知新增 MCP Tool、Widget 或 Page。只有通知需要落地页、通知设置页或对话入口时,才需要同步开发前端或 MCP 能力。

接入目标

服务通知适合订单状态变化、预约提醒、审核结果、服务完成等“业务事实已经发生,需要主动提醒用户”的场景。完整接入需要解决四件事:

  1. 在 business-templates.yaml 中声明通知标题、摘要、展示字段和变量;
  2. 将模板同步到当前应用并完成审核上线;
  3. 业务服务端取得应用级 AccessToken 和目标用户 OpenID;
  4. 按业务事件生成稳定幂等键,调用服务通知 OpenAPI 并记录结果。

标准链路为:

  1. 业务事件发生后,按事件选择固定的 template_id;
  2. 从可信账号绑定中取得目标用户 OpenID;
  3. 获取并缓存应用级 AccessToken;
  4. 构造模板变量和稳定的 out_msg_id;
  5. 调用 push_send;
  6. 当 code == 0 且 notice_id 非空时,记录为“平台已接受”,否则分类失败并按策略重试;
  7. 最后使用真机确认用户侧展示。

结果口径:接口返回 notice_id 只表示平台已接受发送请求,不等于通知已经送达,也不等于用户侧已经展示。实际展示必须通过真机观察确认。

名词解释

对象作用关键规则
business-templates.yaml保存服务通知和远程任务的应用级业务模板与 manifest.yaml 独立;标准布局下放在项目根目录
template_id开发者定义的通知模板稳定标识字符串;通知模板与任务模板之间也不能重名
brief通知列表或系统提醒中的摘要必填、非空;可以引用已声明变量
variable_list模板允许运行时传入的变量集合所有占位符都必须声明;运行时变量值均为字符串
open_id当前应用下的用户身份标识必须来自可信账号绑定,不能接受客户端任意指定其他用户
out_msg_id开发者侧消息幂等键同一业务事件重试必须复用
notice_id平台侧通知 ID仅代表平台接受请求后的资源标识

接入前准备

顺序开发者要完成的动作关键产出
1创建豆包应用插件并获取 AppID、AppSecret应用级凭据
2按 登录接入(服务端) 建立 OpenID 与业务账号的可信绑定可定位目标用户的 OpenID
3明确通知触发事件、接收范围、用户关闭策略、落地页和重试策略通知业务规则
4在项目根目录准备 business-templates.yaml可校验的通知模板
5实现应用级 Token 缓存和通知发送记录安全、可恢复的发送链路

AppSecret、AccessToken、完整 OpenID、完整通知正文和业务敏感字段只能存在于服务端安全边界,不得写入前端、Manifest、运行态 Skill、代码仓库或普通日志。

配置通知模板

标准项目布局:

<project>/
├── manifest.yaml
└── business-templates.yaml

通知模板示例:

schema_version: 1

notice_templates:
  - template_id: milk_tea_ready
    name: "奶茶制作完成通知"
    title: "你的{name}已经做好啦"
    brief: "{name}已制作完成,取餐码 {pickup_code}"

    variable_list:
      - name
      - pickup_code
      - store_name

    keywords:
      - keyword_key: pickup_code
        keyword_name: "取餐码"
        field_value: "{pickup_code}"

      - keyword_key: store_name
        keyword_name: "取餐门店"
        field_value: "{store_name}"

字段说明

字段必填说明
schema_version是当前固定为 1
template_id是应用内稳定业务标识;最长 128,只包含字母、数字、_、-
name是模板管理名称,不允许占位符
title是通知标题,可以引用已声明变量
brief是通知摘要,不能为空或只包含空格
variable_list按需模板变量集合;变量名以字母开头,只包含字母、数字和下划线
keywords是通知卡片展示字段,至少一项
keyword_key是模板内稳定字段 key,不可重复
keyword_name是用户可见字段名,不允许变量
field_value否用户可见字段值;省略时默认使用 {keyword_key}

brief 应在用户不展开通知卡片时也能独立表达关键信息。只在 brief 中使用的变量同样必须加入 variable_list。

字段含义确定后,不要随意更改 keyword_key。同一事件如果用户授权语义或字段集合明显不同,应使用新的 template_id,不要用大量可选变量承载无关通知。

校验与同步模板

修改模板后先执行兼容校验:

dbx check --file ./business-templates.yaml --json

只同步业务模板,不提交新的前端、Manifest 或 Skill 版本时:

dbx config sync business-templates \
  --project <project-root> \
  --json

显式同步要求项目根目录存在 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。

发送服务通知

基本信息

名称描述
HTTP Path/api/miniapp_notify/v1/developer/push_send
HTTP MethodPOST
Content-Typeapplication/json
鉴权X-DB-AccessToken

服务端 API 域名以 服务端 API 总览 中当前环境说明为准。

请求头

字段必填说明
X-DB-AccessToken是使用 AppID、AppSecret 获取的应用级 Token
Content-Type是固定为 application/json

请求体

字段必填说明
open_id是当前应用下目标用户的 OpenID
template_id是business-templates.yaml 中声明的通知模板 ID
channel_info_list是JSON 字符串;服务通知使用 ["service_notice"]
biz_data是JSON 字符串;内容为 map<string,string>,变量与模板声明精确匹配
out_msg_id建议稳定消息幂等键;同一业务事件重试时复用
jump_data否JSON 字符串;通知点击后的应用插件内部 Page 信息
ext_data否JSON 字符串;只有平台当前协议明确要求时才传

请求示例:

{
  "open_id": "<user_open_id>",
  "template_id": "milk_tea_ready",
  "channel_info_list": "[\"service_notice\"]",
  "biz_data": "{\"name\":\"珍珠奶茶\",\"pickup_code\":\"A018\",\"store_name\":\"中关村店\"}",
  "out_msg_id": "milk-tea-order-20260722-001-ready",
  "jump_data": "{\"path\":\"pages/order/detail\",\"query\":\"order_id=20260722-001\"}"
}

channel_info_list、biz_data 和 jump_data 在外层协议中都是 JSON 字符串。实现时应使用语言 JSON 库完成内外两层序列化,不能手工拼接转义文本。

jump_data 只能指向当前应用插件内部已注册的 Page,不允许透传用户提供的任意外部 URL。

响应

{
  "code": 0,
  "msg": "success",
  "log_id": "202607220001",
  "data": {
    "notice_id": "1234567890",
    "success_channel_list": ["service_notice"],
    "fail_channel_list": []
  }
}

只有 code == 0 且 data.notice_id 非空时,才能把本次记录更新为“平台已接受”。HTTP 200 但业务码非 0 时仍是业务失败。

幂等、重试与可观测性

  1. 业务事件第一次进入发送流程时生成并持久化 out_msg_id;
  2. 网络超时或可重试错误继续使用原 out_msg_id;
  3. 模板、权限、变量等确定性错误不盲目重试;
  4. 限流或短暂网络错误使用有上限的指数退避;
  5. 保存模板 ID、脱敏用户标识、out_msg_id、平台结果码、耗时和 log_id;
  6. 不记录 AccessToken、完整 OpenID、完整 biz_data 或敏感通知正文。

建议将通知状态至少拆分为:

状态含义
待发送业务事件已落库,尚未调用平台
平台已接受code == 0 且返回 notice_id
平台拒绝参数、模板、权限或业务校验失败
结果未知请求超时,需使用同一 out_msg_id 重试或核对
用户侧已确认仅在受控测试中实际观察到通知展示

调试与验收

模拟器调试

启动 dbx dev 创建 Sandbox Session 时,CLI/平台会将当前 Manifest 与可选 business-templates.yaml 加入 Session 创建请求。模板变化后:

  1. 手动重新执行模板兼容校验;
  2. 在 Web 调试面板撤回并重建 Session;
  3. 使用模拟器链路实际注入的身份调用通知接口。

只刷新页面不会更新已有 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;
  • 参数错误与短暂错误采用不同重试策略;
  • 平台接受、实际送达和用户侧展示分别记录;
  • 已使用受控账号完成真机验证。