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 是工作区的渠道应用之一。其页面包括：

可见性

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 发送模板消息或服务消息
• 接入自有号码：设置一个号码，以您的品牌发送和接收消息
• 模板：浏览模板并查找发送所需的变量
• 接收 WhatsApp 消息：读取入站消息并获取媒体
• Webhooks：订阅入站消息和投递状态更新