---
docStatus: current
---

# 通知与投递

明确组织通知、渠道消息、已读和业务处理之间的边界，选择公开能力并验证投递结果。

组织通知表达“什么事需要告知谁”。渠道发送表达“把这段内容投递到哪个外部会话”。通知可能需要收件箱、偏好、模板、路由和投递记录；一次渠道发送不能自动代表这些能力都已执行。

## 按需求选择入口

| 需求                | 使用方式                                                                                                 |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| 给已选定的企微私聊发一条消息    | 按[渠道与会话消息](/development/organization-capabilities/channel-messages/)调用 `sendExternalSessionMessage`。 |
| 将结果发回原渠道会话        | 调用 channel gateway 的 `sendSessionMessage`。                                                           |
| 向已绑定群聊发送通知文本      | 先查询群聊通讯录，再调用其公开群聊发送方法。                                                                               |
| 需要统一通知记录、偏好或多渠道路由 | 先确认目标工作区已安装的通知能力和公开方法合同，再由通知能力安排投递。                                                                  |
| 要求某人处理并提交结果       | 创建[人工事项](/development/organization-capabilities/issues/)，消息只负责提醒和提供访问入口。                             |

本章确认的 channel gateway 发送方法不承担统一通知收件箱或已读管理。不能因为平台存在通知实现，
就假设任意工作区都已安装同名 Module，或编造一个通用 `notifyUser` 方法。

## 从业务事件到投递

1. 业务操作产生明确事件和业务对象引用，例如一份已生成报告或待处理事项。
2. 从组织目录确定接收主体，从通讯录解析联系方式；不要把工作流执行用户默认当作接收人。
3. 根据业务要求选择“通知能力管理投递”或“明确渠道会话直接发送”。
4. 记录实际调用结果与关联业务对象，失败时进入可观察的处理路径。
5. 需要用户处理时，查询事项结果；需要已读时，只使用对应渠道或通知能力确实提供的回执。

定时触发、事件触发和工作流编排分别见[定时任务](/features/scheduled-tasks/)、
[Event Trigger 开发](/development/bundle-development/event-trigger-development/)和[工作流](/features/workflows/)。

## 成功、重试和重复消息

消息方法返回成功或 `delivered: true`，不等于用户已读，也不等于业务完成。
通过公开 API 调用时按照[CModel 错误模型](/integration/cmodel-error-model/)检查业务结果，不能仅凭 HTTP 状态判断。

网络超时可能发生在外部渠道已接受消息之后。给工作流添加自动重试前，必须确认目标方法的幂等合同和投递查询能力；
不能仅凭参数里出现 `eventId` 就推断整个链路保证去重。不确定是否已发送时，先检查执行记录和投递证据，再决定是否重发。

## 上线验收

用授权测试接收人验证成功路径、未绑定、渠道停用和权限不足。
区分“业务事件已产生”“通知已受理”“渠道已接受”“对方已读”“事项已完成”，只报告实际可证明的状态。