振铃组

振铃组会呼叫工作区中在浏览器电话里在线的成员。将某个号码或工作区默认路由指向一个振铃组后，来电会在控制台中呼叫该组的在线成员，直到其中一人接听。

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

开始之前

• 会上线的成员。 振铃组只呼叫在浏览器电话中在线的成员。接听来电介绍了如何上线以及哪些人可以上线。
• 管理 Voice 的权限。 查看振铃组需要 voice_management 的读取级别权限。创建、重命名、删除振铃组和更改成员，以及将号码路由到振铃组，需要写入级别权限。
• 使用 API 或 CLI 时： 需要一个 API 密钥，并具有该操作所需级别的 voice_management 权限范围。

默认组

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

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

创建振铃组

1. 打开 Voice > Ring groups，然后选择 New ring group。
2. 输入 Name，然后选择 Create ring group。
3. 在该组的 Members 中，选择 Add member，然后选择该组要振铃的每个用户。列表中显示可以访问该工作区的用户。

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

通过 API，先创建振铃组，再按用户 ID 添加每个成员。要查找用户 ID，请运行 bird members list，它需要读取级别的 members 权限范围。

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

group = client.voice.ring_groups.create(name="Support")
print(group.id, group.name)

group, err := client.Voice.RingGroups.Create(context.Background(), bird.VoiceRingGroupsCreateParams{
	Name: "Support",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(group.Id, group.Name)

$group = $bird->voice->ringGroups->create((new VoiceRingGroupCreate())->setName('Support'));
echo $group->getId(), ' ', $group->getName(), "\n";

bird voice ring-groups create --name Support

curl -X POST "https://{region}.platform.bird.com/v1/voice/ring-groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support"
  }'

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

member = client.voice.ring_groups.members.create("RING_GROUP_ID", user_id="USER_ID")
print(member.user_id)

member, err := client.Voice.RingGroups.Members.Create(context.Background(), "RING_GROUP_ID", bird.VoiceRingGroupsMembersCreateParams{
	UserID: "USER_ID",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(member.UserId)

$member = $bird->voice->ringGroups->members->create('RING_GROUP_ID', (new VoiceRingGroupMemberCreate())->setUserId('USER_ID'));
echo $member->getUserId(), "\n";

bird voice ring-groups members create <ring-group-id> \
  --user-id usr_01krdgeqcxet5s7t44vh8rt9mg

curl -X POST "https://{region}.platform.bird.com/v1/voice/ring-groups/{ring_group_id}/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_01krdgeqcxet5s7t44vh8rt9mg"
  }'

之后离开工作区的用户会一直留在列表中，直到你将其移除，但该组不会再振铃他们。要移除成员，请选择其旁边的 Remove，或通过 API 移除成员。被移除的成员从下一通来电起不再被振铃。

将来电路由到振铃组

当号码自身的路由，或它所遵循的工作区默认路由指定某个组时，该号码的来电会振铃该组。

• 单个号码：打开 Voice > Numbers，打开该号码，在 Inbound routing 下选择 Ring a ring group。选择组，然后选择 Save。
• 所有没有自身路由的号码：在 Numbers 页面上，在 Calls to numbers without their own route 旁选择 Change，选择 Ring a ring group 和组，然后保存。

通过 API，在更新号码时将路由设为 {"type": "ring_group", "ring_group_id": "<id>"}；如需设置默认路由，请在语音设置中进行。如果 ring_group_id 既不是默认组，也不是该工作区中的组，请求会被拒绝并返回 422。

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

curl -X PATCH "https://{region}.platform.bird.com/v1/voice/numbers/vnu_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "ring_group",
        "ring_group_id": "vrg_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  }'

bird voice settings update 对默认路由使用相同的 --route ring_group --ring-group-id 参数。接听来电介绍了其他路由，以及如何让号码恢复使用默认路由。

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

响铃组如何响铃

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

• 成员每次五人一批响铃，每批最多响 20 秒。当一批中的所有成员都拒接或无法接通时，下一批立即开始响铃。
• 总响铃时间达到 60 秒后停止响铃。
• 第一个选择 Accept 的成员接听来电，其他成员的响铃随即停止。
• 每个成员只在一台设备上响铃，即保持其在线状态的浏览器。

如果成员离线、处于 Busy 状态、正在通话，或因连续三次未接而处于 Not accepting calls 状态，则会被跳过。你的状态介绍了每种状态。

成员响铃期间，来电者听到回铃音。在成员接听之前，来电不会被应答，因此响铃时间不计费。如果 60 秒内无人接听，或没有可响铃的成员，直接路由到该响铃组的号码会拒绝来电。如需将无人接听的来电转到其他地方，请将号码路由到一个先呼叫该响铃组、再继续执行的序列。

在语音通话段 API中，来电者的通话段会在 answered_by 中注明接听的成员。在录音或转录中，参与方的 user_id 注明该方的成员。

删除响铃组

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

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

限制

默认组没有成员数量上限。超出上限的创建请求或成员添加请求会被拒绝并返回 422，消息中会注明所触及的上限。同时在线的用户数量是组织级别的上限，详见在线用户上限。

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

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

后续步骤