Ring groups

A ring group rings the people in your workspace who are online in the browser phone. Route a number, or your workspace default route, to a group, and an incoming call rings the group's online members in the dashboard until one of them answers.

Every workspace has a Default group that rings everyone online. Add your own groups to ring a smaller team, such as support or sales, and point each number at the group that should answer it.

Before you start

• Members who go online. A ring group rings only members who are online in the browser phone. Receive calls explains going online and who can.
• Permission to manage Voice. Viewing ring groups needs voice_management at read level. Creating, renaming, deleting and changing members, and routing a number to a group, need it at write level.
• For the API or CLI: an API key holding the voice_management scope at the level the operation needs.

The default group

The Default group is always first in the list. Its members are every user online in the workspace at the moment a call arrives, so you never add anyone to it. It cannot be renamed or deleted, and its members cannot be changed: a request to do so is refused with 409 and E21072.

Its ID is vrg_ followed by the suffix of your workspace ID, so it is the same in every read. Use it wherever a ring group ID is accepted.

Create a ring group

1. Open Voice > Ring groups and select New ring group.
2. Enter a Name and select Create ring group.
3. In the group's Members, select Add member and choose each user the group should ring. The list offers users who can access the workspace.

The Online column counts a group's members who are online and accepting calls. It includes members who are on a call, who are not rung until that call ends. A new group has no members, so it reads 0 until you add them.

Over the API, create the ring group, then add each member by user ID. To find user IDs, run bird members list, which needs the members scope at read level.

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"
  }'

A user who later leaves the workspace stays listed until you remove them, but the group never rings them. To remove a member, select Remove next to them, or remove the member over the API. A removed member stops being rung from the next call.

Route calls to a ring group

A number rings a group when its own route, or the workspace default route it follows, names that group.

• One number: open Voice > Numbers, open the number, and under Inbound routing choose Ring a ring group. Pick the group and select Save.
• Every number without its own route: on the Numbers page, next to Calls to numbers without their own route, select Change, choose Ring a ring group and the group, and save.

Over the API, set the route to {"type": "ring_group", "ring_group_id": "<id>"} when you update the number, or in the voice settings for the default route. A ring_group_id that is neither the default group nor a group in the workspace is refused with 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 takes the same --route ring_group --ring-group-id flags for the default route. Receiving calls covers the other routes and how to return a number to the default.

A sequence can ring a group too, from a dial step. The step's outcome then continues the sequence, which is where a voicemail or a forward after an unanswered group belongs.

How a ring group rings

When a call arrives for a group, Bird reads the group's members who can be rung at that moment and shuffles them into a random order:

• Members are rung five at a time, for up to 20 seconds per batch. When every member of a batch declines or cannot be reached, the next batch starts at once.
• Ringing stops after 60 seconds in total.
• The first member to select Accept takes the call, and the others stop ringing.
• A member rings on one device only: the browser that holds their online status.

A member is skipped when they are offline, Busy, already on a call, or Not accepting calls after three missed calls in a row. Your status explains each one.

The caller hears ringing while members ring, and the call is not answered until a member accepts, so ringing time is not billed. If nobody answers in 60 seconds, or nobody can be rung, a number routed straight to the group refuses the call. To send unanswered callers somewhere else, route the number to a sequence that rings the group and then continues.

Delete a ring group

Select the group on the Ring groups page and select Delete ring group. Calls already ringing its members are not affected.

A group that a number, the workspace default route or a published sequence still rings cannot be deleted: the request is refused with 409 and E21071. Point each of them at another route first, then delete the group.

Limits

The default group has no member limit. A create or an added member over a limit is refused with 422, with a message naming the limit. How many users can be online at once is an organization limit, described in Users online limit.

Manage ring groups from the API, CLI or MCP

The MCP server offers the same operations as voice_ring_groups_* tools, and its voice_numbers_update and voice_settings_update tools take a ring_group route. Each group read includes online_member_count, the same count as the Online column.

Next steps