Ring-Gruppen

Eine Ring-Gruppe 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 verfügbaren Mitgliedern der Gruppe im Dashboard, bis eines davon annimmt.

Jeder Workspace hat eine Gruppe Default, die bei allen klingelt, die online sind. Legen Sie eigene Gruppen an, um ein kleineres Team wie Support oder Vertrieb klingeln zu lassen, und weisen Sie jede Nummer der Gruppe zu, die sie annehmen soll.

Bevor Sie beginnen

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

Die Standardgruppe

Die Gruppe Default steht immer an erster Stelle der Liste. Ihre Mitglieder sind alle Benutzer, die im Moment des Anrufeingangs im Workspace online sind. Sie fügen ihr daher 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. Sie ist daher bei jedem Lesezugriff gleich. Verwenden Sie sie überall, wo eine Ring-Gruppen-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 in den Members der Gruppe Add member und wählen Sie jeden Benutzer aus, 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 in einem laufenden Gespräch, bei denen es erst nach dessen Ende klingelt. Eine neue Gruppe hat keine Mitglieder und zeigt daher 0 an, bis Sie Mitglieder hinzufügen.

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

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 aufgeführt, 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. Bei einem entfernten Mitglied klingelt es ab dem nächsten Anruf 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 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 klicken Sie auf 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 wie Sie eine Nummer wieder auf die Standardroute zurücksetzen.

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

Wie eine Ringgruppe klingelt

Wenn ein Anruf für eine Gruppe eingeht, liest Bird die Mitglieder der Gruppe, die in diesem Moment angeklingelt werden können, und bringt sie in eine zufällige Reihenfolge:

• Mitglieder werden in Gruppen von fünf angeklingelt, bis zu 20 Sekunden pro Durchgang. Wenn alle Mitglieder eines Durchgangs ablehnen oder nicht erreichbar sind, beginnt sofort der nächste Durchgang.
• Das Klingeln endet nach insgesamt 60 Sekunden.
• Das erste Mitglied, das Accept auswählt, übernimmt den Anruf, und bei den anderen hört das Klingeln auf.
• Bei einem Mitglied klingelt nur ein Gerät: der Browser, der seinen Online-Status hält.

Ein Mitglied wird übersprungen, wenn es offline oder Busy ist, 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. Nimmt innerhalb von 60 Sekunden niemand ab oder kann niemand angeklingelt werden, lehnt eine direkt an die Gruppe geleitete Nummer den Anruf ab. Um unbeantwortete Anrufer anderswohin zu leiten, leiten Sie die Nummer an eine Sequenz, die die Gruppe klingeln lässt und danach fortfährt.

In den Sprach-Legs API nennt der Leg des Anrufers das Mitglied in answered_by. In einer Aufnahme oder einem Transkript nennt user_id des Teilnehmers das Mitglied auf dieser Seite.

Eine Ringgruppe 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 angeklingelt wird, lässt sich nicht löschen: Die Anfrage wird mit 409 und E21071 abgelehnt. Leiten Sie diese zuerst auf eine andere Route um und löschen Sie dann die Gruppe.

Limits

Für die Standardgruppe gibt es kein Mitgliederlimit. Wenn das Erstellen einer Gruppe oder das Hinzufügen eines Mitglieds 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 Online-Benutzer 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