WhatsApp 概述
Bird WhatsApp 使用与 Bird Email 和 Bird SMS 相同的平台和 API 密钥。根据 API 密钥调用对应的区域主机（https://us1.platform.bird.com 或 https://eu1.platform.bird.com）。WhatsApp 端点位于 /v1/whatsapp/… 下。
商业发起的发送使用预先审核通过的消息模板。可以从 Bird 的托管目录中发送，无需自有号码，消息将从 Bird 托管的发送方发出；也可以关联一个自有号码，并从该号码发送自己的模板。联系人可以向你的自有号码发送消息，Bird 会将这些入站消息与出站消息一起记录。
发送的工作方式
通过 POST /v1/whatsapp/messages 发送一条 WhatsApp 消息：一个收件人、一个模板，以及可选的标签和元数据。我们会验证请求并返回包含消息 ID 的 202 Accepted。计费和投递异步进行。API 没有批量端点，因此每条消息需发送一个请求。
三个核心概念贯穿整个 API：
- 发送与投递是两个独立阶段。 202 表示 Bird 已接受该消息。收件人的设备只有在消息经过 WhatsApp 到达最终投递结果后才会收到。已读回执以 read_at 时间戳和 whatsapp.read 事件的形式出现，不会改变消息状态。
- 每次商业发起的发送都使用模板。 提供模板 slug、可选的 language 以及变量值。服务消息（即自由格式的文本或媒体）只能在联系人自己发送消息后打开的 24 小时窗口内、且仅从工作区拥有的号码发送。参见发送 WhatsApp 消息。
- 类别和目的地决定发送方和价格。 每个模板属于 authentication、utility 或 marketing 类别。托管模板从对应类别的 Bird 号码发送，因此不包含 from 字段；其他发送均需指定自己的发送方。价格还取决于收件人所在国家/地区，消息分两步计费：Bird 处理发送时收取 Bird 的费用，消息投递后收取 Meta 的费用。参见费用与账单。
仪表板中的 WhatsApp 应用
在仪表板中，WhatsApp 是工作区的渠道应用之一。其页面包括：
| 页面 | 用途 |
|---|---|
| Messages | 入站和出站消息，包含每条消息的内容、事件和投递详情 |
| Metrics | 出站投递指标和入站消息量 |
| Templates | 可发送的模板（托管和自有）：名称、语言、类别和渲染预览 |
| Numbers | Bird 托管的发送号码，以及在功能推出到你的工作区后显示的自有号码 |
可见性
Bird 为每条消息记录时间线。出站时间线包括已接受、已发送、已投递、已读和失败事件。入站时间线记录 Bird 收到消息的时间。
- 读取时间线：GET /v1/whatsapp/messages/{message_id}/events 返回消息的事件。Messages 页面显示相同的时间线。参见 WhatsApp 事件。
- 订阅出站投递事件：将公开的 whatsapp.accepted、whatsapp.sent、whatsapp.delivered、whatsapp.read、whatsapp.failed 和 whatsapp.rejected 事件发送到 webhook 端点。
- 查看汇总指标：Metrics 页面有独立的 Outbound 和 Inbound 标签页。
接收
Bird 存储发送到工作区自有号码的入站消息，状态为 received。Bird 托管的号码不会为你的工作区接收消息。可在 Messages 页面或通过 GET /v1/whatsapp/messages?direction=inbound 查找消息。消息详情显示文本、支持的媒体、文档、位置以及 Bird 无法渲染的内容类型。接收到的媒体可用 30 天。
Metrics 页面上的 Inbound 标签页显示 Messages received 时间序列和 By phone number 分布。要在每条入站消息到达时立即处理，请改为订阅 whatsapp.received webhook 事件；参见 WhatsApp 事件。
部分收件人会要求你停止发送。将其记录为限定于单个商业账户的抑制，或作为覆盖整个工作区的个人级退订，Bird 都会阻止后续向该地址发送。参见退订。
后续步骤
| 页面 | 涵盖内容 |
|---|---|
| 发送 WhatsApp 消息 | 发送 API：收件人、模板、组件、标签、异步模型 |
| 服务消息 | 九种内容形式、服务窗口以及通过 URL 发送媒体 |
| 接收 | 入站消息、获取媒体以及 whatsapp.received webhook |
| 模板 | 模板目录、类别与变量以及按 slug 发送 |
| WhatsApp 日志 | 入站和出站消息、内容、状态与事件时间线 |
| 事件 | 消息时间线与公开的出站投递 webhook |
| 退订 | 账户级抑制、工作区级退订以及取消操作 |
| WhatsApp 指标 | 出站投递表现与入站消息量 |
| 请求速率限制 | 每个分组的基准速率（含 whatsapp_send）以及 429 处理 |