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 托管的发送号码以及您自行接入的号码 |
| 群组 | 您的业务号码管理的 WhatsApp 群组，包含参与者和邀请链接 |
可见性
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 事件；参见入站消息 webhooks。
部分收件人会要求您停止发送，回复 STOP 是最常见的方式：Bird 内置了关键词列表，因此无需任何配置即可在您的号码上生效。您也可以记录限定于单个业务账户的屏蔽，或记录覆盖整个工作区的退订。无论哪种方式，Bird 都会阻止后续向该地址发送消息。请参阅退订与关键词。
后续步骤
| 页面 | 涵盖内容 |
|---|---|
| 发送 WhatsApp 消息 | 发送 API：收件人、模板、组件、标签、异步模型 |
| 服务消息 | 九种内容形式、服务窗口以及通过 URL 发送媒体 |
| 接收 | 入站消息、获取媒体以及 whatsapp.received webhook |
| 模板 | 模板目录、类别与变量以及按 slug 发送 |
| WhatsApp 日志 | 入站和出站消息、内容、状态与事件时间线 |
| Events | 通过 API 查看消息时间线和回应历史 |
| Webhooks | 投递、入站消息、回应、退订和群组 webhooks |
| 群组 | 与多个客户的共享聊天、邀请链接和群组限制 |
| 发送到群组 | 群组寻址、所需条件及按参与者的回执 |
| 接收群组消息 | 哪个参与者发送了群组消息，以及如何回复 |
| 退订 | 关键词规则、收件人偏好设置和退订列表 |
| WhatsApp 指标 | 出站投递性能和入站消息量 |
| 请求速率限制 | 组织策略容量、响应请求头和 429 处理 |