Sign inGet Started
立即开始
指南
API 参考
SDK
CLI
知识库
更新日志

WhatsApp 指标

Bird 仪表板中的 Metrics 页面展示了您的 WhatsApp 渠道运行状况：有多少消息到达了收件人的设备、失败率是否在上升、以及整体速度如何。本指南逐一介绍该页面的内容、每个数字的含义，以及何时需要采取行动。

指标是工作区所有发送的汇总视图。要查看单条消息的生命周期（这个 号码是否收到了消息、何时收到），请参阅 WhatsApp 日志和事件。

阅读您的指标

Metrics 页面位于 Bird 仪表板的 WhatsApp → Metrics；拥有 WhatsApp 读取和 Analytics 读取权限的工作区成员可以查看。所有数字都遵循范围选择器（过去 24 小时、7 天、30 天或 90 天）。新事件在聚合和复制之后才会出现，因此最近的时段是临时数据。

出站指标使用每条消息的接受时间。今天到达的投递回执如果对应昨天接受的消息，则计入昨天，与该消息自身的 accepted 一起统计。因此，每个范围跟踪的是在该范围内接受的消息及其陆续到达的观测数据。最近几小时的 delivered 可能因回执尚未到达而低估。accepted 是投递率和失败率卡片的分母。

计数表示每个已观测事件的去重消息数，在大规模下可能是近似值。它们不是强制漏斗：已读回执可以在没有投递回执的情况下存在，缺失的观测可能导致阶段之间出现差距。群组统计也按消息计数而非收件人；第一个被观测到的参与者投递可能在所有群组成员收到消息之前就增加了投递计数。

Bird 仪表板中的 WhatsApp Metrics 页面：投递率、失败率和接受量摘要卡片位于按时间投递图表上方

摘要卡片

页面顶部的一排卡片是您的快速健康检查：

  • 投递率：已投递消息占已接受消息的比例。高于 95% 时卡片显示 Healthy。等于或低于该值时，说明某些消息未能到达设备：无效号码、客服窗口过期或模板问题。失败原因直方图（见失败率及其原因）会告诉您具体原因。
  • 失败率：已接受消息中以 failed 结束的比例。卡片以进度条显示您的比率与 5% 上限的对比；达到该上限时卡片切换为 Risk。持续的高失败率通常指向列表质量、客服窗口过期或 Meta 的速率限制。
  • 已接受：在该范围内已接受消息的原始计数，以及已提交到 WhatsApp 网络的数量（sent）。

95% 和 5% 的阈值是我们用来为卡片着色的护栏。它们有意设得保守；卡片显示 Healthy 仍有改进空间。

按时间的投递情况

投递图表在整个范围内绘制 已接受、已投递 和 失败 的消息量，以便您发现趋势和一次性峰值：一次失败的营销活动、一次出错的号码列表导入、一个开始被拒绝的模板。分桶粒度跟随范围（24 小时为按小时，更长窗口为按天）。

失败率及其原因

在 Metrics 页面的投递图表下方，失败率折线图绘制了整个范围内每个分桶的失败率，而失败率摘要卡片显示整个窗口的数值。一个直方图按归一化的错误代码对失败进行分组，按数量排名并显示每个代码在失败消息中的占比。WhatsApp 的失败原因是一个开放集合，因此直方图列出的是该范围内实际出现的代码，而非固定列表；某个代码的柱状条上升会直接引导您找到修复方向。

投递延迟

延迟表格在 p50、p95 和 p99 百分位报告三个阶段：

  • 处理：从消息被接受到成功提交给 WhatsApp 供应商。此处某个百分位偏慢，需要排查发送路径，包括供应商提交环节。
  • 投递：从提交到 WhatsApp 确认投递，这一段属于 WhatsApp 网络和收件人设备。
  • 总计：端到端，从消息被接受到 WhatsApp 确认投递至收件人设备。总计与处理之间的差值是 WhatsApp 网络和收件人设备的耗时，这部分我们无法控制。手机离线一小时会拉长总计延迟，但处理延迟不变。

使用 p95/p99 来捕捉慢尾：中位数正常但 p99 偏慢，通常指向某个模板或目的地拖慢了整体。延迟是整窗口数值；在该范围内无数据的阶段或百分位显示占位符。

细分

Breakdowns 面板将同一批投递数据按维度切分，以便您将问题定位到来源：

  • 按号码：每个发送业务号码的已接受、已投递和失败量及其投递率，便于并排比较不同发送方。
  • 按模板：按模板的相同拆分，找出拉低投递率的那个模板。
  • 按模板类别：跨 Meta 模板类别的相同拆分，该分类同时影响您的费用。
  • 按标签：您附加到发送上的标签，是最灵活的切分方式：为营销活动、模板或实验变体打标签，然后直接比较。
  • 按国家/地区：按目的地国家/地区的相同拆分，用于查看投递问题是跟随市场而非发送方或模板出现的。无法确定国家/地区的收件人（看起来像电话号码但不属于任何国家的号码，或免费电话等国际号段）被计入 ZZ，与 SMS 国家/地区细分使用的占位符相同。群组发送被排除在外，因为一个群组可能跨越多个国家/地区且没有单一目的地。在此细分功能上线之前的历史国家/地区覆盖可能不完整，包括有已投递或已读观测但缺少对应已接受计数的情况。聚合历史的留存时间长于 30 天的消息详情窗口；等待 30 天不会修复那些更早的队列。

每行还会获得一个派生状态（Healthy、Watching 或 Throttled），由其自身的投递率和失败率驱动，因此表现不佳的号码或类别无需逐列查看即可一目了然。每个标签页按范围排列排名靠前的行；当某个维度的不同值超出容纳范围时，面板会标注 "Top N of M"。

Bird 仪表板中 WhatsApp Metrics 页面的下半部分：投递延迟表格显示处理、投递和总计的 p50/p95/p99 及迷你折线图，下方是 Breakdowns 面板，按号码、模板、模板类别、标签和国家/地区分组展示投递情况

编程访问

该页面背后的聚合数据也是一个公开的 API。类型化方法以 bird.whatsapp.stats 的形式提供在 TypeScript、Python、PHP 和 Go SDK 中，bird CLI 以 bird whatsapp stats <verb> 的形式暴露它们，Agent 可通过 whatsapp_stats_* MCP tools 访问。完整的请求和响应模式请参阅 API 参考。

聚合与时间序列

GET /v1/whatsapp/stats/summary 返回该窗口的一条聚合行：生命周期计数（已接受、已发送、已投递、失败、已拒绝）及投递率和失败率，互动指标（read、read_rate），以及三个阶段的延迟百分位（p50、p95、p99）：处理、投递和总计。/daily 和 /hourly 返回相同的生命周期和已读计数，每个日历日或小时一行，各自带有延迟百分位；只有比率（delivery_rate、failure_rate、read_rate）是整窗口数值，请从 /summary 读取。三个端点均一次接受一个维度过滤器：template、category、tag 或 phone_number。其中 phone_number 限定为单个业务发送方（E.164 格式），而非在 GET /v1/whatsapp/messages 已弃用的 phone_number 参数上按联系人过滤。

已读率使用 read / delivered，而投递率和失败率使用 accepted。分母为零时返回 null，表示无法计算该比率。已读率不设 100% 上限，因此缺失的已投递观测可能导致已读率偏高；这是需要排查的观测缺口，不代表超过全部收件人读取了消息。

延迟百分位使用已记录的样本。缺少投递延迟样本不意味着延迟为零，并且在中间发送时间戳不可用时总延迟仍可存在。不要对来自不同分桶的已定型百分位求平均值。重放事件可能影响延迟分布，即使去重消息计数保持不变。

data_as_of 存在时表示聚合数据的新鲜度。它不证明所有供应商回调均已到达或计费已结算。null 的新鲜度值表示该响应中此信息不可用。

选择时间窗口

from 和 to 接受日历日或 RFC 3339 时刻，但各端点接受的形式有所不同：

端点边界最大窗口
/summary两端均为日历日，或两端均为 RFC 3339 时刻365 天，或时刻形式下 720 小时
/daily仅日历日365 天
/hourly仅 RFC 3339 时刻720 小时（30 天）

在 /summary 上，日期边界与时刻边界混用会返回 422。时刻边界在 /summary 和 /hourly（仅有这两个端点接受时刻）上向下取整到小时。将 timezone 设为 IANA 标识符可使用本地时区计算日和小时边界而非 UTC；设置后，时刻边界中的数字 UTC 偏移（如 +05:45）将被拒绝。向 /summary 添加 compare=previous_period 可获取前一个等长窗口及其对比变化。

细分

六个端点按单一维度对相同的投递数据进行排名，每个端点已是单维度因此不接受过滤器：按号码、按模板、按模板类别、按标签和按错误代码（仅失败消息，按归一化失败原因分组）。行按已接受量排名（错误代码按失败数排名），上限为 limit（默认 50，最大 200）。某维度无值的发送不会出现在该细分中：自由文本发送不会解析模板，未打标签的发送不会解析标签。一条带有多个标签的消息可以出现在多个标签行中，因此将这些行相加不等于工作区的唯一发送量。请将细分与其自身的历史数据进行对比。除错误代码行外，每行还带有自身的 latency 百分位。第六个端点按国家/地区按收件人的目的地市场对相同数据分组；无法解析国家/地区的收件人计入 ZZ，群组发送因一次发送可能跨越多个国家/地区而被排除。

接收的消息

/v1/whatsapp/stats/inbound/ 下的四个端点涵盖您的号码接收到的（而非发送的）消息：汇总、按天、按小时和按电话号码。每行仅包含一个 received 计数，跟随入站消息的发生时间。接收的消息没有出站投递生命周期可供进一步细分。它们在 SDK 中嵌套于 bird.whatsapp.stats.inbound 下，在 CLI 中嵌套于 bird whatsapp stats inbound <verb> 下。

逐条消息对账

统计端点回答的是聚合问题，不能替代逐条消息的查询。要确认某条消息的处理结果，请实时消费 webhook 事件，或翻页查看 GET /v1/whatsapp/messages 及每条消息的事件端点，其过滤器（状态、收件人、标签、时间窗口）可覆盖大多数对账场景。

后续步骤

相关资源

继续查看此主题的文档、指南和示例。

动手实践并获取实施简报