通过 WhatsApp API 与全球客户互动
将营销、服务和运营团队与客户连接到全球最受欢迎的即时通讯应用上。
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY!,
});
const msg = await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_delivery_update",
components: [{ type: "body", parameters: [
{ type: "text", name: "ref", text: "#4821" },
{ type: "text", name: "date", text: "Wednesday" },
] }],
},
});
console.log(msg.id, msg.status);
// → "wam_01krdgeqcxet5s7t44vh8rt9mg", "accepted"从 npm install 到首次发送仅需5分钟
用您已经在使用的语言发送 WhatsApp 消息。
支持所有主流运行时的 SDK。首次发送使用 Bird 托管模板（如 bird_delivery_update），该模板已获 Meta 批准并自动选择发送方，让您在自行创建模板之前就能看到真实消息送达。
const msg = await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_otp",
components: [{ type: "body", parameters: [{ type: "text", text: "123456" }] }],
},
});
console.log(msg.id, msg.status);我们在您和 Meta 之间处理的八件事。
WhatsApp 有准入门槛：需要审批通过的模板、已授权的接收者、经过验证的企业。这些门槛不会改变。您的服务商决定它们是在代码中显现，还是被藏在后台面板里。
- 01
Meta 官方商业解决方案提供商 (BSP)
自 API 推出以来与 Meta 直接合作。无转售中转，无第三方跳转。
- 02
模板管理
通过 CLI 或 MCP 工具查看模板目录和 Meta 对每种语言的审核结果。模板创建和提交在后台面板中完成。
- 03
支持所有语言的模板
一个标识，多种语言。发送时指定语言，或让模板自动匹配默认语言。
- 04
按钮和轮播卡片
支持链接、快捷回复、电话号码和复制代码按钮，以及 2-10 张卡片的轮播。
- 05
媒体与富内容
图片、视频、音频、贴纸、文档和位置，每种各占一个发送字段。
- 06
每次发送附带标签和元数据
标签可用于筛选和分析维度；元数据通过每个 webhook 回传。
- 07
入站消息 webhook
HMAC 签名事件，涵盖入站消息、送达回执和已读回执。
- 08
30 亿+ 用户，一个端点
超过三十亿 WhatsApp 月活用户，通过一个 bird.whatsapp.send 调用即可触达。
我们为何打造 WhatsApp
我们是最早的 WhatsApp BSP 之一。我们仍是少数与您一起交付代码的 BSP。
WhatsApp 有准入门槛。您需要审批通过的模板；需要在客服窗口期内才能发送非模板消息；还需要完成 Meta 企业验证。这些不会改变，也不会消失。变化的是您的 BSP 是让这些门槛更容易通过还是更难：通过在代码中暴露它们、通过可订阅的 webhook、通过明确指出问题所在的错误信息。我们选择了前者。
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY!,
});
const msg = await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_delivery_update",
components: [{ type: "body", parameters: [
{ type: "text", name: "ref", text: "#4821" },
{ type: "text", name: "date", text: "Wednesday" },
] }],
},
});
console.log(msg.id, msg.status);
// → "wam_01krdgeqcxet5s7t44vh8rt9mg", "accepted"每次状态变更都是一个 webhook。
HMAC 签名载荷，防重放，幂等。所有 Bird 渠道使用相同的信封格式：学会一个，就学会了全部。
{
"type": "whatsapp.read",
"timestamp": "2026-05-19T15:42:08.114Z",
"data": {
"whatsapp_id": "wam_01krdgeqcxet5s7t44vh8rt9mg",
"workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
"direction": "outbound",
"from": { "phone_number": "+15557654321" },
"to": { "phone_number": "+15551234567" },
"tags": [{ "name": "campaign", "value": "order-updates" }],
"metadata": { "order_id": "BRD-49217" }
}
}重试计划：5 秒、5 分钟、30 分钟、2 小时、5 小时，然后 10 小时重试两次。最后一次重试后投递永久失败，可通过后台面板或 API 进行重放恢复。
whatsapp.accepted已被 API 接受并排队等待发送至 Meta。whatsapp.sent已交付至 Meta Cloud API。whatsapp.deliveredMeta 报告消息已送达收件人设备。whatsapp.read收件人已打开消息（如果已读回执已开启）。whatsapp.rejected发送前即被拒绝，不产生费用：原因代码包含在返回数据中。whatsapp.failed永久失败：原因代码包含在载荷中。whatsapp.received来自 WhatsApp 用户的入站消息。
通过 SMS 触达同一客户只需同一调用，换一个字段即可。
相同的客户端、相同的认证、相同的错误封装、相同的 webhook 结构。不同的是载荷：WhatsApp 携带经 Meta 批准的模板，SMS 携带纯文本。标签和元数据在两者中通用，一套仪表盘即可同时覆盖。
await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_delivery_update",
language: "en",
components: [{ type: "body", parameters: [
{ type: "text", name: "ref", text: "BRD-49217" },
{ type: "text", name: "date", text: "10 Jul 2026" },
] }],
},
});Bird 托管模板：经 Meta 批准，支持 70 多种语言，自动选择发送方。占位符值作为组件传入。
SMS
await bird.sms.send({
from: "Bird",
to: "+15551234567",
text: `Your order BRD-49217 has shipped.`,
category: "transactional",
});同一动词，另一个渠道：自由格式文本加分类，无需模板审批。
每条消息一个价格，已包含 Meta 费用。
按用量计费。每个价格都把 Meta 的费用和我们的费用合为一个数字，并随目标国家/地区和消息类别变化。没有按席位收费，也没有需要年度承诺才能使用的功能。
Put it into practice.
Continue with the documentation, guides and examples for this topic. Resources are in English.