Gruppi di squillo

Un gruppo di squillo fa squillare le persone del tuo spazio di lavoro che sono online nel telefono del browser. Instrada un numero, o il percorso predefinito del tuo spazio di lavoro, verso un gruppo: una chiamata in arrivo fa squillare nella dashboard i membri online del gruppo finché uno di loro non risponde.

Ogni spazio di lavoro ha un gruppo Default che fa squillare tutti gli utenti online. Aggiungi i tuoi gruppi per far squillare un team più piccolo, come l'assistenza o le vendite, e associa ogni numero al gruppo che deve rispondere.

Prima di iniziare

• Membri che vanno online. Un gruppo di squillo fa squillare solo i membri online nel telefono del browser. Ricevere chiamate spiega come andare online e chi può farlo.
• Autorizzazione a gestire Voice. Per visualizzare i gruppi di squillo serve voice_management a livello di lettura. Per creare, rinominare ed eliminare gruppi, modificarne i membri e instradare un numero verso un gruppo serve a livello di scrittura.
• Per API o CLI: una chiave API con l'ambito voice_management al livello richiesto dall'operazione.

Il gruppo predefinito

Il gruppo Default è sempre il primo dell'elenco. I suoi membri sono tutti gli utenti online nello spazio di lavoro nel momento in cui arriva una chiamata, quindi non devi mai aggiungervi nessuno. Non può essere rinominato né eliminato e i suoi membri non possono essere modificati: una richiesta in tal senso viene rifiutata con 409 e E21072.

Il suo ID è vrg_ seguito dal suffisso dell'ID del tuo spazio di lavoro, quindi è lo stesso in ogni lettura. Usalo ovunque sia accettato l'ID di un gruppo di squillo.

Creare un gruppo di squillo

1. Apri Voice > Ring groups e seleziona New ring group.
2. Inserisci un Name e seleziona Create ring group.
3. In Members del gruppo, seleziona Add member e scegli ogni utente che il gruppo deve far squillare. L'elenco propone gli utenti che possono accedere allo spazio di lavoro.

La colonna Online conta i membri del gruppo che sono online e accettano chiamate. Include i membri impegnati in una chiamata, che non squillano finché quella chiamata non termina. Un nuovo gruppo non ha membri, quindi mostra 0 finché non li aggiungi.

Tramite API, crea il gruppo di squillo, poi aggiungi ogni membro tramite il suo ID utente. Per trovare gli ID utente, esegui bird members list, che richiede l'ambito members in lettura.

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

Un utente che in seguito lascia lo spazio di lavoro resta nell'elenco finché non lo rimuovi, ma il gruppo non lo fa mai squillare. Per rimuovere un membro, seleziona Remove accanto al suo nome, oppure rimuovi il membro tramite API. Un membro rimosso smette di squillare dalla chiamata successiva.

Instradare le chiamate a un gruppo di squillo

Un numero fa squillare un gruppo quando il suo instradamento, o l'instradamento predefinito dello spazio di lavoro che segue, indica quel gruppo.

• Un solo numero: apri Voice > Numbers, apri il numero e in Inbound routing scegli Ring a ring group. Scegli il gruppo e seleziona Save.
• Tutti i numeri senza un instradamento proprio: nella pagina Numbers, accanto a Calls to numbers without their own route, seleziona Change, scegli Ring a ring group e il gruppo, poi salva.

Tramite API, imposta l'instradamento su {"type": "ring_group", "ring_group_id": "<id>"} quando aggiorni il numero, oppure nelle impostazioni vocali per l'instradamento predefinito. Un ring_group_id che non corrisponde né al gruppo predefinito né a un gruppo dello spazio di lavoro viene rifiutato con 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 accetta gli stessi flag --route ring_group --ring-group-id per l'instradamento predefinito. Ricevere chiamate descrive gli altri instradamenti e spiega come riportare un numero all'instradamento predefinito.

Anche una sequenza può far squillare un gruppo, da un passaggio di chiamata. L'esito del passaggio prosegue poi la sequenza: è lì che va inserita una segreteria o un inoltro quando il gruppo non risponde.

Come squilla un gruppo di squillo

Quando arriva una chiamata per un gruppo, Bird legge i membri del gruppo che possono squillare in quel momento e li mescola in ordine casuale:

• I membri squillano cinque alla volta, per un massimo di 20 secondi per gruppo di squilli. Quando tutti i membri di un gruppo di squilli rifiutano o non sono raggiungibili, il gruppo successivo parte subito.
• Lo squillo si interrompe dopo 60 secondi in totale.
• Il primo membro che seleziona Accept prende la chiamata e per gli altri lo squillo si interrompe.
• Un membro squilla su un solo dispositivo: il browser che mantiene il suo stato online.

Un membro viene saltato quando è offline, Busy, già impegnato in una chiamata oppure Not accepting calls dopo tre chiamate perse di fila. Il tuo stato spiega ciascuno di questi stati.

Mentre i membri squillano, il chiamante sente il segnale di chiamata e la chiamata non riceve risposta finché un membro non accetta, quindi il tempo di squillo non viene addebitato. Se nessuno risponde entro 60 secondi, o nessuno può squillare, un numero instradato direttamente al gruppo rifiuta la chiamata. Per indirizzare altrove i chiamanti senza risposta, instrada il numero a una sequenza che fa squillare il gruppo e poi prosegue.

Eliminare un gruppo di squillo

Seleziona il gruppo nella pagina Ring groups e seleziona Delete ring group. Le chiamate che stanno già facendo squillare i suoi membri non vengono interessate.

Non puoi eliminare un gruppo che un numero, l'instradamento predefinito dello spazio di lavoro o una sequenza pubblicata fa ancora squillare: la richiesta viene rifiutata con 409 e E21071. Prima indirizza ciascuno di essi verso un altro instradamento, poi elimina il gruppo.

Limiti

Il gruppo predefinito non ha un limite di membri. Una creazione o un membro aggiunto oltre un limite viene rifiutato con 422, con un messaggio che indica il limite. Il numero di utenti che possono essere online contemporaneamente è un limite dell'organizzazione, descritto in Limite di utenti online.

Gestire i gruppi di squillo da API, CLI o MCP

Il server MCP offre le stesse operazioni come strumenti voice_ring_groups_*, e i suoi strumenti voice_numbers_update e voice_settings_update accettano un instradamento ring_group. Ogni lettura di un gruppo include online_member_count, lo stesso conteggio della colonna Online.

Passaggi successivi