每次发送都会产生一份运营商投递回执。Bird 将这些回执转化为投递、失败和延迟指标，按国家/地区、运营商和发送者拆分，可在控制台中以及通过你可以在自己代码中查询的统计 API 查看。
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const code = generateOtp();
const { data, error } = await bird.sms.send({
from: "Bird",
to: "+15005550006",
text: `Your Bird verification code is ${code}. Reply STOP to opt out.`,
}).safe();
if (error) throw error;
console.log(data.id);
// → "sms_4kT01Lq2m..."Today at 2:14 PM
同一套 API 的报告侧。
无需新增任何埋点。
分析是 Bird SMS API 的报告侧。你已经通过它发送消息，并且每次状态变更都已收到投递 webhook；分析就是 Bird 替你保留计数，于是你无需先搭建一个数据仓库来存放事件，就能了解某次活动的投递情况。
投递回执告诉你什么。
来自运营商的测量，而非推断。
- 01
投递率。
在已提交的发送中运营商确认投递的占比。按国家/地区和按发送者跟踪，而不仅仅是一个掩盖了某条悄悄丢包路由的全站单一数字。
- 02
按运营商划分的失败原因。
失败的发送会携带运营商原因码，按目的地运营商（MCC/MNC）分组。一次飙升通常是某一家运营商拒绝了某一个发送者 ID，这是一个注册问题，而非平台故障。
- 03
分段与成本。
每条消息都会报告其编码和分段数，因此用量会汇总成你实际被计费的分段数。一次转为 Unicode 并使分段数翻倍的发送会在这里显现，而不是到账单上才发现。
- 04
投递延迟。
从提交到投递回执所用的时间，以分布而非平均值呈现。全球范围内约 95% 的消息在 2.5 秒内确认；尾部正是质量下降的路由暴露自己的地方。
在你自己的代码中查询这些数据。
统计 API 接收一个时间范围和一个 groupBy，并返回汇总后的计数。按国家/地区和运营商分组以找出表现不佳的路由，按发送者分组以查看运营商信任你的哪些 ID。同一套聚合支撑着控制台图表，因此你截图的数字与你可以按计划拉取的数字一致。
const { data, error } = await bird.sms.stats
.query({
from: "2026-06-01",
to: "2026-06-26",
groupBy: ["country", "carrier"],
metrics: ["sent", "delivered", "failed", "p95_latency_ms"],
})
.safe();
if (error) throw error;
console.log(data.rows[0]);
// → {
// country: "BR",
// carrier: "Vivo", // MCC/MNC 724/06
// sent: 48213,
// delivered: 47190,
// failed: 1023,
// p95_latency_ms: 2310,
// }拉取某一条消息的时间线。
聚合回答某次活动表现如何；一张支持工单问的是某一条短信。把单个消息 ID 传给事件端点，你就能按顺序得到它的完整生命周期——已排队、已发送、运营商投递回执或失败，每一步都带有时间戳，失败时还附带运营商自己的原因码。
const { data } = await bird.sms
.events("sms_4kT01Lq2m...")
.safe();
console.log(data.events);
// → [
// { type: "sms.queued", at: "2026-06-26T10:00:00.110Z" },
// { type: "sms.sent", at: "2026-06-26T10:00:00.640Z" },
// { type: "sms.delivered", at: "2026-06-26T10:00:02.300Z" },
// ]无论问题如何提出，都从同一批发送中切片。
每种拆分都读取自同一批投递回执；groupBy 只是改变了观察的视角。
| 维度 | 它告诉你什么 |
|---|---|
| 国家/地区 | 投递在哪里保持稳定，以及哪个目的地正在拖低全球投递率。 |
| 运营商（MCC/MNC） | 一个国家/地区内哪家运营商在拒绝流量，可细化到网络代码。 |
| 发送者 | 你的每个发送者 ID 或号码受信任的程度，因为声誉是按发送者计的。 |
| 时间桶 | 某项指标何时发生变动，于是一次下降能与一次部署、一次注册变更或一次故障对应起来。 |
在文档中深入了解。
基于 投递 webhook 构建你自己的存储，阅读 可投递性指南 了解失败码的含义，并将计数与 账单与用量 进行对账。