WhatsApp API 常见问题

安装 SDK，获取 API 密钥，然后使用预审批模板调用发送端点即可。Bird 提供托管发送号码，因此在首次发送前无需进行号码配置。

一个发送端点，支持模板或自由格式内容、预审批模板目录、通过 API 和 webhooks 获取送达及已读回执事件、每条消息的事件时间线、入站消息和媒体、汇总投递指标，以及 Bird 托管的发送号码用于首次发送。与 Bird Email 和 SMS 使用相同的 API 密钥和区域主机。

表示 Bird 已接受您的消息并将异步投递。202 不是送达确认。送达、已读回执和失败会在之后以事件形式通过轮询或 Webhook 返回。

两者都支持。模板可以在任何时间触达任何人，因此它是发起对话的唯一方式。自由格式内容只能在联系人自己发送消息所打开的 24 小时客服窗口内触达该联系人，且只能从您工作区拥有的号码发送。Bird 不会为您跟踪该窗口，因此在窗口外发送的自由格式消息会被接受，但随后会以 service_window_expired 失败。

是的。联系人的消息会通过 whatsapp.received webhook 送达，显示在仪表板的 WhatsApp 日志中，并计入指标页面的入站标签。入站消息仅通过您自己的号码接收：Bird 托管号码在多个工作区间共享，因此发送到该号码的消息不会记录到您的工作区。

按消息计费，基于模板类别（验证、实用或营销）和收件人所在国家/地区。费用在 Bird 接受消息时产生，而非收件人阅读时。

当您的企业位于收件人所在国家/地区之外并发送身份验证模板时，Meta 会收取更高的单条消息费率。当您在滚动 30 天内向某一国家/地区的用户发送超过 750,000 条身份验证模板消息后，即符合此费率的适用条件。您在 Meta Business Manager 中设置的主要企业所在地决定了哪些发送适用该费率。

共享发送者的身份验证模板始终按国际费率收费，与您的数量阈值无关。所有 WhatsApp 号码目前均由 Bird 管理，因此当您的企业位于收件人所在国家/地区之外时，身份验证发送适用此费率。

仪表板中的用量和消费页面会显示您的 WhatsApp 费用。消息日志会在每条消息定价后显示其类别和费用。

没有。每条 WhatsApp 消息都是对 POST /v1/whatsapp/messages 的单独 API 调用，包含一个收件人。要发送给多个收件人，请循环调用发送端点。

whatsapp_send 速率组适用于发送端点。每个响应都带有 IETF RateLimit 标头，包含剩余配额和重置时间，建议根据该标头调整发送节奏，而非使用硬编码数值。付费计划可提高基础速率。

是的，以自由格式内容的形式发送。发送端点支持图片、视频、音频、贴纸、文档和位置，以及文本。与所有自由格式发送一样，每次发送都需要一个已打开的 24 小时客服窗口和一个您工作区拥有的号码。模板参数本身仅支持文本。

一种通过 Meta 向 WhatsApp 注册的预审批消息结构。每个模板都有一个名称、一种或多种语言、一个类别（身份验证、实用或营销），以及在发送时填充的占位变量。Bird 提供了一套可直接发送的托管模板目录，您也可以在连接 WhatsApp Business Account 后创建自己的模板。

Meta 会审核并批准每个模板，无论是 Bird 提交的还是您自己提交的。一个模板可能整体处于活跃状态，但个别语言版本处于被拒绝或暂停状态，因此在使用某种语言发送之前，请检查该语言的状态。

身份验证（一次性密码和登录流程）、实用（订单更新、账户通知）和营销（促销和优惠）。类别决定了 Bird 选择哪个发送号码以及消息的定价方式。

发送时传入 components 数组，包含 body 和 button 参数。参数可以是命名的（通过键匹配，如 'name'）或位置的（通过索引匹配）。当模板变量顺序可能发生变化时，命名参数更安全。

是的，在仪表板的模板页面中，前提是您的工作区已连接自己的 WhatsApp Business Account。构建器目前支持单一语言的正文文本。暂不支持通过公共 API 创建模板，但发送端点支持您工作区可发送的任何模板，无论是托管模板还是您自己的模板。

不需要。Bird 提供托管发送号码。验证模板从专用号码发送，实用和营销模板共享一个通知号码。仪表板的号码页面列出了您工作区可用的号码。

是的，连接自有号码正是解锁以您自己品牌身份发送的关键：包括您自己的模板、在已打开的客服窗口内发送自由格式内容，以及接收入站消息。Bird 托管号码在多个工作区间共享，且仅支持托管模板，因此请将其视为零配置的首次发送途径，而非最终状态。

对于托管模板，由其类别决定：身份验证使用专用发送号码，而实用和营销共用一个通知号码。其他所有情况在 from 字段中指定自己的发送号码，该号码必须是您工作区拥有的号码，并且您创建的模板必须与该号码属于同一个 WhatsApp Business Account。

向 /v1/whatsapp/messages 发送 POST 请求，包含收件人的 E.164 格式电话号码、模板标识符以及模板变量的值。Bird 验证请求后返回 202 和消息 ID，并异步投递消息。

传入 Idempotency-Key 头部，重试请求将返回原始结果，而不会重复发送。如果未传入，重试将被视为新消息，收件人会收到重复内容。

可以。标签最多支持 20 个结构化标签，可在消息日志和指标中进行筛选和分组。元数据是任意 JSON（最大 2 KB），会在消息及其事件中返回，便于将发送记录与您自己的系统进行关联。

每次状态变更都会触发 webhook 事件：accepted、sent、delivered、read、failed 或 rejected。您也可以通过 API 轮询消息的事件时间线。delivered 状态表示 WhatsApp 已确认收件人的设备已接收该消息。

六个生命周期事件：whatsapp.accepted（Bird 已入队）、whatsapp.sent（已提交至 WhatsApp）、whatsapp.delivered（已送达收件人设备）、whatsapp.read（收件人已阅读）、whatsapp.failed（提交后被 WhatsApp 拒绝）和 whatsapp.rejected（提交前被 Bird 拒绝，不收费）。

不是。已读事件表示收件人打开了消息，但消息状态仍为已送达。已读会作为时间戳和 whatsapp.read 事件单独报告，不会触发状态变更。

rejected 表示 Bird 在提交给 WhatsApp 之前拒绝了该消息，因此不会收费。failed 表示 Bird 已提交但 WhatsApp 拒绝了投递。两者都包含一个错误对象，其中有错误码、描述以及适用时的 Meta 错误码。

两种方式：通过 GET /v1/whatsapp/messages/{id}/events 拉取特定消息的事件时间线，或订阅 Webhook 端点接收 whatsapp.* 事件类型的实时推送。仪表板的消息页面也会显示每条消息的事件时间线。

在 WhatsApp 仪表板应用的指标页面中。它显示您工作区所有发送的送达率、失败率、接受量和投递延迟（处理延迟和端到端延迟）。

按发送号码、按模板、按模板类别和按标签。整体看起来正常的失败率，往往是某个模板或某个标签导致了大部分错误。

两种：处理延迟（Bird 端，从接受到提交）和总延迟（端到端，从接受到收到送达回执）。两者均按 p50、p95 和 p99 报告。

汇总统计目前还没有。您可以通过 Webhook 事件或消息列表 API 自行构建聚合数据，消息列表 API 包含每条消息的状态和事件时间线。

WhatsApp 为发送者与收件人设备之间的消息提供端到端加密。您对 Bird 的 API 调用通过 HTTPS 进行，Bird 发送给您的 webhook 事件经过 HMAC 签名。

每个事件都经过 HMAC 签名。在处理负载之前，请使用您端点的密钥验证签名，并在需要时从仪表板轮换该密钥。

存储在您组织所在的区域，即 us1 或 eu1。您的 API 密钥前缀中包含区域信息（bk_us1_、bk_eu1_），SDK 和 CLI 会据此自动选择正确的端点，无需您手动配置。

仅限于您设定的权限范围。密钥包含一组权限范围，每个权限分为读取或写入，因此一个用于发送 WhatsApp 消息的密钥无法管理您的号码或读取其他渠道。密钥还支持 IP 白名单以及带有可配置宽限期的安全轮换。

认证和安全文档请访问 trust.bird.com。数据处理协议、隐私声明和可接受使用政策请访问 bird.com/legal。如需供应商调查问卷，请联系您的 Bird 客户团队处理。