---
title: "振铃组"
description: "当来电呼入某个号码时，在浏览器电话中为您的团队振铃。振铃组可在控制台中管理，也可通过 API、CLI 和 MCP 管理。"
canonical: "https://bird.com/zh-sg/wendang/guides/voice/ring-groups"
---

# 振铃组

振铃组会为工作区中在[浏览器电话](/docs/guides/voice/phone)里在线的人员振铃。将某个号码或工作区默认路由指向一个振铃组后，来电会在控制台中为该组的在线成员振铃，直到其中一人接听。

每个工作区都有一个 **Default** 组，会为所有在线人员振铃。您可以添加自己的振铃组，为支持或销售等较小的团队振铃，并将每个号码指向应接听该号码的组。

## 开始之前

- **会上线的成员。** 振铃组只为在浏览器电话中在线的成员振铃。[接听来电](/docs/guides/voice/phone#receive-calls) 介绍了如何上线以及哪些人可以上线。
- **管理 Voice 的权限。** 查看振铃组需要读取级别的 `voice_management`。创建、重命名、删除振铃组、更改成员以及将号码路由到振铃组，需要写入级别的该权限。
- **使用 API 或 CLI 时：** 需要一个 API 密钥，且其 `voice_management` 范围达到操作所需的级别。

## 默认组

**Default** 组始终位于列表首位。其成员是来电到达时工作区中所有在线的用户，因此您无需向其中添加任何人。该组不能重命名或删除，其成员也不能更改：此类请求会被拒绝，并返回 `409` 和 `E21072`。

其 ID 由 `vrg_` 加上您工作区 ID 的后缀组成，因此每次读取时都相同。凡是接受振铃组 ID 的地方，都可以使用它。

## 创建振铃组

1. 打开 **Voice** > [**Ring groups**](https://bird.com/dashboard/w/voice/ring-groups)，然后选择 **New ring group**。
2. 输入 **Name**，然后选择 **Create ring group**。
3. 在该组的 **Members** 中，选择 **Add member**，然后逐一选择该组要振铃的用户。列表中列出可以访问该工作区的用户。

**Online** 列统计组内在线且接听来电的成员数。其中包括正在通话的成员，这些成员要等当前通话结束后才会振铃。新建的组没有成员，因此在您添加成员之前该列显示 0。

通过 API，先[创建振铃组](/docs/api/reference/create-voice-ring-group)，再按用户 ID [逐一添加成员](/docs/api/reference/create-voice-ring-group-member)。要查找用户 ID，请运行 [`bird members list`](/docs/cli/reference/members-list)，它需要读取级别的 `members` 权限范围。

**TypeScript**

```typescript
const group = await bird.voice.ringGroups.create({ name: "Support" });
console.log(group.id, group.name);
```

Examples: [TypeScript](/zh-sg/wendang/guides/voice/ring-groups.ts.md) · [Python](/zh-sg/wendang/guides/voice/ring-groups.py.md) · [Go](/zh-sg/wendang/guides/voice/ring-groups.go.md) · [PHP](/zh-sg/wendang/guides/voice/ring-groups.php.md) · [CLI](/zh-sg/wendang/guides/voice/ring-groups.cli.md) · [MCP](/zh-sg/wendang/guides/voice/ring-groups.mcp.md) · [cURL](/zh-sg/wendang/guides/voice/ring-groups.curl.md)

**TypeScript**

```typescript
const member = await bird.voice.ringGroups.members.create("RING_GROUP_ID", { user_id: "USER_ID" });
console.log(member.user_id);
```

Examples: [TypeScript](/zh-sg/wendang/guides/voice/ring-groups.ts.md) · [Python](/zh-sg/wendang/guides/voice/ring-groups.py.md) · [Go](/zh-sg/wendang/guides/voice/ring-groups.go.md) · [PHP](/zh-sg/wendang/guides/voice/ring-groups.php.md) · [CLI](/zh-sg/wendang/guides/voice/ring-groups.cli.md) · [MCP](/zh-sg/wendang/guides/voice/ring-groups.mcp.md) · [cURL](/zh-sg/wendang/guides/voice/ring-groups.curl.md)

用户日后离开工作区后，仍会保留在列表中，直到你将其移除，但该组不会再向其振铃。要移除成员，请选择其旁边的 **Remove**，或通过 API [移除该成员](/docs/api/reference/delete-voice-ring-group-member)。成员被移除后，从下一通来电起不再振铃。

## 将来电路由到振铃组

如果号码自身的路由，或其沿用的工作区默认路由指定了某个组，该号码的来电就会向该组振铃。

- **单个号码**：打开 **Voice** > [**Numbers**](https://bird.com/dashboard/w/voice/numbers)，打开该号码，在 **Inbound routing** 下选择 **Ring a ring group**。选择组，然后选择 **Save**。
- **所有没有自身路由的号码**：在 **Numbers** 页面上，在 **Calls to numbers without their own route** 旁选择 **Change**，选择 **Ring a ring group** 和要振铃的组，然后保存。

通过 API，在[更新号码](/docs/api/reference/update-voice-number)时将路由设为 `{"type": "ring_group", "ring_group_id": "<id>"}`；如需设置默认路由，则在[语音设置](/docs/api/reference/update-voice-settings)中进行。如果 `ring_group_id` 既不是默认组，也不是该工作区中的组，请求会被拒绝并返回 `422`。

**CLI**

```cli
bird voice numbers update vnu_01krdgeqcxet5s7t44vh8rt9mg \
  --route ring_group --ring-group-id vrg_01krdgeqcxet5s7t44vh8rt9mg
```

Examples: [CLI](/zh-sg/wendang/guides/voice/ring-groups.cli.md) · [cURL](/zh-sg/wendang/guides/voice/ring-groups.curl.md)

`bird voice settings update` 对默认路由接受相同的 `--route ring_group --ring-group-id` 标志。[接听来电](/docs/guides/voice/receiving-calls)介绍了其他路由，以及如何让号码恢复使用默认路由。

序列也可以通过拨号步骤呼叫振铃组。该步骤的结果随后会继续执行序列，因此在振铃组无人接听后转入语音信箱或转接，应在序列中设置。

## 振铃组如何振铃

当有来电呼叫某个振铃组时，Bird 会读取该组在此刻可振铃的成员，并将其打乱为随机顺序：

- 每次同时呼叫五名成员，每批最多振铃 20 秒。当一批中的每名成员都拒接或无法接通时，下一批会立即开始。
- 振铃总时长达到 60 秒后停止。
- 第一个选择 **Accept** 的成员接起来电，其他成员的振铃随即停止。
- 每名成员只在一台设备上振铃：即保持其在线状态的那个浏览器。

成员处于离线、**Busy**、正在通话中，或因连续三次未接来电而变为 **Not accepting calls** 时，会被跳过。[你的状态](/docs/guides/voice/phone#your-status)对每种状态都有说明。

成员振铃期间，来电者会听到回铃音。在成员接听之前，来电不会被应答，因此振铃时间不计费。如果 60 秒内无人接听，或没有可振铃的成员，直接路由到该振铃组的号码会拒绝这通来电。若要将无人接听的来电转到别处，请把号码路由到一个先呼叫该振铃组、再继续执行后续步骤的序列。

## 删除振铃组

在 **Ring groups** 页面选择该振铃组，然后选择 **Delete ring group**。正在呼叫其成员的来电不受影响。

如果某个号码、工作区默认路由或已发布的序列仍在呼叫某个响铃组，则无法删除该组：请求会被拒绝，并返回 `409` 和 `E21071`。请先将它们各自指向其他路由，再删除该组。

## 限制

| 限制项                                   | 值    |
| ---------------------------------------- | ----- |
| 每个工作区的振铃组数（**Default** 除外） | 50    |
| 每个振铃组的成员数                       | 200   |
| 同时振铃的成员数                         | 5     |
| 每通来电的振铃时长                       | 60 秒 |

默认组没有成员数量限制。创建组或添加成员时若超出限制，请求会被拒绝并返回 `422`，消息中会指明所超出的限制。可同时在线的用户数量属于组织级限制，详见[在线用户限制](/docs/guides/voice/phone#users-online-limit)。

## 通过 API、CLI 或 MCP 管理振铃组

| 任务           | API                                                            | CLI                                                                                             |
| -------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| 列出工作区的组 | [列出振铃组](/docs/api/reference/list-voice-ring-groups)       | [`bird voice ring-groups list`](/docs/cli/reference/voice-ring-groups-list)                     |
| 创建组         | [创建振铃组](/docs/api/reference/create-voice-ring-group)      | [`bird voice ring-groups create`](/docs/cli/reference/voice-ring-groups-create)                 |
| 重命名组       | [更新振铃组](/docs/api/reference/update-voice-ring-group)      | [`bird voice ring-groups update`](/docs/cli/reference/voice-ring-groups-update)                 |
| 删除组         | [删除振铃组](/docs/api/reference/delete-voice-ring-group)      | [`bird voice ring-groups delete`](/docs/cli/reference/voice-ring-groups-delete)                 |
| 列出组的成员   | [列出成员](/docs/api/reference/list-voice-ring-group-members)  | [`bird voice ring-groups members list`](/docs/cli/reference/voice-ring-groups-members-list)     |
| 添加成员       | [添加成员](/docs/api/reference/create-voice-ring-group-member) | [`bird voice ring-groups members create`](/docs/cli/reference/voice-ring-groups-members-create) |
| 移除成员       | [移除成员](/docs/api/reference/delete-voice-ring-group-member) | [`bird voice ring-groups members delete`](/docs/cli/reference/voice-ring-groups-members-delete) |

[MCP 服务器](/docs/ai/mcp-server)以 `voice_ring_groups_*` 工具的形式提供相同的操作，其中 `voice_numbers_update` 和 `voice_settings_update` 工具接受 `ring_group` 路由。每次读取振铃组都会返回 `online_member_count`，其计数与 **Online** 列相同。

## 后续步骤

| 页面                                           | 涵盖内容                                         |
| ---------------------------------------------- | ------------------------------------------------ |
| [电话](/docs/guides/voice/phone)               | 上线、你的状态，以及在浏览器中接听来电           |
| [接听来电](/docs/guides/voice/receiving-calls) | 号码可以使用的所有路由，以及如何解读被拒绝的来电 |
| [通话记录](/docs/guides/voice/call-log)        | 每次通话留下的记录，以及如何筛选和导出记录       |

## Related resources

- [What is a voice API?](/explained/voice/what-is-a-voice-api) (answer)
- [Voice](/voice-api) (product)
- [Voice overview](/docs/guides/voice/overview) (docs)

[Get an implementation brief](/learn/workspace?topic=voice)