发送您的第一条 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",
components: [
{
type: "body",
parameters: [
{ type: "text", name: "ref", text: "A1B2C3D4" },
{ type: "text", name: "date", text: "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",
components=[
{
"type": "body",
"parameters": [
{"type": "text", "name": "ref", "text": "A1B2C3D4"},
{"type": "text", "name": "date", "text": "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",
Components: []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
{Type: "text", Name: bird.String("ref"), Text: bird.String("A1B2C3D4")},
{Type: "text", Name: bird.String("date"), Text: bird.String("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;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponent;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponentParameter;
$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');
$message = $bird->whatsapp->send(
to: '+15551234567',
template: 'bird_delivery_update',
components: [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('date')->setText('10 Jul 2026'),
]),
],
);
echo $message->getId(), ' ', $message->getStatus(), "\n";bird whatsapp send \
--components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"date","text":"10 Jul 2026","type":"text"}],"type":"body"}]' \
--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",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "name": "ref", "text": "A1B2C3D4" },
{ "type": "text", "name": "date", "text": "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 参考：完整的请求和响应结构。