---
title: "发送你的第一条 SMS"
description: "创建 Bird API 密钥，启用目标国家/地区，向你的手机发送内置模板 SMS，然后查看其投递状态。"
canonical: "https://bird.com/zh-sg/wendang/get-started/send-your-first-sms"
---

# 发送你的第一条 SMS

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

开始之前，请确保你所在组织的钱包有余额。SMS 发送会从钱包扣款，余额不足时 Bird 会拒绝发送并返回 `402` `WalletInsufficientBalance`。[付款方式与钱包](/docs/knowledge-base/billing/payment-methods-wallet)介绍了如何充值。

## 1. 创建 API 密钥

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

![Bird API Keys 页面，位于 Bird 控制面板中，列出密钥及其掩码前缀、权限范围和最后使用时间](/images/docs/dashboard-api-keys.png)

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

```bash
export BIRD_API_KEY="bk_us1_..."
```

## 2. 启用目标国家/地区

Bird 仅向为你的工作区启用的国家/地区发送 SMS。向其他任何国家/地区发送将失败，返回 `422` `SMSDestinationNotEnabled`。在 [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations) 下启用你手机号码所属的国家/地区。如果该国家/地区已显示为已启用，请继续执行步骤 3。

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

```bash
bird sms destinations update --destination US=true
```

连接到 [MCP server](/docs/ai/mcp-server) 的 Agent 使用 `sms_destinations_update` 工具。公共 API 没有目的地相关的操作。更改最多需要一分钟才能生效。

## 3. 发送消息

向你的手机发送内置的 `bird_otp_verification` 模板。它会使用你传入的 `code` 值渲染为 **"493021 is your verification code. Do not share it."**。按照 [SDK 快速入门](/docs/get-started/quickstarts)为你的语言安装 Bird SDK。

在 SDK 标签页中，替换示例 API 密钥，并将 `+14155550100` 替换为你的手机号码（[E.164](https://en.wikipedia.org/wiki/E.164) 格式）。CLI 使用你的登录凭据，cURL 标签页使用 `BIRD_API_KEY`。

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/zh-sg/wendang/get-started/send-your-first-sms.ts.md) · [Python](/zh-sg/wendang/get-started/send-your-first-sms.py.md) · [Go](/zh-sg/wendang/get-started/send-your-first-sms.go.md) · [PHP](/zh-sg/wendang/get-started/send-your-first-sms.php.md) · [CLI](/zh-sg/wendang/get-started/send-your-first-sms.cli.md) · [MCP](/zh-sg/wendang/get-started/send-your-first-sms.mcp.md) · [cURL](/zh-sg/wendang/get-started/send-your-first-sms.curl.md)

如果你的密钥以 `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 路径。

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/zh-sg/wendang/get-started/send-your-first-sms.ts.md) · [Python](/zh-sg/wendang/get-started/send-your-first-sms.py.md) · [Go](/zh-sg/wendang/get-started/send-your-first-sms.go.md) · [PHP](/zh-sg/wendang/get-started/send-your-first-sms.php.md) · [CLI](/zh-sg/wendang/get-started/send-your-first-sms.cli.md) · [cURL](/zh-sg/wendang/get-started/send-your-first-sms.curl.md)

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

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

轮询直到状态离开 `accepted` 和 `sent`，或订阅 [SMS 事件](/docs/guides/sms/events) 通过 webhook 接收每次状态变更。每条消息也会显示在 [**Messages**](https://bird.com/dashboard/w/sms/messages) 页面及其事件时间线中。

## 修复发送失败

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

## 后续步骤

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

## Related resources

- [Sending your first SMS](/learn/sms/sending-your-first-sms) (video)
- [One-way and two-way SMS](/explained/sms/what-is-the-difference-between-one-way-and-two-way-sms) (answer)
- [Two-way SMS](/sms-api/features/two-way) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms-replies)