发送你的第一条 SMS

使用 Bird SMS 向你自己的手机发送一条短信，然后读取该消息以确认是否已送达。本快速入门使用内置模板，模板提供文本、类别以及 Bird 根据目标地区选择的共享发送者。你不需要为此配置发送者 ID 或发送者注册。

开始之前，请确保你所在组织的钱包有余额。SMS 发送会从钱包扣款，余额不足时 Bird 会拒绝发送并返回 402 WalletInsufficientBalance。付款方式与钱包介绍了如何充值。

1. 创建 API 密钥

在控制面板中，前往 Platform tools > API keys，创建一个具有 sms:write 权限范围的密钥，该范围涵盖消息的发送和读取。密钥按区域划分，格式类似 bk_us1_... 或 bk_eu1_...。前缀中的区域标识告诉你应调用哪个 API 主机：https://us1.platform.bird.com 或 https://eu1.platform.bird.com。

Bird API Keys 页面，位于 Bird 控制面板中，列出密钥及其掩码前缀、权限范围和最后使用时间

完整密钥仅在创建时显示一次。将其复制到安全的地方，然后为 cURL 示例导出该密钥：

代码示例

export BIRD_API_KEY="bk_us1_..."

2. 启用目标国家/地区

Bird 仅向为你的工作区启用的国家/地区发送 SMS。向其他任何国家/地区发送将失败，返回 422 SMSDestinationNotEnabled。在 SMS > Destinations 下启用你手机号码所属的国家/地区。如果该国家/地区已显示为已启用，请继续执行步骤 3。

在终端中，Bird CLI 可完成相同的操作。传入该国家/地区的两位字母 ISO 代码，例如 US 代表美国。如果你的 CLI 登录缺少对 SMS 设置的访问权限，命令会打印用于添加权限的 bird auth login 命令：

代码示例

bird sms destinations update --destination US=true

连接到 MCP server 的 Agent 使用 sms_destinations_update 工具。公共 API 没有目的地相关的操作。更改最多需要一分钟才能生效。

3. 发送消息

向你的手机发送内置的 bird_otp_verification 模板。它会使用你传入的 code 值渲染为 "493021 is your verification code. Do not share it."。按照 SDK 快速入门为你的语言安装 Bird SDK。

在 SDK 标签页中，替换示例 API 密钥，并将 +14155550100 替换为你的手机号码（E.164 格式）。CLI 使用你的登录凭据，cURL 标签页使用 BIRD_API_KEY。

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.sms.send({
  to: "+14155550100",
  template: { slug: "bird_otp_verification", parameters: { code: "493021" } },
});

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.sms.send(
            to="+14155550100",
            template="bird_otp_verification",
            parameters={"code": "493021"},
        )
        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.Sms.Send(context.Background(), bird.SmsSendParams{
		To:         "+14155550100",
		Template:   "bird_otp_verification",
		Parameters: map[string]any{"code": "493021"},
	})
	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->sms->send(
    to: '+14155550100',
    template: 'bird_otp_verification',
    parameters: ['code' => '493021'],
);

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird sms send \
  --parameters '{"code":"493021"}' \
  --template bird_otp_verification \
  --to +14155550100

curl -X POST https://us1.platform.bird.com/v1/sms/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "slug": "bird_otp_verification",
      "parameters": { "code": "493021" }
    }
  }'

如果你的密钥以 bk_eu1_ 开头，请改为调用 https://eu1.platform.bird.com。

API 返回 202 Accepted 和消息内容。消息的 id 以 sms_ 开头，status 为 accepted：Bird 已接收消息并将异步投递。请保存 id，下一步会用到。消息将从 Bird 为您所在国家选择的共享发送方发出。

4. 检查投递状态

通过消息 ID 获取消息。发送后立即读取可能会返回 404，因为消息需要在 202 之后不久才会在读取端点上可见。稍等片刻后再次读取。将 SMS_MESSAGE_ID 替换为第 3 步中的 id，并将 SDK 标签页中的示例 API 密钥替换为你自己的。Go SDK 没有用于读取 SMS 消息的类型化方法，因此 Go 标签页通过 SDK 的 client.Get 请求方法调用 API 路径。

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.sms.get("SMS_MESSAGE_ID");

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.sms.get("SMS_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)
	}

	var msg bird.SMSMessage
	if err := client.Get(context.Background(), "/v1/sms/messages/SMS_MESSAGE_ID", &msg); 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->sms->get('SMS_MESSAGE_ID');

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird sms get SMS_MESSAGE_ID

curl https://us1.platform.bird.com/v1/sms/messages/SMS_MESSAGE_ID \
  -H "Authorization: Bearer $BIRD_API_KEY"

status 字段报告消息当前所处的阶段：

accepted：Bird 已收到消息，尚未将其移交给运营商。
sent：运营商已收到消息，sent_at 记录了 Bird 移交的时间。
delivered：运营商已确认送达，delivered_at 记录了送达时间。
undelivered、failed、rejected 或 expired：消息未到达手机。last_error 给出了原因，投递错误对每种原因做了说明。

轮询直到状态离开 accepted 和 sent，或订阅 SMS 事件通过 webhook 接收每次状态变更。每条消息也会显示在 Messages 页面及其事件时间线中。

修复发送失败

422 SMSDestinationNotEnabled：收件人所在国家/地区未在你的工作区中启用。按第 2 步启用，等待最多一分钟后重新发送。
402 WalletInsufficientBalance：钱包余额不足以支付该消息。充值钱包后重新发送。
403 InsufficientScope：API 密钥缺少 sms 权限范围。编辑该密钥的权限范围，或创建一个具有 sms:write 权限的密钥。

后续步骤

发送 SMS：使用自定义文本、发送方和类别发送消息，支持批量发送和安全重试。
SMS 发送方 ID：为每个国家/地区选择发送方，并在该国家/地区要求时完成注册。
SMS 模板：内置模板目录及其变量。
SMS 事件：事件类型以及每次状态变更的 webhook 投递。
SMS API 参考：完整的请求和响应结构。

继续查看此主题的文档、指南和示例。

获取实施简报