messaging-performance-analyzer

消息性能分析器

概述

使用此技能，将原始 Sent 消息证据转化为简洁的诊断，说明发生了哪些变化、漏斗在哪个环节出现流失，以及应优先修复什么。在解读运营商、WhatsApp 或 RCS 提供商代码之前，所有分析都应以 Sent 消息 ID、消息状态、消息活动记录 和 webhook 事件 为依据。

Sent v3 发送端点接受基于模板的请求，并为异步跟踪返回每位收件人的 message_id 值。可通过 GET /v3/messages/{id} 获取状态，并通过 GET /v3/messages/{id}/activities 获取详细的生命周期证据。Webhook 端点支持事件接收、事件类型发现、事件历史记录、测试投递和密钥轮换。

适用场景

当用户询问消息为何失败、投递率或已读率为何下降、回退是否正常工作、提供商是否在过滤流量，或营销活动表现如何时，使用此技能。遇到诸如“MDR”、“投递报告”、“webhook 事件”、“活动记录”、“状态”、“失败”、“未投递”、“已读率”、“回退”、“过滤”、“限流”或“运营商拒绝”等词语时触发。

不要使用此技能来注册 10DLC、设计 Sender Profile、接入 RCS 或编写 WhatsApp 模板。症状明确后，将这些工作流程交给相关技能处理。

证据层级

先从 Sent 自身的证据入手，再结合提供商的上下文。这可以避免过度依赖可能缺失、过时或在不同渠道间采用不同标准化方式的运营商代码。

证据	Sent 验证路径	用途
发送响应	POST /v3/messages	确认请求 ID、已接受的收件人、渠道分发情况以及 Sent message_id 值。
当前状态	GET /v3/messages/{id}	确认最新的已知生命周期状态，以及 API 提供的错误详情。
活动时间线	GET /v3/messages/{id}/activities	还原接受、路由、发送、投递、已读和错误状态转换。
Webhook 配置	GET /v3/webhooks、GET /v3/webhooks/event-types	确认客户是否订阅了分析所需的事件。
Webhook 事件历史记录	GET /v3/webhooks/{id}/events	对比已投递的事件、API 状态和客户的接收日志。
Webhook 连通性	POST /v3/webhooks/{id}/test	在归咎于投递基础设施之前，验证端点是否可访问。

流程

1. 在拆分漏斗前明确问题

将用户的确切问题重述为可衡量的比较。“WhatsApp 效果很差”应改为“从周一到周三，使用配置文件 A 发送的订单模板中，WhatsApp DELIVERED 率是否下降？”明确的问题能确保队列保持稳定，并避免混合渠道的平均值掩盖故障模式。

在进行任何计算之前，记录以下维度：配置文件或发送方身份、模板 ID/名称、渠道、国家/地区、发送时段、收件人细分，以及是否请求了回退或多渠道广播。

示例。 如果用户说“RCS 回退不再生效”，则将队列定义为未指定 channel 或使用 channel: ["sent"] 的发送，然后对比所选的 payload.channel 和消息活动记录。对任何显式指定的多渠道数组，应作为广播单独分析。

2. 根据 Sent 消息 ID 构建群组

以 Sent message_id 作为主要统计单位。指定多个渠道时，v3 发送操作可能会针对每个收件人和渠道组合分别创建消息。在汇总终态结果时，每条 Sent 消息只计数一次；去重后再进行收件人级或活动级汇总。

区分活动历史记录和最新状态快照。历史记录可以证明其中包含的状态转换。像 status=DELIVERED 这样的快照只能证明观察到的当前结果；它不能证明导出数据也观察到了 QUEUED、ROUTED 或 SENT。如果无法获取状态转换的分母，请报告为 N/A，而不是 0；切勿合成缺失的状态转换。

除非导出的证据中没有 Sent ID，否则不要使用 WhatsApp wamid、SMS 运营商 ID 或 RCS 消息 ID 等提供商 ID 作为主要关联键。提供商 ID 有助于升级处理问题，但 Sent API 和仪表板会根据 Sent 消息 ID 跟踪状态。

3. 将生命周期阶段规范化为 Sent 文档中定义的状态

将 Sent 文档中定义的投递生命周期作为初步漏斗：QUEUED、ROUTED、SENT 和 DELIVERED。将 READ 作为 WhatsApp 和 RCS 的独立互动指标，不要将其视为 SMS 的投递要求。将终态失败、延迟／进行中消息、入站 RECEIVED 消息以及格式错误／未知记录分别归入不同类别，只使用证据中存在的字段。

阶段	说明	常见诊断问题
QUEUED	Sent 已接受请求并准备处理。	待处理队列是否在增长，或者请求从未进入路由？
ROUTED	Sent 已选择渠道／提供商路径。	路由是否选择了预期渠道或回退路径？
SENT	消息已从 Sent／提供商处理流程发往目标网络。	提供商接受率很高，但下游投递率偏低吗？
DELIVERED	在支持的情况下，投递已得到确认。	目标网络是否确认收到消息？
READ	在可用时，已观察到 WhatsApp／RCS 已读回执。	用户是否在收到消息后打开了它？
错误／失败	发生了终态或可恢复错误。	根本原因是合规问题、负载问题、吞吐量问题、退订还是提供商中断？

4. 诊断投递问题前先检查 Webhook 健康状况

仪表板活动或客户侧事件减少，可能是 Webhook 接收问题，而非投递问题。确认 Webhook 是否存在、是否处于活动状态、事件订阅、最近的事件历史记录以及测试投递情况。只有在用户明确要求或怀疑凭据已泄露时才轮换密钥，因为轮换会立即使旧密钥失效。

示例。 如果 Sent 状态显示 DELIVERED，但客户数据库显示“没有投递回调”，请检查 /v3/webhooks/{id}/events 和客户的端点日志。如果 Sent 有事件，但端点返回失败，则应修复 Webhook 处理，而不是调整活动路由。

5. 先按渠道拆分，再判断根本原因

SMS、WhatsApp 和 RCS 的故障模式各不相同。除非用户明确要求混合 KPI，否则不要将它们合并求平均值。分别比较每个渠道的漏斗，再比较汇总结果。

渠道	首要细分维度	常见的后续证据
SMS	国家／地区、发送方／配置文件、10DLC 活动、退订、运营商类型	合规状态、品牌／活动准备情况、退订日志、吞吐量模式。
WhatsApp	模板、语言、类别、收件人国家／地区、质量／层级表现	模板状态、已读回执、对话窗口，以及可用时的 Meta 侧错误。
RCS	Agent 就绪状态、自动路由、固定渠道故障、文本／建议芯片渲染	Sent RCS 设置状态、所选路由以及准确的活动／错误详情。

6. 在建议修复方案前量化影响

同时报告原始数量和比率。在 15 条消息中失败率为 40%，与在 150,000 条消息中失败率为 4%，对应的决策并不相同。核对全局总数与每个渠道 × 方向分组的数据，保留明确的 unknown 分组，不要悄悄丢弃不完整的维度。列出排除项，例如待处理消息、测试流量、沙盒发送、重试和重复的渠道扇出。

实用的分析表应包括：发送数量、最新状态分布、失败数量、相较基线的失败率变化、最常见的精确错误字符串/代码、首次观测时间、受影响的模板、受影响的国家和受影响的配置文件。

7. 将诊断转化为下一步行动

最后给出一个主要诊断、一个置信度等级，以及下一步验证措施。避免罗列大段通用修复建议。每项建议都应与观测到的证据相关联。

示例。“最大流失发生在 ROUTED 之后，涉及配置文件 support-us 上的 SMS 流量，始于 14:10 UTC。WhatsApp 和 RCS 分组保持稳定。受影响的流量使用相同的订单更新模板和美国 A2P 路由。接下来请核实 Sent 品牌/活动状态和退订处理；如果符合规定，则升级处理并提供确切的消息 ID 和活动时间戳。”

应避免的常见说法

在检查 Sent webhook 事件历史和端点响应之前，不要根据缺少客户侧 webhook 推断消息未送达。Webhook 接收故障常常会伪装成消息未送达。

不要仅凭小样本就将活动标记为“运营商过滤”；应先比较基线、国家、发送方/配置文件和模板。过滤是隔离分组后得出的结论，不是“失败”的同义词。

不要将 READ 视为通用阶段。Sent 为 WhatsApp 和 RCS 提供已读回执文档；SMS 通常不支持已读回执。

不要将广播误认为回退路由。省略 channel 或使用 ["sent"] 会启用自动路由；指定一个渠道会固定投递渠道；指定多个值则会创建多条独立消息。每个返回的 message_id 只计数一次，并报告所选渠道。

验证清单

• 分析以 Sent message_id 值作为主要统计单位。
• 按时间窗口、配置文件/发送方身份、模板、渠道和接收者分组固定分析范围。
• 状态统计使用每个 Sent 消息 ID 的最新已知状态。
• 阶段转换统计使用观测到的活动历史，绝不根据仅含最新状态的数据补填阶段。
• 待处理或正在处理的消息要么排除，要么单独报告。
• SMS 投递分析止于 DELIVERED；WhatsApp/RCS 的 READ 标记为互动。
• 全局总数与渠道 × 方向总数相符，并包括格式错误和明确的 unknown 分组。
• 如果症状是缺少回调，则检查 webhook 配置、事件历史和端点测试结果。
• 汇报汇总比率前，先拆分渠道特定的失败情况。
• 提供方或运营商代码必须按观测到的内容原样引用，不能根据查找表臆造。
• 最终建议需指出一项下一步验证措施，以及支持该措施的证据。

相关技能

如果流失原因指向美国 A2P SMS 合规、品牌注册、活动注册或加入/退出订阅的证据，请使用 sms-10dlc-registration。

如果症状指向 RCS Agent 审批、上线准备、能力缺口或回退设计，而非实时投递分析，请使用 rcs-agent-onboarding。

如果问题涉及租户/配置文件隔离、webhook 路由、凭据范围或多品牌发送方设计，请使用 sender-profile-architect。

如果根本原因是 WhatsApp 模板类别、审核状态、模板负载结构或编写工作流，请使用 waba-template-author 或 template-builder-ui。

使用 sent 技能了解 Sent 的通用术语和路由。

随附的参考资料和脚本

文件	类型	用途
references/mdr-status-codes.md	查找表	规范化观测到的 SMS、WhatsApp 和 RCS 服务商错误，无需在技能正文中放入冗长的代码字典。
references/performance-diagnosis-playbook.md	实例分析	用于判断优先调查哪项信号的决策树、按渠道划分的诊断模式、跨技能交接矩阵和升级标准。
scripts/analyze_mdr_funnel.py	验证脚本	读取 MDR 导出文件（CSV 或 JSON），按渠道 × 方向汇总结果，将送达状态转变与互动分开，并保留格式错误或未知的行。从技能根目录运行：python scripts/analyze_mdr_funnel.py path/to/mdr.csv（使用 --threshold N、--show-errors 或 --format json）。退出码 0 表示未观察到状态转变违规，2 表示输入错误或没有可用队列，3 表示观察到违规。JSON 在分母不可用时使用 null；文本使用 N/A。
scripts/fixtures/good.json	测试样例	合成的健康漏斗 MDR 导出文件。
scripts/fixtures/bad.json	测试样例	合成的 MDR 导出文件，其中故意设置了超过 50% 的 SENT→DELIVERED 流失。