Sign inGet Started

发送你的第一条 SMS

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

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

如果你还没有账户,可以通过自助注册在终端中使用 CLI 或 curl 创建账户,无需浏览器。如果你的代码调用位于 rest.messagebird.com 的 MessageBird API,该 API 及其访问密钥与本快速入门中的 API 相互独立。从 MessageBird 迁移说明了这些账户之间的关系,从 Bird Connectivity Platform 迁移 SMS列出了旧发送调用中每个字段的对应关系。

1. 创建 API 密钥

在控制面板中,前往 Platform tools > API keys,创建一个具有 sms:write 权限范围的密钥,该范围涵盖消息的发送和读取。仅具有该权限范围的密钥无法启用 SMS 目标国家/地区、更改 SMS 每日支出限额或充值:Agent 控制列出了对发送密钥的各项限制。密钥按区域划分,格式类似 bk_us1_... 或 bk_eu1_...。前缀中的区域标识告诉你应调用哪个 API 主机:https://us1.platform.bird.com 或 https://eu1.platform.bird.com。

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

在终端中,Bird CLI 中的 bird api-keys create 可创建相同的密钥。创建密钥需要 api_keys:write 权限范围,并且 CLI 登录只能为密钥授予其自身拥有的权限范围。此登录还会请求 sms_management:write,步骤 2 需要用到它。如果你是在终端中使用 bird auth create-org 创建的账户,请跳过登录这一行:注册时保存的凭据已具备这些权限范围,重新登录会将其替换为范围更窄的凭据。

代码示例
bird auth login --scope api_keys:write --scope sms:write --scope sms_management:write
bird api-keys create --name "SMS quickstart key" --scope sms:write

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

代码示例
export BIRD_API_KEY="bk_us1_..."

设置了 BIRD_API_KEY 时,CLI 会使用该密钥而不是你的登录凭据。此密钥无法更改 SMS 目标国家/地区,因此请在未设置该变量的 shell 中运行步骤 2 中的 CLI 命令。

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 服务器 的 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 使用你的登录凭据,设置了该变量时则使用 BIRD_API_KEY;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);

如果你的密钥以 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);

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 参考:完整的请求和响应结构。