Grupos de toque

Um grupo de toque chama as pessoas do seu espaço de trabalho que estão online no telefone do navegador. 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 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 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 e depois adicione cada membro pelo ID de usuário. Para encontrar os IDs de usuário, execute bird members list, que exige o escopo members no nível de leitura.

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

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 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, 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 ou, para a rota padrão, nas configurações de voz. Um ring_group_id que não seja o grupo padrão nem um grupo do espaço de trabalho é recusado com 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 aceita as mesmas flags --route ring_group --ring-group-id para a rota padrão. Receber chamadas 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 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

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.

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

O servidor MCP 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