Grupos de llamada

Un grupo de llamada hace sonar a las personas de tu espacio de trabajo que están en línea en el teléfono del navegador. Dirige un número, o la ruta predeterminada de tu espacio de trabajo, a un grupo, y cada llamada entrante sonará en el panel para los miembros del grupo que estén en línea hasta que uno de ellos conteste.

Cada espacio de trabajo tiene un grupo Default que hace sonar a todas las personas en línea. Añade tus propios grupos para hacer sonar a un equipo más pequeño, como soporte o ventas, y dirige cada número al grupo que debe contestarlo.

Antes de empezar

• Miembros que se conectan. Un grupo de llamada solo hace sonar a los miembros que están en línea en el teléfono del navegador. En Recibir llamadas se explica cómo conectarse y quién puede hacerlo.
• Permiso para gestionar Voice. Para ver los grupos de llamada necesitas voice_management con nivel de lectura. Para crearlos, cambiarles el nombre, eliminarlos, cambiar sus miembros y dirigir un número a un grupo, lo necesitas con nivel de escritura.
• Para API o CLI: una clave de API con el ámbito voice_management en el nivel que requiere la operación.

El grupo predeterminado

El grupo Default aparece siempre primero en la lista. Sus miembros son todos los usuarios en línea en el espacio de trabajo en el momento en que llega una llamada, así que nunca tienes que añadir a nadie. No se puede renombrar ni eliminar, y sus miembros no se pueden cambiar: cualquier solicitud para hacerlo se rechaza con 409 y E21072.

Su ID es vrg_ seguido del sufijo del ID de tu espacio de trabajo, por lo que es el mismo en cada lectura. Úsalo en cualquier lugar donde se acepte el ID de un grupo de llamada.

Crear un grupo de llamada

1. Abre Voice > Ring groups y selecciona New ring group.
2. Introduce un Name y selecciona Create ring group.
3. En Members del grupo, selecciona Add member y elige cada usuario al que deba llamar el grupo. La lista ofrece los usuarios que tienen acceso al espacio de trabajo.

La columna Online cuenta los miembros del grupo que están en línea y aceptan llamadas. Incluye a los miembros que están en una llamada, a los que no se llama hasta que esa llamada termina. Un grupo nuevo no tiene miembros, así que muestra 0 hasta que los añadas.

Con la API, crea el grupo de llamada y después añade cada miembro por su ID de usuario. Para obtener los ID de usuario, ejecuta bird members list, que requiere el ámbito members con nivel de lectura.

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

Si un usuario abandona después el espacio de trabajo, sigue apareciendo en la lista hasta que lo quites, pero el grupo nunca lo llama. Para quitar un miembro, selecciona Remove junto a él, o quita el miembro con la API. Un miembro quitado deja de recibir llamadas a partir de la siguiente.

Dirigir llamadas a un grupo de llamada

Un número llama a un grupo cuando su propia ruta, o la ruta predeterminada del espacio de trabajo que sigue, indica ese grupo.

• Un solo número: abre Voice > Numbers, abre el número y, en Inbound routing, elige Ring a ring group. Elige el grupo y selecciona Save.
• Todos los números sin ruta propia: en la página Numbers, junto a Calls to numbers without their own route, selecciona Change, elige Ring a ring group y el grupo, y guarda.

Con la API, establece la ruta en {"type": "ring_group", "ring_group_id": "<id>"} al actualizar el número, o en la configuración de voz para la ruta predeterminada. Si el ring_group_id no es el grupo predeterminado ni un grupo del espacio de trabajo, la solicitud se rechaza 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 admite las mismas opciones --route ring_group --ring-group-id para la ruta predeterminada. Recibir llamadas describe las demás rutas y cómo devolver un número a la ruta predeterminada.

Una secuencia también puede hacer sonar un grupo, desde un paso de marcación. El resultado del paso continúa entonces la secuencia, y ahí es donde se configura un buzón de voz o un desvío cuando el grupo no contesta.

Cómo suena un grupo de timbrado

Cuando llega una llamada para un grupo, Bird lee los miembros del grupo que pueden recibir la llamada en ese momento y los ordena al azar:

• Los miembros suenan de cinco en cinco, durante un máximo de 20 segundos por tanda. Cuando todos los miembros de una tanda rechazan la llamada o no están localizables, la siguiente tanda empieza de inmediato.
• El timbrado se detiene tras 60 segundos en total.
• El primer miembro que selecciona Accept atiende la llamada, y los demás dejan de sonar.
• A cada miembro le suena un solo dispositivo: el navegador que mantiene su estado en línea.

Se omite a un miembro cuando está desconectado, en Busy, ya en una llamada, o en Not accepting calls tras tres llamadas perdidas seguidas. Tu estado explica cada uno.

La persona que llama oye el tono mientras suenan los miembros, y la llamada no se contesta hasta que un miembro la acepta, así que el tiempo de timbrado no se factura. Si nadie contesta en 60 segundos, o no se puede hacer sonar a nadie, un número dirigido directamente al grupo rechaza la llamada. Para enviar a otro destino las llamadas no contestadas, dirige el número a una secuencia que haga sonar el grupo y después continúe.

Eliminar un grupo de timbrado

Selecciona el grupo en la página Ring groups y selecciona Delete ring group. Las llamadas que ya están sonando a sus miembros no se ven afectadas.

No puedes eliminar un grupo al que todavía llama un número, la ruta predeterminada del espacio de trabajo o una secuencia publicada: la solicitud se rechaza con 409 y E21071. Primero dirige cada uno de ellos a otra ruta y después elimina el grupo.

Límites

El grupo predeterminado no tiene límite de miembros. Si una creación o un miembro añadido supera un límite, la solicitud se rechaza con 422 y un mensaje que indica el límite. El número de usuarios que pueden estar en línea a la vez es un límite de la organización, descrito en Límite de usuarios en línea.

Gestionar grupos de llamada desde API, CLI o MCP

El servidor MCP ofrece las mismas operaciones como herramientas voice_ring_groups_*, y sus herramientas voice_numbers_update y voice_settings_update aceptan una ruta ring_group. Cada lectura de un grupo incluye online_member_count, el mismo recuento que muestra la columna Online.

Próximos pasos