飞书消息通知没有送达时，建议先查渠道配置，再查接口权限。渠道配置决定消息能否被正确路由到目标群或目标人，接口权限决定调用能否被飞书接受；两类问题都会表现为“没收到”，但配置问题的定位成本更低、证据更直接、修改也更容易回退。下面按“确认发送是否触发—核对渠道配置—核对接口权限—验证与预防”的顺序展开，范围限定在研发平台对接飞书的消息通知渠道。
要点总览（TL;DR）
- 先查渠道配置，再查接口权限：配置问题定位成本低、证据直接、修改可回退，适合作为第一站。
- 排查前先把“没送达”拆成症状：完全无消息、部分人收到、延迟到达、内容为空，分别指向不同的检查入口。
- 渠道配置按“是否触发—发往哪里—发给谁—发什么内容”逐项核对，并记录检查结果作为证据。
- 配置排除后再看调用返回码、应用权限范围、可用范围与凭证状态；修改权限前记录原状态并保留回退方式。
- 修复后用一条测试消息验证端到端链路，并对历史失败消息补发，同时建立失败告警与定期巡检。
症状与范围：先分清“没发出”还是“没收到”
“通知没送达”是一个笼统描述，直接动手改配置容易把原本正常的设置改乱。第一步是把症状拆成可观察的事实，判断问题出在发送侧还是接收侧，再决定查哪里。
发送侧关注研发平台是否触发了发送动作、调用是否成功返回；接收侧关注飞书是否收到消息、是否在正确的会话中展示。两侧的检查入口不同，先分清可以避免在错误的一侧反复尝试。
| 症状 | 常见指向 | 优先确认 |
|---|---|---|
| 完全没有任何消息 | 发送动作未触发，或调用被拒绝 | 触发条件是否满足、调用是否返回成功 |
| 部分人收到、部分人没收到 | 接收对象映射或可用范围不一致 | 接收人清单与实际账号、应用可见范围 |
| 消息延迟到达 | 调用重试、队列积压或频率限制 | 调用时间戳、返回码、发送频率 |
| 消息发出但内容为空或报错 | 消息类型不被支持、字段缺失 | 消息体结构、渠道支持的消息类型 |
本文讨论研发平台对接飞书消息通知渠道的排查与恢复。飞书目录认证、企业身份账号集成，以及团队日常沟通规范与信息同步策略，属于另外的话题，这里不展开。
为什么先查渠道配置：两类故障的表现差异
先查渠道配置，依据是排查成本和证据可得性，而非配置问题更常见。配置层的检查大多可以在管理后台或规则页面直接看到结果，影响面可以按群、按人逐一枚举，改错了也能改回来；权限层的问题往往要依赖调用返回码和后台授权记录才能判断，排查链条更长。
渠道配置类问题通常表现为：消息发到了错误的群或人；机器人在配置完成后被移出目标群；webhook 地址失效或被重建；使用了当前渠道不支持的消息类型。这类问题的共同点是“路由或承载”出了偏差，消息本身可能已经成功发出。
接口权限类问题通常表现为：调用直接返回权限相关错误码；应用或机器人的可见范围不包含实际接收人；消息发送所需的能力未开通；凭证过期或被重置导致鉴权失败。这类问题的共同点是“调用没有被接受”，发送侧往往能看到明确的失败返回。
| 对比维度 | 渠道配置问题 | 接口权限问题 |
|---|---|---|
| 典型表现 | 发错对象、机器人不在群、webhook 失效、消息类型不支持 | 返回权限错误码、可见范围不含接收人、能力未开通、凭证失效 |
| 证据来源 | 渠道配置页面、群成员列表、规则设置 | 调用返回码、授权记录、凭证状态 |
| 定位成本 | 较低，可逐项核对 | 较高，需要结合返回信息判断 |
| 修改影响 | 可回退，影响面可枚举 | 涉及授权变更，需记录原状态 |
需要说明的是，两类问题可能同时存在。先配置后权限是为了逐步缩小范围，把容易确认的因素先排除，并非认定权限问题可以忽略。如果配置检查全部正常而消息仍未送达，就应把注意力转向权限与调用返回。
第一步：核对渠道配置的检查项
渠道配置排查按“是否触发—发往哪里—发给谁—发什么内容”的顺序进行，每一项都记录检查结果，作为后续判断的证据，避免凭印象下结论。
确认发送动作是否真的触发
先看研发平台侧的事件和规则：触发条件是否满足，规则是否处于启用状态，事件是否在预期时间发生。如果发送动作根本没有触发，后面的渠道和权限检查都没有意义。在 ONES 中，工作项状态变化、评论、流转等事件可以作为通知规则的触发来源，排查时先确认对应规则是否生效、触发记录是否存在。
核对目标渠道
- webhook 地址是否仍然有效，是否被重建或替换过；
- 群机器人是否仍在目标群内，是否被移出或禁用；
- 渠道指向的群或会话是否就是预期接收位置。
核对接收对象
确认接收人是个人、群还是角色，映射关系是否与实际账号一致。人员调岗、离职、账号变更都可能导致映射失效，出现“部分人收到、部分人没收到”的情况。逐条比对接收清单与实际成员，是确认这类问题最直接的方式。
核对消息类型与内容
卡片、文本、富文本在不同渠道的支持程度不同。检查消息体结构是否符合当前渠道要求，必填字段是否为空，变量替换后是否产生了空值。内容为空或格式报错，往往在这一步就能复现。
| 检查项 | 判断标准 | 记录字段 |
|---|---|---|
| 发送动作触发 | 规则启用、触发条件满足、有触发记录 | 规则名称、触发时间、触发结果 |
| 目标渠道 | webhook 有效、机器人在群、指向正确会话 | 渠道标识、群名称、检查时间 |
| 接收对象 | 接收清单与实际账号、群成员一致 | 接收对象类型、比对结果 |
| 消息类型与内容 | 类型受支持、必填字段非空 | 消息类型、字段完整性 |
第二步：核对接口权限与调用返回
渠道配置逐项确认无误后，转向接口权限与调用返回。这一步的核心是拿到调用侧的客观证据，而不是靠猜测判断权限是否足够。
查看调用返回码与错误信息
先区分错误类型：权限拒绝、参数错误、频率限制对应的处理方式完全不同。权限拒绝需要调整授权，参数错误要回到消息体检查，频率限制则要调整发送节奏或合并消息。把返回码和错误信息完整记录下来，是后续判断和复盘的基础。
核对应用权限范围
确认消息发送相关权限是否已申请并生效。权限申请后可能存在生效延迟，也可能因为应用版本调整而发生变化。对照实际调用所需的能力逐项核对，避免出现“申请了但未生效”或“申请的不是实际调用的那一项”。
核对可用范围与凭证
- 应用或机器人的可见范围是否覆盖实际接收人，范围外的用户收不到消息；
- token、密钥是否过期、被重置或与当前环境不匹配；
- 调用所使用的应用身份是否与配置时一致。
修改应用权限和可见范围属于有影响的操作，可能影响其他正在使用该应用的通知和集成。变更前记录原状态，保留回退方式，并在变更后立即用测试消息验证，确认没有波及其他渠道。
在发送侧的证据留存上，ONES 提供 API 接口用于与企业系统集成，通知规则的触发情况、相关变更记录可以在平台内留存，便于在排查时对照“何时改了什么、改前是什么状态”。具体配置入口以实际部署版本为准。
验证恢复与复发预防
定位并修复后，需要用一条测试消息验证端到端链路：从触发、调用、路由到展示，确认接收人正确、内容完整、时延在可接受范围内。只验证“调用返回成功”不够，还要确认消息确实出现在预期的会话中。
对故障期间未送达的历史消息，按重要程度做补发或人工通知，避免关键信息出现缺口。补发前确认接收对象已修正，避免把旧消息再次发错位置。
预防复发可以从三方面入手：
- 建立发送失败告警，覆盖调用失败率、消息延迟、机器人状态异常等指标；
- 定期巡检渠道配置，包括 webhook 有效性、机器人在群状态、接收对象映射；
- 把渠道配置与权限变更纳入变更记录，记录变更人、时间、内容和回退方式，便于同类问题快速定位。
完成上述步骤后，再遇到“通知没送达”，可以按同一顺序复走一遍：先确认发送是否触发，再核对渠道配置，然后核对接口权限与返回，最后验证恢复并更新告警和巡检项。顺序稳定，排查就不会每次从零开始。
常见问题
渠道配置和接口权限都检查过、看起来都正常，消息还是没送达，接下来查什么？
把注意力转向调用链路的中间环节和消息本身。可以按以下顺序继续：
- 核对消息内容与频率限制：消息体是否超出渠道允许的结构，发送频率是否触发限流，限流往往表现为延迟或部分丢失。
- 核对调用时间戳与重试记录：确认调用是否真的在预期时间发出，是否存在重试后仍未成功的情况。
- 核对接收端的展示条件：接收人是否屏蔽了该机器人或会话，消息是否进入了免打扰或折叠位置。
- 用一条最小化的测试消息单独验证链路，排除业务消息体本身的干扰。
如果以上都正常，建议保留完整的调用记录和接收端截图，再向飞书开放平台侧或研发平台侧提交工单，避免反复修改配置扩大影响面。
只影响部分接收人，其他人能正常收到，应该优先查哪一侧？
部分人收到、部分人没收到，通常指向“接收对象映射”或“可用范围”不一致，两类原因要分开确认。
- 先查渠道配置中的接收对象：接收人是个人、群还是角色，清单与实际账号是否一致。人员调岗、离职、账号变更都可能让映射失效。
- 再查应用或机器人的可用范围：范围外的用户收不到消息，这一项属于权限层，但表现与配置问题相似。
建议逐条比对接收清单与实际成员，把差异人员单独列出，再判断差异是来自映射配置还是可见范围。两类原因可能同时存在，先修正映射再调整范围，便于观察每一步的效果。
修改应用权限或可见范围时，需要注意哪些风险？
修改应用权限和可见范围属于有影响的操作，可能波及其他正在使用该应用的通知和集成。执行前建议做到：
- 记录变更前的权限清单和可见范围，保留可回退的配置快照；
- 确认该应用还被哪些渠道或系统使用，评估变更的连带影响；
- 选择影响较小的时段变更，变更后立即用测试消息验证；
- 把变更人、时间、内容和回退方式写入变更记录。
权限申请后可能存在生效延迟，验证时留出一定观察时间，避免因延迟误判为配置错误而反复调整。
修复后如何确认通知真的恢复了，而不只是调用返回成功？
调用返回成功只说明请求被接受，不代表消息已经出现在正确的会话中。验证应覆盖端到端链路：
- 从研发平台侧触发一次真实事件，确认触发记录存在；
- 确认消息出现在预期的群或会话中，接收人正确；
- 检查消息内容完整，变量替换后没有空值；
- 记录从触发到展示的时延，确认在可接受范围内。
对故障期间未送达的历史消息，按重要程度补发或人工通知，补发前先确认接收对象已修正，避免旧消息再次发错位置。
怎样减少同类问题再次发生？
可以从告警、巡检和变更记录三方面入手：
- 建立发送失败告警，覆盖调用失败率、消息延迟、机器人状态异常等指标，让问题在接收人反馈之前被发现；
- 定期巡检渠道配置，包括 webhook 有效性、机器人在群状态、接收对象映射，人员变动后及时复核；
- 把渠道配置与权限变更纳入变更记录，记录变更人、时间、内容和回退方式。
在 ONES 中，通知规则的触发情况与相关变更记录可以在平台内留存，便于排查时对照“何时改了什么、改前是什么状态”，具体配置入口以实际部署版本为准。
