---
title: "Grupos de toque"
description: "Faça o telefone do navegador tocar para sua equipe quando uma chamada chegar a um número, com grupos de toque que você gerencia no painel ou pela API, CLI e MCP."
canonical: "https://bird.com/pt-br/documentacao/guides/voice/ring-groups"
---

# Grupos de toque

Um grupo de toque chama as pessoas do seu espaço de trabalho que estão online no [telefone do navegador](/docs/guides/voice/phone). Direcione um número, ou a rota padrão do seu espaço de trabalho, para um grupo, e uma chamada recebida toca para os membros online do grupo no painel até que um deles atenda.

Todo espaço de trabalho tem um grupo **Default** que chama todos que estão online. Adicione seus próprios grupos para chamar uma equipe menor, como suporte ou vendas, e aponte cada número para o grupo que deve atendê-lo.

## Antes de começar

- **Membros que ficam online.** Um grupo de toque chama apenas os membros que estão online no telefone do navegador. [Receber chamadas](/docs/guides/voice/phone#receive-calls) explica como ficar online e quem pode fazer isso.
- **Permissão para gerenciar o Voice.** Para visualizar grupos de toque, é preciso ter `voice_management` no nível de leitura. Para criar, renomear, excluir e alterar membros, e para direcionar um número a um grupo, é preciso ter essa permissão no nível de escrita.
- **Para a API ou CLI:** uma chave API com o escopo `voice_management` no nível que a operação exige.

## O grupo padrão

O grupo **Default** é sempre o primeiro da lista. Os membros dele são todos os usuários online no espaço de trabalho no momento em que uma chamada chega, por isso você nunca adiciona ninguém a ele. Ele não pode ser renomeado nem excluído, e seus membros não podem ser alterados: uma solicitação para fazer isso é recusada com `409` e `E21072`.

O ID dele é `vrg_` seguido do sufixo do ID do seu espaço de trabalho, por isso é o mesmo em toda leitura. Use-o onde quer que um ID de grupo de toque seja aceito.

## Criar um ring group

1. Abra **Voice** > [**Ring groups**](https://bird.com/dashboard/w/voice/ring-groups) e selecione **New ring group**.
2. Insira um **Name** e selecione **Create ring group**.
3. Em **Members** do grupo, selecione **Add member** e escolha cada usuário que o grupo deve chamar. A lista oferece os usuários que têm acesso ao espaço de trabalho.

A coluna **Online** conta os membros do grupo que estão online e aceitando chamadas. Ela inclui os membros que estão em uma chamada, que só são chamados quando essa chamada termina. Um grupo novo não tem membros, então mostra 0 até você adicioná-los.

Pela API, [crie o ring group](/docs/api/reference/create-voice-ring-group) e depois [adicione cada membro](/docs/api/reference/create-voice-ring-group-member) pelo ID de usuário. Para encontrar os IDs de usuário, execute [`bird members list`](/docs/cli/reference/members-list), que exige o escopo `members` no nível de leitura.

**TypeScript**

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

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

Um usuário que sai do espaço de trabalho depois continua na lista até você removê-lo, mas o grupo nunca o chama. Para remover um membro, selecione **Remove** ao lado dele ou [remova o membro](/docs/api/reference/delete-voice-ring-group-member) pela API. Um membro removido deixa de ser chamado a partir da próxima chamada.

## Encaminhar chamadas para um ring group

Um número chama um grupo quando a própria rota dele, ou a rota padrão do espaço de trabalho que ele segue, indica esse grupo.

- **Um número:** abra **Voice** > [**Numbers**](https://bird.com/dashboard/w/voice/numbers), abra o número e, em **Inbound routing**, escolha **Ring a ring group**. Escolha o grupo e selecione **Save**.
- **Todos os números sem rota própria:** na página **Numbers**, ao lado de **Calls to numbers without their own route**, selecione **Change**, escolha **Ring a ring group** e o grupo, e salve.

Pela API, defina a rota como `{"type": "ring_group", "ring_group_id": "<id>"}` ao [atualizar o número](/docs/api/reference/update-voice-number) ou, para a rota padrão, nas [configurações de voz](/docs/api/reference/update-voice-settings). Um `ring_group_id` que não seja o grupo padrão nem um grupo do espaço de trabalho é recusado com `422`.

**CLI**

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

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

`bird voice settings update` aceita as mesmas flags `--route ring_group --ring-group-id` para a rota padrão. [Receber chamadas](/docs/guides/voice/receiving-calls) descreve as outras rotas e como fazer um número voltar à rota padrão.

Uma sequência também pode tocar um grupo, a partir de uma etapa de discagem. O resultado da etapa dá continuidade à sequência, e é ali que entra um correio de voz ou um encaminhamento quando ninguém do grupo atende.

## Como um grupo de toque toca

Quando chega uma chamada para um grupo, Bird lê os membros do grupo que podem ser chamados naquele momento e os embaralha em ordem aleatória:

- Os membros são chamados de cinco em cinco, por até 20 segundos por lote. Quando todos os membros de um lote recusam ou não podem ser alcançados, o próximo lote começa imediatamente.
- O toque para após 60 segundos no total.
- O primeiro membro a selecionar **Accept** atende a chamada, e o toque para nos demais.
- Cada membro recebe o toque em um único dispositivo: o navegador que mantém seu status online.

Um membro é ignorado quando está offline, em **Busy**, já está em uma chamada ou em **Not accepting calls** após três chamadas perdidas seguidas. [Seu status](/docs/guides/voice/phone#your-status) explica cada caso.

Quem liga ouve o toque enquanto os membros são chamados, e a chamada só é atendida quando um membro aceita, por isso o tempo de toque não é cobrado. Se ninguém atender em 60 segundos, ou se ninguém puder ser chamado, um número roteado diretamente para o grupo recusa a chamada. Para enviar as chamadas não atendidas para outro destino, roteie o número para uma sequência que toque o grupo e depois continue.

## Excluir um grupo de toque

Selecione o grupo na página **Ring groups** e selecione **Delete ring group**. As chamadas que já estão tocando para os membros não são afetadas.

Não é possível excluir um grupo que ainda é tocado por um número, pela rota padrão do espaço de trabalho ou por uma sequência publicada: a solicitação é recusada com `409` e `E21071`. Primeiro aponte cada um deles para outra rota e depois exclua o grupo.

## Limites

| Limite                                                      | Valor |
| ----------------------------------------------------------- | ----- |
| Grupos de toque por espaço de trabalho, além do **Default** | 50    |
| Membros por grupo de toque                                  | 200   |
| Membros chamados ao mesmo tempo                             | 5     |
| Tempo de toque por chamada                                  | 60 s  |

O grupo padrão não tem limite de membros. Uma criação ou um membro adicionado que ultrapasse um limite é recusado com `422`, com uma mensagem que indica o limite. Quantos usuários podem ficar online ao mesmo tempo é um limite da organização, descrito em [Limite de usuários online](/docs/guides/voice/phone#users-online-limit).

## Gerencie grupos de toque pela API, pela CLI ou pelo MCP

| Tarefa                                 | API                                                                        | CLI                                                                                             |
| -------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Listar os grupos do espaço de trabalho | [Listar grupos de toque](/docs/api/reference/list-voice-ring-groups)       | [`bird voice ring-groups list`](/docs/cli/reference/voice-ring-groups-list)                     |
| Criar um grupo                         | [Criar um grupo de toque](/docs/api/reference/create-voice-ring-group)     | [`bird voice ring-groups create`](/docs/cli/reference/voice-ring-groups-create)                 |
| Renomear um grupo                      | [Atualizar um grupo de toque](/docs/api/reference/update-voice-ring-group) | [`bird voice ring-groups update`](/docs/cli/reference/voice-ring-groups-update)                 |
| Excluir um grupo                       | [Excluir um grupo de toque](/docs/api/reference/delete-voice-ring-group)   | [`bird voice ring-groups delete`](/docs/cli/reference/voice-ring-groups-delete)                 |
| Listar os membros de um grupo          | [Listar membros](/docs/api/reference/list-voice-ring-group-members)        | [`bird voice ring-groups members list`](/docs/cli/reference/voice-ring-groups-members-list)     |
| Adicionar um membro                    | [Adicionar um membro](/docs/api/reference/create-voice-ring-group-member)  | [`bird voice ring-groups members create`](/docs/cli/reference/voice-ring-groups-members-create) |
| Remover um membro                      | [Remover um membro](/docs/api/reference/delete-voice-ring-group-member)    | [`bird voice ring-groups members delete`](/docs/cli/reference/voice-ring-groups-members-delete) |

O [servidor MCP](/docs/ai/mcp-server) oferece as mesmas operações como ferramentas `voice_ring_groups_*`, e as ferramentas `voice_numbers_update` e `voice_settings_update` aceitam uma rota `ring_group`. Cada leitura de grupo inclui `online_member_count`, a mesma contagem da coluna **Online**.

## Próximos passos

| Página                                                 | O que aborda                                                                     |
| ------------------------------------------------------ | -------------------------------------------------------------------------------- |
| [Telefone](/docs/guides/voice/phone)                   | Como ficar online, seu status e como atender uma chamada no navegador            |
| [Receber chamadas](/docs/guides/voice/receiving-calls) | Todas as rotas que um número pode seguir e como interpretar uma chamada recusada |
| [Registro de chamadas](/docs/guides/voice/call-log)    | O registro que cada chamada gera e como filtrá-lo e exportá-lo                   |

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