每次发送都会产生一份运营商投递回执。Bird 将这些回执转化为投递、失败和延迟指标，按国家/地区、运营商和发送者拆分，可在控制台中以及通过你可以在自己代码中查询的统计 API 查看。
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.sms.send({
from: "Bird",
to: "+31612345678",
text: "Your order #4821 has shipped. Track it: bird.ly/t/4821x",
category: "transactional",
}).safe();
if (error) throw error;
console.log(data.id);
// → "sms_01m11jw130e7svjzv70kgqr38w"
同一套 API 的报告侧。
无需新增任何埋点。
分析是 Bird SMS API 的报告侧。你已经通过它发送消息，并且每次状态变更都已收到投递 webhook；分析就是 Bird 替你保留计数，于是你无需先搭建一个数据仓库来存放事件，就能了解某次活动的投递情况。
投递回执告诉你什么。
来自运营商的测量，而非推断。
- 01
投递率。
在已提交的发送中运营商确认投递的占比。按国家/地区和按发送者跟踪，而不仅仅是一个掩盖了某条悄悄丢包路由的全站单一数字。
- 02
按运营商划分的失败原因。
失败的发送会携带运营商原因码，按目的地运营商（MCC/MNC）分组。一次飙升通常是某一家运营商拒绝了某一个发送者 ID，这是一个注册问题，而非平台故障。
- 03
分段与成本。
每条消息都会报告其编码和分段数，因此用量会汇总成你实际被计费的分段数。一次转为 Unicode 并使分段数翻倍的发送会在这里显现，而不是到账单上才发现。
- 04
投递延迟。
从提交到投递回执所用的时间，以分布而非平均值呈现。全球范围内约 95% 的消息在 2.5 秒内确认；尾部正是质量下降的路由暴露自己的地方。
在你自己的代码中查询这些数据。
统计 API 接受一个时间范围，返回汇总计数，每个维度对应一个端点：按运营商查找表现不佳的路由，按发送方查看运营商信任您的哪些发送者，还可按国家、类别、状态、错误代码或标签筛选。每行携带各自的维度，因此交叉两个维度需要两次调用。仪表板图表使用相同的聚合逻辑，所以您截图中的数字与定时拉取的数字完全一致。
// One endpoint per dimension, and one dimension per row: "by country and
// carrier" is two calls, not one grouped query.
const { data: byCarrier, error } = await bird.sms.stats
.byCarrier({ from: "2026-06-01", to: "2026-06-26" })
.safe();
if (error) throw error;
console.log(byCarrier.data[0]);
// → {
// carrier: "Vivo",
// delivery: {
// accepted: 14820,
// sent: 14810,
// delivered: 14720,
// undelivered: 60,
// failed: 25,
// delivery_rate: 0.9932,
// },
// latency: { processing: { p50_ms: 480, p95_ms: 2310, p99_ms: 4100 } },
// }
拉取某一条消息的时间线。
聚合数据回答的是一个活动的整体表现；而工单关注的是某一条短信。将单个消息 ID 传递给事件端点，即可按顺序获取其完整生命周期：排队、已发送、运营商送达回执或失败通知，每个节点都带有时间戳，失败时还附带运营商自身的原因代码。
const { data: events, error } = await bird.sms
.listEvents("sms_01m11jw130e7svjzv70kgqr38w")
.safe();
if (error) throw error;
console.log(events.data);
// → [
// { id: "evt_01m11jw196...", type: "sms.accepted", occurred_at: "2026-06-26T10:00:00.110Z" },
// { id: "evt_01m11jw19h...", type: "sms.sent", occurred_at: "2026-06-26T10:00:00.640Z" },
// { id: "evt_01m11jx4c2...", type: "sms.delivered", occurred_at: "2026-06-26T10:00:02.300Z" },
// ]
无论问题如何提出，都从同一批发送中切片。
每种细分都读取相同的送达回执，您调用的端点只是改变了查看的视角。
| 维度 | 它告诉你什么 |
|---|---|
| 国家/地区 | 投递在哪里保持稳定，以及哪个目的地正在拖低全球投递率。 |
| 运营商（MCC/MNC） | 一个国家/地区内哪家运营商在拒绝流量，可细化到网络代码。 |
| 发送者 | 你的每个发送者 ID 或号码受信任的程度，因为声誉是按发送者计的。 |
| 时间桶 | 某项指标何时发生变动，于是一次下降能与一次部署、一次注册变更或一次故障对应起来。 |
在文档中深入了解。
基于 投递 webhook 构建你自己的存储，阅读 可投递性指南 了解失败码的含义，并将计数与 账单与用量 进行对账。
付诸实践。
继续查阅此主题的文档、指南和示例。资源为英文。