messaging-performance-analyzer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Messaging performance analyzer

消息性能分析工具

Overview

概述

Use this skill to turn raw Sent message evidence into a concise diagnosis of what changed, where the funnel leaks, and what to fix first. Anchor every analysis to Sent message IDs, message status, message activities, and webhook events before interpreting carrier, WhatsApp, or RCS provider codes.

Sent’s v3 send endpoint accepts a template-based request and returns per-recipient

message_id

values for asynchronous tracking. Status is retrieved with

GET /v3/messages/{id}

, and detailed lifecycle evidence is retrieved with

GET /v3/messages/{id}/activities

. Webhook endpoints support event ingestion, event-type discovery, event history, test delivery, and secret rotation.

使用该技能可将原始Sent消息数据转化为简洁的诊断结果，明确变化点、漏斗流失位置及首要修复项。在解读运营商、WhatsApp或RCS服务商代码之前，所有分析都必须基于Sent消息ID、消息状态、消息活动及webhook事件展开。

Sent的v3发送接口接受基于模板的请求，并返回每个收件人的

message_id

值用于异步跟踪。可通过

GET /v3/messages/{id}

获取消息状态，通过

GET /v3/messages/{id}/activities

获取详细的生命周期数据。Webhook接口支持事件接收、事件类型发现、事件历史查询、测试投递及密钥轮换功能。

When to use

使用场景

Use this skill when the user asks why messages failed, why delivery or read rate dropped, whether fallback is working, whether a provider is filtering traffic, or how a campaign performed. Trigger on words such as “MDR,” “delivery report,” “webhook event,” “activities,” “status,” “failed,” “undelivered,” “read rate,” “fallback,” “filtering,” “throttling,” or “carrier reject.”

Do not use this skill to register 10DLC, design a Sender Profile, onboard RCS, or author WhatsApp templates. Hand those workflows to the related skills after the performance symptom is isolated.

当用户询问消息发送失败原因、投递/读取率下降原因、Fallback是否正常工作、服务商是否过滤流量，或营销活动表现如何时，使用该技能。触发关键词包括：“MDR”、“投递报告”、“webhook事件”、“活动数据”、“状态”、“失败”、“未投递”、“读取率”、“Fallback”、“过滤”、“限流”或“运营商拒绝”。

请勿使用该技能进行10DLC注册、发件人资料设计、RCS接入或WhatsApp模板创建。在定位到性能问题症状后，将这些工作流转交至相关技能处理。

Evidence hierarchy

证据优先级

Start with Sent-owned evidence, then enrich it with provider context. This prevents overfitting to a carrier code that may be missing, stale, or normalized differently across channels.

Evidence	Sent-verified path	Use it for
Send response	`POST /v3/messages`	Identify request ID, accepted recipients, channel fan-out, and Sent `message_id` values.
Current status	`GET /v3/messages/{id}`	Confirm the latest known lifecycle status and any error details exposed by the API.
Activity timeline	`GET /v3/messages/{id}/activities`	Reconstruct acceptance, routing, sending, delivery, read, and error transitions.
Webhook configuration	`GET /v3/webhooks` , `GET /v3/webhooks/event-types`	Confirm whether the customer subscribed to the events needed for analysis.
Webhook event history	`GET /v3/webhooks/{id}/events`	Compare delivered events against API status and customer ingestion logs.
Webhook connectivity	`POST /v3/webhooks/{id}/test`	Verify endpoint reachability before blaming delivery infrastructure.

先以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`	在排查投递基础设施问题前，先验证端点可达性。

Process

分析流程

1. Pin the question before slicing the funnel

1. 明确问题后再拆分漏斗

Restate the user’s exact question as a measurable comparison. “WhatsApp is bad” becomes “Did WhatsApp

DELIVERED

rate fall for order templates sent from profile A between Monday and Wednesday?” A precise question keeps the cohort stable and prevents mixed-channel averages from hiding the failure mode.

Capture these dimensions before calculating anything: profile or sender identity, template ID/name, channel, country, send window, recipient segment, and whether fallback or multi-channel broadcast was requested.

Example. If a user says “RCS fallback stopped working,” define the cohort as messages sent with

channel: ["rcs", "sms"]

during the affected window, then compare RCS statuses, SMS fallback statuses, and duplicate recipient/channel pairs separately.

将用户的问题重述为可量化的对比项。例如“WhatsApp表现很差”可转化为“周一至周三，从资料A发送的订单模板的WhatsApp

DELIVERED

率是否下降？”精准的问题可保持群组稳定性，避免跨渠道平均值掩盖失败模式。

在计算任何指标前，先记录以下维度：资料/发件人身份、模板ID/名称、渠道、国家、发送窗口、收件人群体，以及是否请求了Fallback或多渠道广播。

示例：如果用户说“RCS Fallback停止工作”，则将群组定义为受影响时段内以

channel: ["rcs", "sms"]

发送的消息，然后分别对比RCS状态、SMS Fallback状态及重复收件人/渠道对。

2. Build cohorts from Sent message IDs

2. 基于Sent消息ID构建群组

Use Sent

message_id

as the primary unit. A v3 send can create separate messages for each recipient and channel pair when multiple channels are specified. Count each Sent message once at its latest status, then add recipient-level or campaign-level rollups only after deduplication.

Do not use provider IDs such as WhatsApp

wamid

, SMS carrier IDs, or RCS message IDs as the primary join key unless the exported evidence lacks Sent IDs. Provider IDs are useful for escalation, but the Sent API and dashboard track status by Sent message ID.

以Sent

message_id

作为核心分析单元。当指定多个渠道时，v3发送请求会为每个收件人-渠道对创建独立消息。每个Sent消息仅按其最新状态统计一次，去重后再添加收件人或营销活动级别的汇总数据。

除非导出的证据缺少Sent ID，否则不要将WhatsApp

wamid

、SMS运营商ID或RCS消息ID等服务商ID作为主关联键。服务商ID仅用于问题升级，Sent API及控制台均通过Sent消息ID跟踪状态。

3. Normalize lifecycle stages to Sent’s documented statuses

3. 将生命周期阶段标准化为Sent文档定义的状态

Use Sent’s documented lifecycle as the first-pass funnel:

QUEUED

ROUTED

SENT

DELIVERED

, and

READ

for WhatsApp and RCS. Keep failed and error states in a separate terminal bucket using the exact status/error fields present in the evidence.

Stage	Interpretation	Common diagnostic question
`QUEUED`	Sent accepted the request for processing.	Is the backlog growing or did the request never route?
`ROUTED`	Sent selected a channel/provider path.	Did routing choose the expected channel or fallback path?
`SENT`	The message left Sent/provider processing toward the destination network.	Are provider accepts high but downstream delivery low?
`DELIVERED`	Delivery was confirmed where supported.	Did the destination network confirm receipt?
`READ`	WhatsApp/RCS read receipt was observed where available.	Did users open the message after delivery?
Error/failure	A terminal or recoverable error occurred.	Is the root cause compliance, payload, throughput, opt-out, or provider outage?

以Sent文档定义的生命周期作为初始漏斗：

QUEUED

、

ROUTED

、

SENT

、

DELIVERED

，以及WhatsApp和RCS的

READ

状态。将失败和错误状态单独归入一个终端分组，使用证据中实际存在的状态/错误字段。

阶段	解读	常见诊断问题
`QUEUED`	Sent已接受请求并进入处理流程。	消息积压是否在增加，还是请求从未路由？
`ROUTED`	Sent已选择渠道/服务商路径。	路由是否选择了预期渠道或Fallback路径？
`SENT`	消息已离开Sent/服务商处理系统，发往目标网络。	服务商接收率高但下游投递率低？
`DELIVERED`	在支持的场景下已确认投递成功。	目标网络是否确认收到消息？
`READ`	在支持的场景下已观测到WhatsApp/RCS已读回执。	用户在投递后是否打开了消息？
错误/失败	发生了终端或可恢复错误。	根因是否为合规问题、 payload问题、吞吐量问题、退订问题或服务商 outage？

4. Check webhook health before diagnosing delivery

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

A drop in dashboard activity or customer-side events can be a webhook ingestion problem, not a delivery problem. Confirm webhook existence, active status, event subscriptions, recent event history, and test delivery. Rotate secrets only when the user explicitly asks or when a credential compromise is suspected, because rotation immediately invalidates the old secret.

Example. If Sent status shows

DELIVERED

but the customer database shows “no delivery callbacks,” inspect

/v3/webhooks/{id}/events

and the customer’s endpoint logs. If Sent has events but the endpoint returned failures, the fix is webhook handling, not campaign routing.

控制台活动或客户侧事件减少可能是Webhook接收问题，而非投递问题。确认Webhook的存在性、活跃状态、事件订阅情况、近期事件历史及测试投递结果。仅当用户明确要求或怀疑凭证泄露时才轮换密钥，因为轮换会立即使旧密钥失效。

示例：如果Sent状态显示

DELIVERED

但客户数据库显示“无投递回调”，则检查

/v3/webhooks/{id}/events

及客户端点日志。如果Sent有事件记录但端点返回失败，则修复方向是Webhook处理逻辑，而非营销活动路由。

5. Split by channel before naming a root cause

5. 拆分渠道后再确定根因

SMS, WhatsApp, and RCS fail differently. Do not average them together unless the user explicitly asked for a blended KPI. Compare each channel’s funnel and then compare the aggregate.

Channel	First cuts	Typical next evidence
SMS	Country, sender/profile, 10DLC campaign, opt-out, carrier family	Compliance status, brand/campaign readiness, opt-out logs, throughput patterns.
WhatsApp	Template, language, category, recipient country, quality/tier symptoms	Template status, read receipts, conversation window, Meta-side errors if present.
RCS	Agent readiness, fallback behavior, capability gaps, rich content rendering	Sent RCS setup status, fallback SMS results, capability/error details if present.

SMS、WhatsApp和RCS的失败模式不同。除非用户明确要求混合KPI，否则不要将它们的指标平均计算。先对比各渠道的漏斗数据，再对比汇总数据。

渠道	初步拆分维度	典型后续验证证据
SMS	国家、发件人/资料、10DLC营销活动、退订情况、运营商体系	合规状态、品牌/营销活动就绪度、退订日志、吞吐量模式。
WhatsApp	模板、语言、分类、收件人国家、质量/等级症状	模板状态、已读回执、会话窗口、Meta侧错误（若存在）。
RCS	Agent就绪状态、Fallback行为、能力缺口、富内容渲染情况	Sent RCS配置状态、Fallback SMS结果、能力/错误详情（若存在）。

6. Quantify impact before recommending fixes

6. 量化影响后再推荐修复方案

Report raw counts and rates together. A 40% failure rate over 15 messages is a different decision than a 4% failure rate over 150,000 messages. Include exclusions such as pending messages, test traffic, sandbox sends, retries, and duplicate channel fan-out.

A practical analysis table should include: sent count, latest status distribution, failure count, failure-rate delta versus baseline, top exact error strings/codes, first observed timestamp, affected templates, affected countries, and affected profiles.

同时报告原始计数和比率。15条消息中40%的失败率与150,000条消息中4%的失败率对应不同的决策。需排除待处理消息、测试流量、沙箱发送、重试及重复渠道分发等情况。

实用的分析表格应包含：发送数量、最新状态分布、失败数量、失败率与基准值的差值、主要错误字符串/代码、首次观测时间戳、受影响模板、受影响国家及受影响资料。

7. Convert the diagnosis into the next action

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

End with one primary diagnosis, one confidence level, and the next verification step. Avoid long lists of generic fixes. Tie every recommendation to observed evidence.

Example. “The largest leak is after

ROUTED

for SMS traffic on profile

support-us

, starting at 14:10 UTC. WhatsApp and RCS cohorts are stable. The affected traffic uses the same order-update template and a US A2P route. Verify the Sent brand/campaign status and opt-out handling next; if compliant, escalate the exact message IDs and activity timestamps.”

最终给出一个核心诊断结论、一个置信度级别及下一步验证步骤。避免列出冗长的通用修复清单。所有建议都必须与观测到的证据关联。

示例：“最大的流失点出现在

ROUTED

之后，涉及资料

support-us

的SMS流量，始于UTC时间14:10。WhatsApp和RCS群组状态稳定。受影响流量使用相同的订单更新模板及美国A2P路由。下一步请验证Sent品牌/营销活动状态及退订处理逻辑；若合规，则提交具体消息ID及活动时间线进行升级处理。”

Common rationalizations to avoid

需避免的常见误区

Do not infer delivery failure from missing customer-side webhooks until Sent webhook event history and endpoint responses are checked. Webhook ingestion failures often mimic delivery failures.

Do not label a campaign “carrier filtered” from a small sample without comparing baseline, country, sender/profile, and template. Filtering is a conclusion after cohort isolation, not a synonym for “failed.”

Do not treat

READ

as a universal stage. Sent documents read receipts for WhatsApp and RCS; SMS generally does not support read receipts.

Do not collapse RCS fallback into SMS delivery. For

channel: ["rcs", "sms"]

, count RCS attempts and SMS attempts separately, then report recipient-level success if the user asks for it.

在未检查Sent Webhook事件历史及端点响应前，不要从客户侧Webhook缺失推断投递失败。Webhook接收失败常与投递失败表现相似。

在未对比基准值、国家、发件人/资料及模板的情况下，不要仅凭小样本就将营销活动标记为“运营商过滤”。过滤是群组定位后的结论，而非“失败”的同义词。

不要将

READ

视为通用阶段。Sent仅为WhatsApp和RCS记录已读回执；SMS通常不支持已读回执。

不要将RCS Fallback合并到SMS投递中。对于

channel: ["rcs", "sms"]

，需分别统计RCS尝试和SMS尝试次数，仅当用户要求时才报告收件人级别的成功情况。

Verification checklist

验证清单

The analysis uses Sent
```
message_id
```
values as the primary unit.
The cohort is pinned by time window, profile/sender identity, template, channel, and recipient segment.
Status math uses the latest known status per Sent message ID.
Pending or in-flight messages are either excluded or reported separately.
Webhook configuration, event history, and endpoint test results are checked when the symptom is missing callbacks.
Channel-specific failures are split before aggregate rates are reported.
Provider or carrier codes are quoted exactly as observed and not invented from a lookup table.
The final recommendation names one next verification step and the evidence that justifies it.

分析以Sent
```
message_id
```
作为核心单元。
群组已按时间窗口、资料/发件人身份、模板、渠道及收件人群体定位。
状态计算使用每个Sent消息ID的最新已知状态。
待处理或在途消息已被排除或单独报告。
当症状为回调缺失时，已检查Webhook配置、事件历史及端点测试结果。
在报告汇总比率前已拆分渠道特定失败情况。
服务商或运营商代码完全按观测结果引用，未从查找表中杜撰。
最终建议明确了一个下一步验证步骤及支撑该步骤的证据。

Related skills

Bundled references and scripts

附带参考资料及脚本

File	Type	Purpose
`references/mdr-status-codes.md`	Lookup table	Normalize observed SMS, WhatsApp, and RCS provider errors without putting long code dictionaries in the skill body.
`references/performance-diagnosis-playbook.md`	Worked examples	Decision tree for which signal to investigate first, channel-specific diagnostic patterns, cross-skill handoff matrix, and escalation criteria.
`scripts/analyze_mdr_funnel.py`	Validation script	Reads an MDR export (CSV or JSON), prints per-stage counts and drop-off percentages, exits non-zero on anomalies. Run from the skill root: `python scripts/analyze_mdr_funnel.py path/to/mdr.csv` (use `--threshold N` to tune, default 20; pass `--show-errors` to also tally `ERR_*` codes parsed from FAILED message `description` fields).
`scripts/fixtures/good.json`	Fixture	Synthetic healthy-funnel MDR export.
`scripts/fixtures/bad.json`	Fixture	Synthetic MDR export with deliberate >50% SENT→DELIVERED drop.

文件	类型	用途
`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` 调整阈值，默认20；添加 `--show-errors` 可同时统计从FAILED消息 `description` 字段解析出的 `ERR_*` 代码）。
`scripts/fixtures/good.json`	测试数据	模拟健康漏斗的MDR导出文件。
`scripts/fixtures/bad.json`	测试数据	模拟SENT→DELIVERED流失率>50%的MDR导出文件。

Unverified claims to confirm or remove

待确认或移除的未验证声明

Any fixed cohort-size threshold such as “1,000 messages minimum” is an analyst heuristic, not a documented Sent API rule.
External provider identifiers such as carrier message IDs, WhatsApp
```
wamid
```
, and RCS message IDs are not in the v3 docs as join keys; use Sent
```
message_id
```
and treat provider IDs as escalation-only context.

任何固定群组大小阈值（如“最少1000条消息”）均为分析师经验法则，并非Sent API的文档化规则。
外部服务商标识符（如运营商消息ID、WhatsApp
```
wamid
```
及RCS消息ID）未在v3文档中列为关联键；请使用Sent
```
message_id
```
，并将服务商ID仅作为升级时的上下文信息。",