---
title: "Ring groups"
description: "Ring your team in the browser phone when a call arrives on a number, with ring groups you manage in the dashboard or over the API, CLI and MCP."
canonical: "https://bird.com/docs/guides/voice/ring-groups"
---

# Ring groups

A ring group rings the people in your workspace who are online in the [browser phone](/docs/guides/voice/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](/docs/guides/voice/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**](https://bird.com/dashboard/w/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](/docs/api/reference/create-voice-ring-group), then [add each member](/docs/api/reference/create-voice-ring-group-member) by user ID. To find user IDs, run [`bird members list`](/docs/cli/reference/members-list), which needs the `members` scope at read level.

**TypeScript**

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

Examples: [TypeScript](/docs/guides/voice/ring-groups.ts.md) · [Python](/docs/guides/voice/ring-groups.py.md) · [Go](/docs/guides/voice/ring-groups.go.md) · [PHP](/docs/guides/voice/ring-groups.php.md) · [CLI](/docs/guides/voice/ring-groups.cli.md) · [MCP](/docs/guides/voice/ring-groups.mcp.md) · [cURL](/docs/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](/docs/guides/voice/ring-groups.ts.md) · [Python](/docs/guides/voice/ring-groups.py.md) · [Go](/docs/guides/voice/ring-groups.go.md) · [PHP](/docs/guides/voice/ring-groups.php.md) · [CLI](/docs/guides/voice/ring-groups.cli.md) · [MCP](/docs/guides/voice/ring-groups.mcp.md) · [cURL](/docs/guides/voice/ring-groups.curl.md)

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](/docs/api/reference/delete-voice-ring-group-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**](https://bird.com/dashboard/w/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](/docs/api/reference/update-voice-number), or in the [voice settings](/docs/api/reference/update-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`.

**CLI**

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

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

`bird voice settings update` takes the same `--route ring_group --ring-group-id` flags for the default route. [Receiving calls](/docs/guides/voice/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](/docs/guides/voice/phone#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

| Limit                                          | Value |
| ---------------------------------------------- | ----- |
| Ring groups per workspace, besides **Default** | 50    |
| Members per ring group                         | 200   |
| Members rung at once                           | 5     |
| Ringing time for each call                     | 60 s  |

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](/docs/guides/voice/phone#users-online-limit).

## Manage ring groups from the API, CLI or MCP

| Task                        | API                                                                   | CLI                                                                                             |
| --------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| List the workspace's groups | [List ring groups](/docs/api/reference/list-voice-ring-groups)        | [`bird voice ring-groups list`](/docs/cli/reference/voice-ring-groups-list)                     |
| Create a group              | [Create a ring group](/docs/api/reference/create-voice-ring-group)    | [`bird voice ring-groups create`](/docs/cli/reference/voice-ring-groups-create)                 |
| Rename a group              | [Update a ring group](/docs/api/reference/update-voice-ring-group)    | [`bird voice ring-groups update`](/docs/cli/reference/voice-ring-groups-update)                 |
| Delete a group              | [Delete a ring group](/docs/api/reference/delete-voice-ring-group)    | [`bird voice ring-groups delete`](/docs/cli/reference/voice-ring-groups-delete)                 |
| List a group's members      | [List members](/docs/api/reference/list-voice-ring-group-members)     | [`bird voice ring-groups members list`](/docs/cli/reference/voice-ring-groups-members-list)     |
| Add a member                | [Add a member](/docs/api/reference/create-voice-ring-group-member)    | [`bird voice ring-groups members create`](/docs/cli/reference/voice-ring-groups-members-create) |
| Remove a member             | [Remove a member](/docs/api/reference/delete-voice-ring-group-member) | [`bird voice ring-groups members delete`](/docs/cli/reference/voice-ring-groups-members-delete) |

The [MCP server](/docs/ai/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

| Page                                                  | What it covers                                                 |
| ----------------------------------------------------- | -------------------------------------------------------------- |
| [Phone](/docs/guides/voice/phone)                     | Going online, your status, and answering a call in the browser |
| [Receiving calls](/docs/guides/voice/receiving-calls) | Every route a number can take, and how to read a refused call  |
| [Call log](/docs/guides/voice/call-log)               | The record each call leaves, and how to filter and export it   |

## 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)