发送您的第一条 WhatsApp 消息
使用 Bird WhatsApp 向您自己的手机发送一条 WhatsApp 消息，然后读取该消息以确认已投递。由企业发起的发送需要使用预先批准的模板。本快速入门从 Bird 的托管模板目录（例如 bird_delivery_update 或 bird_otp）发送，这些模板使用由 Bird 托管的共享 WhatsApp 发送方。您无需先连接 WhatsApp Business Account 或注册号码。
开始之前，请确保您组织的钱包有余额。WhatsApp 模板发送会从钱包扣费，如果余额不足以支付某次发送，Bird 会拒绝该发送并返回 402 WalletInsufficientBalance。有关充值，请参阅支付方式和钱包。
1. 创建 API 密钥
在控制台中，前往 Platform tools > API keys，创建一个具有 whatsapp:write 范围的密钥，该范围涵盖发送和读取消息。密钥按区域划分，格式类似 bk_us1_... 或 bk_eu1_...。前缀中的区域决定了您要调用哪个 API 主机：https://us1.platform.bird.com 或 https://eu1.platform.bird.com。
完整密钥仅在创建时显示一次。请将其复制到安全的位置，然后导出以供 cURL 示例使用：
export BIRD_API_KEY="bk_us1_..."2. 发送模板消息
将 Bird 托管目录中预先批准的 bird_delivery_update 模板发送到您的手机，或使用 bird_otp 发送一次性验证码。托管模板以 bird_ 开头，并从共享的 Bird 号码发送，因此您无需填写 from。请按照 SDK 快速入门为您的语言安装 Bird SDK。如果您使用 Bird CLI 选项卡，请先安装它（curl -fsSL https://cli.bird.com/install.sh | sh），并以写入权限完成身份验证（bird auth login --scope whatsapp:write）。
在 SDK 选项卡中，替换示例 API 密钥，并将 +15551234567 替换为 E.164 格式的您的手机号码。CLI 使用您的登录凭据，cURL 选项卡则使用 BIRD_API_KEY。
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });
const msg = await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_delivery_update",
parameters: { ref: "A1B2C3D4", date: "10 Jul 2026" },
},
});
console.log(msg.id, msg.status);from bird import APIError, Bird
with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
try:
message = client.whatsapp.send(
to="+15551234567",
template="bird_delivery_update",
parameters={"ref": "A1B2C3D4", "date": "10 Jul 2026"},
)
print(message.id, message.status)
except APIError as err:
print("send failed:", err)package main
import (
"context"
"fmt"
"log"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+15551234567",
Template: "bird_delivery_update",
Parameters: map[string]any{"ref": "A1B2C3D4", "date": "10 Jul 2026"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}<?php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');
$message = $bird->whatsapp->send(
to: '+15551234567',
template: 'bird_delivery_update',
parameters: ['ref' => 'A1B2C3D4', 'date' => '10 Jul 2026'],
);
echo $message->getId(), ' ', $message->getStatus(), "\n";bird whatsapp send \
--parameters '{"date":"10 Jul 2026","ref":"A1B2C3D4"}' \
--template bird_delivery_update \
--to +15551234567curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+15551234567",
"template": {
"slug": "bird_delivery_update",
"parameters": {
"ref": "A1B2C3D4",
"date": "10 Jul 2026"
}
}
}'如果你的密钥以 bk_eu1_ 开头，请改为调用 https://eu1.platform.bird.com。
API 返回 202 Accepted 以及创建的消息。消息的 id 以 wam_ 开头，status 为 accepted：表示 Bird 已接受该消息，并将异步投递。请保留 id，下一步会用到。
3. 检查投递状态
按 wam_ ID 获取该消息。将 WHATSAPP_MESSAGE_ID 替换为第 2 步中的 id，并将 SDK 标签页中的示例 API 密钥替换为你自己的密钥：
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });
const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");
console.log(msg.id, msg.status);from bird import APIError, Bird
with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
try:
message = client.whatsapp.get("WHATSAPP_MESSAGE_ID")
print(message.id, message.status)
except APIError as err:
print("read failed:", err)package main
import (
"context"
"fmt"
"log"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Get(context.Background(), "WHATSAPP_MESSAGE_ID")
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}<?php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');
$message = $bird->whatsapp->get('WHATSAPP_MESSAGE_ID');
echo $message->getId(), ' ', $message->getStatus(), "\n";bird whatsapp get WHATSAPP_MESSAGE_IDcurl https://us1.platform.bird.com/v1/whatsapp/messages/WHATSAPP_MESSAGE_ID \
-H "Authorization: Bearer $BIRD_API_KEY"status 字段表示消息当前所处的阶段：
accepted：Bird 已接收该消息，正准备将其交给 WhatsApp。sent：WhatsApp 已接受该消息，sent_at记录接受时间。delivered：WhatsApp 已确认消息投递到收件人的设备，delivered_at记录投递时间。收件人阅读消息后，系统会设置read_at，而status仍为delivered。failed或rejected：消息未能送达手机。last_error给出原因，消息状态事件列出了各错误代码。
持续轮询，直到状态不再是 accepted 或 sent；也可以订阅 WhatsApp webhook，接收每一次投递和已读状态变化（whatsapp.sent、whatsapp.delivered、whatsapp.read、whatsapp.failed）。由 Bird 管理的共享号码只能发送消息，不会将收到的回复转到你的工作区；如需接收回复，请连接你自己的号码。每条消息及其事件时间线也会显示在 Messages 页面上。
处理发送失败
402WalletInsufficientBalance：钱包余额不足以支付该消息。请为钱包充值，然后重新发送。403InsufficientScope：API 密钥缺少whatsapp权限范围。请编辑该密钥的权限范围，或创建一个具有whatsapp:write权限范围的密钥。422WhatsAppInvalidRecipient：to号码不是有效的 E.164 电话号码。请检查开头的+、国家代码和用户号码。
后续步骤
- 发送 WhatsApp 消息：在 24 小时客户服务窗口内发送模板消息和自由格式的服务消息。
- WhatsApp 模板：浏览托管目录（
bird_otp、bird_delivery_update等），或创建您自己的模板。 - 连接电话号码：使用您自己的 WhatsApp Business Account 和发送号码，让您的工作区也能接收用户回复。
- WhatsApp webhook：接收送达回执和已读回执（使用您自己连接的号码时，还可接收入站消息）。
- WhatsApp API 参考：完整的请求和响应结构。