Sign inGet Started

Grupos de toque

Um grupo de toque faz tocar para as pessoas do seu espaço de trabalho que estão online no telefone no 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 Everyone que toca para todos que estão online. Adicione seus próprios grupos para tocar para 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 toca apenas para membros que estão online no telefone no navegador. Receber chamadas explica como ficar online e quem pode fazer isso.
  • Permissão para gerenciar o Voice. Para visualizar grupos de toque, você precisa de voice_management no nível de leitura. Para criar, renomear, excluir e alterar membros, e para direcionar um número a um grupo, você precisa dela no nível de escrita.
  • Para a API ou CLI: uma chave de API com o escopo voice_management no nível que a operação exige.

O grupo padrão

O grupo Everyone é sempre o primeiro da lista. Seus membros são todos os usuários online no espaço de trabalho no momento em que uma chamada chega, então 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 todas as leituras. Use-o em qualquer lugar que aceite um ID de grupo de toque.

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 mostra os usuários com acesso ao espaço de trabalho.

A coluna Online conta os membros do grupo que estão online e aceitando chamadas. Ela inclui membros 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);
const member = await bird.voice.ringGroups.members.create("RING_GROUP_ID", { user_id: "USER_ID" });
console.log(member.user_id);

Um usuário que depois sai do espaço de trabalho 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 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 nas configurações de voz para a rota padrão. 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

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 é nela que entra um correio de voz ou um encaminhamento quando o grupo não atende.

Como um grupo de toque toca

Quando uma chamada chega 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 os outros param de tocar.
  • Um membro toca em um único dispositivo: o navegador que mantém seu status online.

Um membro é ignorado quando está offline, Busy, já em uma chamada ou Not accepting calls após três chamadas perdidas seguidas. Seu status explica cada um.

O chamador ouve o toque enquanto os membros são chamados, e a chamada só é atendida quando um membro aceita, então 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 quem não foi atendido para outro destino, roteie o número para uma sequência que toca o grupo e depois continua.

Nos API de trechos de voz, o trecho do chamador os identifica em answered_by. Em uma gravação ou transcrição, o user_id da parte identifica o membro daquele lado.

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 do grupo não são afetadas.

Não é possível excluir um grupo que ainda é chamado 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

LimiteValor
Grupos de toque por espaço de trabalho, além do Everyone50
Membros por grupo de toque200
Membros chamados ao mesmo tempo5
Tempo de toque de cada chamada60 s

O grupo padrão não tem limite de membros. Uma criação ou adição de membro que ultrapasse um limite é recusada com 422, com uma mensagem que indica o limite. O número de usuários que 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

PáginaO que ela aborda
TelefoneComo ficar online, seu status e como atender uma chamada no navegador
Receber chamadasTodas as rotas que um número pode seguir e como interpretar uma chamada recusada
Registro de chamadasO registro que cada chamada deixa e como filtrá-lo e exportá-lo

Continue com a documentação, guias e exemplos sobre este tópico.