---
title: "管理你的电话号码"
description: "列出并查找分配到你工作区的号码，为其设置名称和自定义引用，查询语音记录，以及通过 API 取消或释放号码。"
canonical: "https://bird.com/zh-sg/wendang/guides/numbers/managing-numbers"
---

# 管理你的电话号码

号码分配到你的工作区后，号码 API 允许你列出持有的号码、通过任意标识查找某个号码、为其设置名称和自定义引用，以及在不再需要时取消或释放号码。读取操作需要一个具有 `numbers` 作用域读取级别的 API 密钥；更改、取消或释放号码需要写入级别。

控制台中的 [**Numbers**](https://bird.com/dashboard/w/numbers) 页面显示相同的号码。

## 列出你持有的所有号码

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) 返回当前分配到你工作区的号码，按最新优先排列，专用和共享号码均包含在内。每页默认显示 25 个号码，可通过 `limit` 设置为最多 100 个。

列表通过游标分页。将页面的 `next_cursor` 作为 `starting_after` 传回以读取下一页，当 `next_cursor` 为 `null` 时停止。SDK 会自动为你跟踪游标。以下示例将列表筛选为 `country_code: "GB"`；去掉筛选条件可遍历你持有的所有号码：

**TypeScript**

```typescript
for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}
```

Examples: [TypeScript](/zh-sg/wendang/guides/numbers/managing-numbers.ts.md) · [Python](/zh-sg/wendang/guides/numbers/managing-numbers.py.md) · [Go](/zh-sg/wendang/guides/numbers/managing-numbers.go.md) · [PHP](/zh-sg/wendang/guides/numbers/managing-numbers.php.md) · [MCP](/zh-sg/wendang/guides/numbers/managing-numbers.mcp.md) · [cURL](/zh-sg/wendang/guides/numbers/managing-numbers.curl.md)

使用与你密钥的 `bk_{region}_` 前缀匹配的区域主机：`https://us1.platform.bird.com` 或 `https://eu1.platform.bird.com`。

列表不包含总数。要统计你的号码数量，请遍历所有页面并计算条目数。传递 `include_total` 会被拒绝，返回 `422` 和 [`E01029`](/docs/api/errors/E01029)。

每个条目包含其 `status` 和 `ownership`。如果某个国家/地区不要求所有权证明文件，`ownership` 为 `null`。[号码概览](/docs/guides/numbers/overview#the-status-of-an-allocated-number)解释了每种状态的含义。要提交号码正在等待的证明文件，请参阅[提交号码的所有权证明文件](/docs/guides/numbers/ownership-paperwork)。

每个条目还包含 `pricing`，即你的组织为该号码支付的费用（不含税）：

- `recurring_price` 是你按 `recurring_period` 计的费率，以该号码的计费货币计价。该货币就是你的账单货币，除非该号码的订阅开始于你的账单货币变更之前；这类号码保留其订阅自身的货币，由 `currency_code` 标明。
- `intervals_per_charge` 表示一次续费收取多少个 `recurring_period`。税前周期费用为 `recurring_price` 乘以 `intervals_per_charge`。固定价格的号码覆盖整个周期，因此其 `intervals_per_charge` 为 `1`。

对于 `shared` 号码以及没有有效订阅的号码，`pricing` 为 `null`。当号码的订阅没有适用价格时，其价格为 `null`，且 `pricing.error: null`；请[联系销售](/contact-sales)为其定价。如果无法读取价格，`pricing.error` 包含 [`E14009`](/docs/api/errors/E14009)，价格为 `null`。使用指数退避重试 [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number)。号码仍可继续管理；不要为了刷新价格而重复已完成的更新或取消操作。

控制台和 API 使用相同的价格解析逻辑。固定价格保留其现有条款；否则显示的是当前费率，续费前可能会变动。它不会显示之前订单的收费金额。设置了 `releases_at` 的号码在释放前保留其 `pricing`，之后不再续费。

## 在列表中查找号码

列表筛选条件可以组合使用，因此国家或功能筛选条件会与其他条件同时生效。

`number` 可以查找单个号码，无论你的记录中使用哪种格式。`+31612345678` 和 `0031612345678` 会解析为同一个号码。类似 `0612345678` 这样的本地格式仅在 `country_code` 指定了国家时才能解析：

```bash
curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."
```

当你传入完整号码，或带有 `country_code` 的本地格式，且不附加其他筛选条件时，空的 `data` 数组表示该号码未分配到你的工作区，包括你已释放的号码。不带 `country_code` 的本地格式（例如单独使用 `0612345678`）也会返回空列表，因此不能以此证明该号码不属于你。

`search` 对号码、名称或引用进行部分匹配，不区分大小写。`reference` 返回具有完全匹配引用的号码，区分大小写：

```bash
curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."
```

`prefix` 返回以你给定数字开头的号码，这些数字的含义取决于 `country_code`：

- 带有 `country_code` 时，数字为本地号码，匹配位置紧跟在国际区号之后。`prefix=6&country_code=NL` 返回以 `+31 6` 开头的荷兰号码。
- 不带 `country_code` 时，数字从完整号码的开头开始匹配。单独使用 `prefix=6` 会返回国际区号以 6 开头的号码（例如澳大利亚的 `+61` 号码），因此不会找到你的荷兰手机号码。它也会匹配以这些数字开头的短码。

## 为号码命名并设置引用

每个号码包含两个由你自定义的标签。`name` 用于区分你的号码，例如 `Support line`。`reference` 用于存储你自己记录中的标识符，例如客户或门店 ID，且不要求唯一。两者均适用于专用和共享号码，最多 100 个字符。

使用 [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number) 设置它们。省略的字段保留当前值，发送为 `null` 的字段会被清除。前后空白会被自动去除。

**TypeScript**

```typescript
const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);
```

Examples: [TypeScript](/zh-sg/wendang/guides/numbers/managing-numbers.ts.md) · [Python](/zh-sg/wendang/guides/numbers/managing-numbers.py.md) · [Go](/zh-sg/wendang/guides/numbers/managing-numbers.go.md) · [PHP](/zh-sg/wendang/guides/numbers/managing-numbers.php.md) · [MCP](/zh-sg/wendang/guides/numbers/managing-numbers.mcp.md) · [cURL](/zh-sg/wendang/guides/numbers/managing-numbers.curl.md)

响应为 `200`，包含更新后的号码。要清除引用并保留名称，请将引用设为 `null`，不传名称字段：

```bash
curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'
```

要在购买号码时设置引用，请在 [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) 上传入 `reference`。如果订单需要等待运营商处理，引用会一直保留，直到号码分配完成，此后号码将一直携带该引用。

## 查找号码对应的语音记录

支持语音的号码有两个标识符。`GET /v1/numbers` 上的 `id` 以 `nda_` 开头（专用号码）或以 `nal_` 开头（共享号码），号码操作使用该标识符。语音操作（包括设置来电路由的操作）使用号码的语音记录，其 `id` 以 `vnu_` 开头。将 `nda_` 或 `nal_` ID 传给语音操作会被拒绝，返回 `422`。

要在两者之间转换，请通过电话号码搜索语音号码。这需要 `voice_management` 作用域的读取权限：

```bash
curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."
```

条目的 `id` 是 `vnu_` 标识符，其 `provider.number_id` 是同一号码的 `nda_` 或 `nal_` 标识符。[接听来电](/docs/guides/voice/receiving-calls)介绍了如何从这里开始路由号码。

语音记录有自己的 `name`。通过 `PATCH /v1/numbers/{number_id}` 为号码命名不会更改语音记录的名称，反之亦然。

## 释放号码

你可以通过两种方式归还专用号码：

- **在已付费周期结束时。** [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) 会停止号码续费。号码在当前计费周期结束前继续工作，届时自动释放。`202` 响应返回号码，其中 `releases_at` 设为该时间，再次请求返回相同的 `releases_at`。取消操作不可撤销。没有订阅的号码（例如免费分配给你的号码）会立即释放，响应为 `200`，号码的 `status` 设为 `released`。
- **立即释放。** [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) 立即释放号码，包括已计划取消的号码。当前周期的剩余时间不予退款。[购买和释放号码](/docs/guides/numbers/buying-numbers#release-a-number)展示了每种 SDK 中的调用方式。

当号码的续费付款逾期时，两个请求都返回 `409`，直到完成付款。

无论选择哪种释放方式，发送请求时都应附带 `Idempotency-Key`，以确保重试安全：相同的键会重放首次响应并附带 `Idempotency-Replay: true` 响应头，而对已释放号码发起的新请求会返回 `404` 和 [`E01008`](/docs/api/errors/E01008)。[幂等性](/docs/guides/idempotency)说明了键的保留时长。

在预定的取消生效之前，号码照常可读并携带 `releases_at`。释放之后：

- 你将无法再使用该号码，其订阅也不会续费。
- `GET /v1/numbers/{number_id}` 和该号码的语音记录返回 `404`，号码从 `GET /v1/numbers` 中移除。
- 该号码的订单保留在 [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders) 中，其 `number_id` 现在返回 `404`。
- 该号码需经过 30 天冷却期后才能重新出售，因此你无法立即回购同一号码。

## 后续步骤

- [接听来电](/docs/guides/voice/receiving-calls)将号码路由到 SIP 中继、转接或序列。
- [购买和释放号码](/docs/guides/numbers/buying-numbers)演示通过 API 完成购买的流程。
- [Numbers API 参考](/docs/api/reference/list-workspace-numbers)记录了每个操作和字段。

## Related resources

- [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer)
- [SMS numbers](/sms-api/features/numbers) (product)
- [Number types](/docs/guides/numbers/number-types) (docs)

[Get an implementation brief](/learn/workspace?topic=phone-numbers)