Ring Groups

Eine Ring Group lässt die Personen in Ihrem Workspace klingeln, die im Browser-Telefon online sind. Leiten Sie eine Nummer oder die Standardroute Ihres Workspace an eine Gruppe weiter. Ein eingehender Anruf klingelt dann bei den Online-Mitgliedern der Gruppe im Dashboard, bis eines von ihnen annimmt.

Jeder Workspace hat eine Gruppe Default, die bei allen Online-Nutzern klingelt. Legen Sie eigene Gruppen an, um ein kleineres Team wie Support oder Vertrieb klingeln zu lassen, und leiten Sie jede Nummer an die Gruppe weiter, die ihre Anrufe annehmen soll.

Voraussetzungen

• Mitglieder, die online gehen. Eine Ring Group klingelt nur bei Mitgliedern, die im Browser-Telefon online sind. Anrufe empfangen erklärt, wie man online geht und wer das kann.
• Berechtigung zur Verwaltung von Voice. Zum Anzeigen von Ring Groups benötigen Sie voice_management mit Lesezugriff. Zum Erstellen, Umbenennen und Löschen, zum Ändern von Mitgliedern und zum Weiterleiten einer Nummer an eine Gruppe benötigen Sie Schreibzugriff.
• Für API oder CLI: einen API-Schlüssel mit dem Scope voice_management in der Stufe, die der jeweilige Vorgang erfordert.

Die Standardgruppe

Die Gruppe Default steht immer an erster Stelle der Liste. Ihre Mitglieder sind alle Nutzer, die beim Eingang eines Anrufs im Workspace online sind. Sie fügen ihr also nie jemanden hinzu. Sie lässt sich weder umbenennen noch löschen, und ihre Mitglieder lassen sich nicht ändern: Eine entsprechende Anfrage wird mit 409 und E21072 abgelehnt.

Ihre ID besteht aus vrg_, gefolgt vom Suffix Ihrer Workspace-ID, und ist daher bei jedem Abruf gleich. Verwenden Sie sie überall, wo eine Ring-Group-ID akzeptiert wird.

Ring Group erstellen

1. Öffnen Sie Voice > Ring groups und wählen Sie New ring group.
2. Geben Sie einen Name ein und wählen Sie Create ring group.
3. Wählen Sie unter Members der Gruppe Add member und dann jeden Benutzer, bei dem die Gruppe klingeln soll. Die Liste zeigt Benutzer, die Zugriff auf den Workspace haben.

Die Spalte Online zählt die Mitglieder einer Gruppe, die online sind und Anrufe annehmen. Dazu gehören auch Mitglieder, die gerade telefonieren. Bei ihnen klingelt es erst, wenn dieser Anruf endet. Eine neue Gruppe hat keine Mitglieder, daher steht dort 0, bis Sie welche hinzufügen.

Über die API erstellen Sie die Ring Group und fügen dann jedes Mitglied per Benutzer-ID hinzu. Benutzer-IDs ermitteln Sie mit bird members list; dafür benötigen Sie den Scope members mit Leseberechtigung.

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

Ein Benutzer, der den Workspace später verlässt, bleibt in der Liste, bis Sie ihn entfernen, aber die Gruppe klingelt nie bei ihm. Um ein Mitglied zu entfernen, wählen Sie daneben Remove oder entfernen das Mitglied über die API. Ab dem nächsten Anruf klingelt es bei einem entfernten Mitglied nicht mehr.

Anrufe an eine Ring Group weiterleiten

Eine Nummer lässt eine Gruppe klingeln, wenn ihre eigene Route oder die Standardroute des Workspace, der sie folgt, diese Gruppe angibt.

• Eine einzelne Nummer: Öffnen Sie Voice > Numbers, öffnen Sie die Nummer und wählen Sie unter Inbound routing die Option Ring a ring group. Wählen Sie die Gruppe aus und dann Save.
• Alle Nummern ohne eigene Route: Wählen Sie auf der Seite Numbers neben Calls to numbers without their own route die Option Change, wählen Sie Ring a ring group und die Gruppe aus und speichern Sie.

Über die API setzen Sie die Route auf {"type": "ring_group", "ring_group_id": "<id>"}, wenn Sie die Nummer aktualisieren, oder für die Standardroute in den Voice-Einstellungen. Eine ring_group_id, die weder die Standardgruppe noch eine Gruppe im Workspace ist, wird mit 422 abgelehnt.

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 akzeptiert dieselben --route ring_group --ring-group-id-Flags für die Standardroute. Anrufe empfangen beschreibt die anderen Routen und erklärt, wie Sie eine Nummer wieder auf die Standardroute zurücksetzen.

Auch eine Sequenz kann über einen Wählschritt eine Gruppe klingeln lassen. Das Ergebnis des Schritts setzt dann die Sequenz fort. Dort gehören eine Voicemail oder eine Weiterleitung hin, wenn die Gruppe nicht annimmt.

So klingelt eine Ruf­gruppe

Wenn ein Anruf für eine Gruppe eingeht, ermittelt Bird die Mitglieder der Gruppe, die in diesem Moment erreichbar sind, und bringt sie in eine zufällige Reihenfolge:

• Es klingeln jeweils fünf Mitglieder gleichzeitig, bis zu 20 Sekunden pro Gruppe von Mitgliedern. Wenn alle Mitglieder einer solchen Gruppe ablehnen oder nicht erreichbar sind, beginnt sofort die nächste.
• Das Klingeln endet nach insgesamt 60 Sekunden.
• Das erste Mitglied, das Accept auswählt, übernimmt den Anruf, und bei den anderen hört es auf zu klingeln.
• Bei einem Mitglied klingelt nur ein Gerät: der Browser, in dem es online ist.

Ein Mitglied wird übersprungen, wenn es offline ist, den Status Busy hat, bereits telefoniert oder nach drei verpassten Anrufen in Folge auf Not accepting calls steht. Ihr Status erklärt jeden dieser Zustände.

Der Anrufer hört ein Freizeichen, während es bei den Mitgliedern klingelt. Der Anruf gilt erst als angenommen, wenn ein Mitglied annimmt, daher wird die Klingelzeit nicht berechnet. Wenn innerhalb von 60 Sekunden niemand annimmt oder niemand erreichbar ist, lehnt eine Nummer, die direkt an die Gruppe geleitet wird, den Anruf ab. Um unbeantwortete Anrufer an ein anderes Ziel zu leiten, leiten Sie die Nummer an eine Sequenz, die die Gruppe klingeln lässt und danach fortfährt.

Eine Rufgruppe löschen

Wählen Sie die Gruppe auf der Seite Ring groups aus und wählen Sie Delete ring group. Anrufe, die bereits bei ihren Mitgliedern klingeln, sind davon nicht betroffen.

Eine Gruppe, die noch von einer Nummer, der Standardroute des Workspace oder einer veröffentlichten Sequenz angerufen wird, können Sie nicht löschen: Die Anfrage wird mit 409 und E21071 abgelehnt. Leiten Sie zuerst jede davon auf eine andere Route um und löschen Sie dann die Gruppe.

Limits

Für die Standardgruppe gibt es keine Mitgliederbegrenzung. Wenn eine neue Gruppe oder ein hinzugefügtes Mitglied ein Limit überschreitet, wird die Anfrage mit 422 abgelehnt, und die Meldung nennt das betreffende Limit. Wie viele Benutzer gleichzeitig online sein können, ist ein Limit der Organisation, das unter Limit für Benutzer online beschrieben ist.

Ring Groups über API, CLI oder MCP verwalten

Der MCP-Server bietet dieselben Operationen als voice_ring_groups_*-Tools an, und seine Tools voice_numbers_update und voice_settings_update akzeptieren eine ring_group-Route. Jede gelesene Gruppe enthält online_member_count, dieselbe Anzahl wie die Spalte Online.

Nächste Schritte