Belgroepen

Een belgroep belt de mensen in je werkruimte die online zijn in de browsertelefoon. Routeer een nummer, of de standaardroute van je werkruimte, naar een groep. Een inkomende oproep belt dan de online leden van de groep in het dashboard totdat een van hen opneemt.

Elke werkruimte heeft een groep Default die iedereen belt die online is. Voeg eigen groepen toe om een kleiner team te bellen, zoals support of sales, en verwijs elk nummer naar de groep die het moet beantwoorden.

Voordat je begint

• Leden die online gaan. Een belgroep belt alleen leden die online zijn in de browsertelefoon. Oproepen ontvangen legt uit hoe je online gaat en wie dat kan.
• Toestemming om Voice te beheren. Om belgroepen te bekijken heb je voice_management op leesniveau nodig. Om groepen te maken, te hernoemen, te verwijderen, leden te wijzigen en een nummer naar een groep te routeren, heb je deze op schrijfniveau nodig.
• Voor de API of CLI: een API-sleutel met de scope voice_management op het niveau dat de bewerking vereist.

De standaardgroep

De groep Default staat altijd bovenaan de lijst. De leden zijn alle gebruikers die online zijn in de werkruimte op het moment dat een oproep binnenkomt, dus je voegt er nooit iemand aan toe. Je kunt de groep niet hernoemen of verwijderen en de leden niet wijzigen: zo'n verzoek wordt geweigerd met 409 en E21072.

De ID ervan is vrg_ gevolgd door het achtervoegsel van je werkruimte-ID, dus die is bij elke uitlezing hetzelfde. Gebruik deze overal waar een belgroep-ID wordt geaccepteerd.

Een ring group maken

1. Open Voice > Ring groups en selecteer New ring group.
2. Voer een Name in en selecteer Create ring group.
3. Selecteer in de Members van de groep Add member en kies elke gebruiker die de groep moet bellen. De lijst toont gebruikers die toegang hebben tot de werkruimte.

De kolom Online telt de leden van een groep die online zijn en oproepen accepteren. Daarbij horen ook leden die in gesprek zijn, maar die worden pas gebeld als dat gesprek is afgelopen. Een nieuwe groep heeft geen leden, dus de kolom staat op 0 totdat je leden toevoegt.

Via de API maak je de ring group aan en voeg je elk lid toe op gebruikers-ID. Gebruikers-ID's vind je met bird members list. Daarvoor heb je de scope members op leesniveau nodig.

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

Een gebruiker die later de werkruimte verlaat, blijft in de lijst staan totdat je hem verwijdert, maar de groep belt hem nooit. Om een lid te verwijderen selecteer je Remove naast dat lid, of je verwijdert het lid via de API. Een verwijderd lid wordt vanaf de volgende oproep niet meer gebeld.

Oproepen naar een ring group routeren

Een nummer belt een groep wanneer de eigen route van het nummer, of de standaardroute van de werkruimte die het volgt, die groep noemt.

• Eén nummer: open Voice > Numbers, open het nummer en kies onder Inbound routing de optie Ring a ring group. Kies de groep en selecteer Save.
• Elk nummer zonder eigen route: selecteer op de pagina Numbers, naast Calls to numbers without their own route, de optie Change, kies Ring a ring group en de groep, en sla op.

Via de API stel je de route in op {"type": "ring_group", "ring_group_id": "<id>"} wanneer je het nummer bijwerkt, of in de voice-instellingen voor de standaardroute. Een ring_group_id die niet de standaardgroep is en ook geen groep in de werkruimte, wordt geweigerd met 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 accepteert dezelfde --route ring_group --ring-group-id-flags voor de standaardroute. Oproepen ontvangen beschrijft de andere routes en hoe je een nummer terugzet naar de standaardroute.

Een sequence kan ook een groep laten overgaan, vanuit een belstap. De uitkomst van die stap zet de sequence daarna voort. Daar hoort een voicemail of een doorschakeling thuis als de groep niet opneemt.

Hoe een belgroep overgaat

Wanneer er een oproep voor een groep binnenkomt, leest Bird welke leden van de groep op dat moment gebeld kunnen worden en zet ze in een willekeurige volgorde:

• Leden worden per vijf tegelijk gebeld, maximaal 20 seconden per groepje. Als elk lid van een groepje weigert of onbereikbaar is, begint het volgende groepje meteen.
• Het overgaan stopt na in totaal 60 seconden.
• Het eerste lid dat Accept selecteert, neemt de oproep aan en bij de anderen stopt het overgaan.
• Bij een lid gaat maar één apparaat over: de browser die zijn onlinestatus bevat.

Een lid wordt overgeslagen als het offline is, op Busy staat, al in gesprek is, of op Not accepting calls staat na drie gemiste oproepen achter elkaar. Je status legt elke status uit.

De beller hoort een kiestoon terwijl de leden worden gebeld. De oproep wordt pas beantwoord als een lid accepteert, dus de tijd van het overgaan wordt niet gefactureerd. Als niemand binnen 60 seconden opneemt, of niemand gebeld kan worden, weigert een nummer dat rechtstreeks naar de groep routeert de oproep. Wil je onbeantwoorde bellers ergens anders heen sturen, routeer het nummer dan naar een sequence die de groep laat overgaan en daarna verdergaat.

Een belgroep verwijderen

Selecteer de groep op de pagina Ring groups en selecteer Delete ring group. Oproepen die al bij de leden overgaan, blijven ongewijzigd.

Een groep die nog wordt gebeld door een nummer, de standaardroute van de werkruimte of een gepubliceerde sequence, kun je niet verwijderen: het verzoek wordt geweigerd met 409 en E21071. Stel eerst voor elk van deze een andere route in en verwijder daarna de groep.

Limieten

De standaardgroep heeft geen ledenlimiet. Als het aanmaken van een groep of het toevoegen van een lid een limiet overschrijdt, wordt het verzoek geweigerd met 422 en een melding die de limiet noemt. Hoeveel gebruikers tegelijk online kunnen zijn, is een limiet van de organisatie, beschreven in Limiet voor online gebruikers.

Belgroepen beheren via de API, CLI of MCP

De MCP-server biedt dezelfde bewerkingen als voice_ring_groups_*-tools, en de tools voice_numbers_update en voice_settings_update accepteren een ring_group-route. Elke uitgelezen groep bevat online_member_count, hetzelfde aantal als in de kolom Online.

Volgende stappen