Compartir a través de

Salas para sesión de subgrupo

  • Artículo

En este artículo se describe cómo implementar salas de interrupción de Microsoft Teams con Azure Communication Services. Esta funcionalidad permite a los usuarios de Azure Communication Services en reuniones de Teams participar en salas de interrupción. Los administradores de Teams controlan la disponibilidad de las salas de interrupción en la reunión de Teams con la directiva de reuniones de Teams. Puede encontrar información adicional sobre las salas para sesión de subgrupo en la documentación de Teams.

Requisitos previos

Solo los usuarios de Microsoft 365 con el rol organizador, coorganizador o administrador de salas de reuniones pueden administrar las salas para sesión de subgrupo.

Soporte técnico

En las siguientes tablas se define la compatibilidad de las salas para sesión de subgrupo en Azure Communication Services.

Identidades y tipos de llamadas

En la tabla siguiente se muestra compatibilidad en salas de interrupción para un tipo de llamada y una identidad específicos.

Identidades Reuniones en Teams Sala Llamada 1:1 Llamada grupal Llamada de interoperabilidad de Teams individual Llamada de interoperabilidad de Teams de grupo
Usuario de Communication Services ✔️
Usuario de Microsoft 365 ✔️

Operations

En la tabla siguiente se muestra compatibilidad con API individuales en el SDK de llamada relacionado con tipos de identidad individuales.

Operations Usuario de Communication Services Usuario de Microsoft 365
Obtención de la sala para sesión de subgrupo asignada ✔️ ✔️
Obtención de todas las salas para sesión de subgrupo ✔️[1]
Unirse a la sala para sesión de subgrupo ✔️ ✔️
Administrar salas de trabajos en grupo
Participar en el chat de la sala para sesión de subgrupo ✔️[2]
Obtención de la configuración de la sala para sesión de subgrupo ✔️ ✔️

[1] Solo usuario de Microsoft 365 con función de organizador, coorganizador o administrador de sala para sesión de subgrupo.

[2] Los usuarios de Microsoft 365 pueden usar Graph API para participar en el chat de la sala para sesión de subgrupo. El identificador de subproceso del chat se proporciona en el objeto de sala para sesión de subgrupo asignado.

SDK

En las tablas siguientes se muestra compatibilidad con la característica de salas de interrupción en los SDK individuales de Azure Communication Services.

Estado de compatibilidad Web IU Web iOS Interfaz de usuario de iOS Android UI de Android Windows
Se admite ✔️

Instalación del SDK

Use el comando npm install para instalar los SDK comunes y de llamada de Azure Communication Services para JavaScript:

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

Inicialización de los objetos necesarios

Se requiere una instancia de CallClient para la mayoría de las operaciones de llamada. Al crear una nueva instancia de CallClient, puede configurarla con opciones personalizadas, como una instancia de Logger.

Con la instancia de CallClient, puede crear una instancia de CallAgent llamando al createCallAgent. Este método devuelve un objeto de instancia CallAgent de manera asincrónica.

El método createCallAgent utiliza CommunicationTokenCredential como argumento. Acepta un token de acceso de usuario.

Puede usar el método getDeviceManager en la instancia de CallClient para acceder a deviceManager.

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Cuál es la mejor forma de administrar la conectividad del SDK en la infraestructura de Microsoft

La instancia de Call Agent le ayuda a administrar llamadas (para unirse o iniciar llamadas). Para trabajar con el SDK de llamadas, debe conectarse a la infraestructura de Microsoft para obtener notificaciones de llamadas entrantes y coordinar otros detalles de la llamada. Call Agent tiene dos posibles estados:

Conectado: un valor connectionStatue Call Agent con estado Connected significa que el SDK de cliente está conectado y es capaz de recibir notificaciones de la infraestructura de Microsoft.

Desconectado: un valor connectionStatue Call Agent con estado Disconnected indica que hay un problema que impide que el SDK se conecte correctamente. Call Agent se debe volver a crear.

  • invalidToken: si un token ha expirado o no es válido, la instancia de Call Agent se desconecta con este error.
  • connectionIssue: si hay un problema cuando el cliente se conecta a la infraestructura de Microsoft, después de muchos reintentos, Call Agent expone el error connectionIssue.

Para comprobar si el Call Agent local está conectado a la infraestructura de Microsoft, inspeccione el valor actual de la propiedad connectionState. Durante una llamada activa, puede escuchar el evento connectionStateChanged para determinar si Call Agent cambia de Conectado a Desconectado.

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

Implementación de salas de interrupción

BreakoutRooms es un feature de la clase Call. En primer lugar, debe importar el paquete Features desde el SDK de llamadas:

import { Features} from "@azure/communication-calling";

Creación de una característica breakoutRoom

A continuación, obtenga el objeto de API de características de la instancia de llamada:

const breakoutRoomsFeature = mainMeetingCall.feature(Features.BreakoutRooms);

Suscribirse a eventos breakoutRoom

La API BreakoutRooms permite suscribirse a los eventos BreakoutRooms. Un evento breakoutRoomsUpdated procede de una instancia de BreakoutRoomsCallFeature y contiene información sobre las salas de interrupción creadas, actualizadas y asignadas.

Para recibir detalles de la sala para sesión de subgrupo, suscríbase al evento breakoutRoomsUpdated.

breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Control de eventos breakoutRoom

El evento breakoutRoomsUpdated proporciona una instancia de una de las siguientes clases como parámetro de entrada. Puede usar la propiedad type para distinguir entre tipos de eventos individuales.

  • Clase BreakoutRoomsEvent: Este evento se desencadena cuando un usuario con el organizador de roles, coorganizador o administrador de salas de interrupción crea o actualiza las salas de interrupción. Los usuarios de Microsoft 365 con organizador de roles, coorganizador o administrador de salas de interrupción pueden recibir este tipo de evento. Los desarrolladores pueden usar las salas para sesión de subgrupo en la propiedad data para representar detalles sobre todas las salas para sesión de subgrupo. Esta clase tiene la propiedad type igual a "breakoutRooms".

      export interface BreakoutRoomsEvent {
    /**
     * Breakout room event type
    */
    type: "breakoutRooms",
    /**
     * list of Breakout rooms
    */
    data: BreakoutRoom[] | undefined;
  }

  • Clase BreakoutRoomsSettingsEvent: Cuando un usuario con un organizador de roles, coorganizador o administrador de salas de interrupción actualiza la configuración de la sala de interrupción, desencadena este evento. Los desarrolladores pueden usar esta información para representar la hora en que finaliza la sala de interrupción o decidir si se va a representar un botón para unirse a la sala principal. Esta clase tiene la propiedad type igual a "breakoutRoomSettings".

      export interface BreakoutRoomSettingsEvent {
    /**
    * Breakout room event type
    */
    type: "breakoutRoomSettings",
    /**
    * Breakout Room setting details
    */
    data: BreakoutRoomSettings | undefined;
  }

  • Clase AssignedBreakoutRoomsEvent: este evento se desencadena cuando el usuario se asigna a una sala para sesión de subgrupo o se actualiza la sala para sesión de subgrupo asignada. Los usuarios pueden unirse a la sala de interrupción cuando la propiedad state está establecida en open, deje la sala de interrupción cuando la propiedad state esté establecida en closed, o represente los detalles de la sala de interrupción. Esta clase tiene la propiedad type igual a "assignedBreakoutRoom".

      export interface AssignedBreakoutRoomEvent {
    /**
     * Breakout room event type
     */
    type: "assignedBreakoutRoom";
    /**
     * Assigned breakout room details
     */
    data: BreakoutRoom | undefined;
  }

  • Clase JoinBreakoutRoomsEvent: Este evento se desencadena cuando el participante se une a una llamada de sala de interrupción. Este evento puede ocurrir cuando un usuario se mueve automáticamente a la sala de interrupción (es decir, si assignedBreakoutRoom tiene la propiedad state establecida en open y autoMoveParticipantToBreakoutRoom se establece en true) o cuando un usuario se une explícitamente a una sala de interrupción (es decir, llama al método join en la instancia assignedBreakoutRoom cuando autoMoveParticipantToBreakoutRoom se establece en false). La propiedad data contiene la instancia de call de la sala para sesión de subgrupo, que los desarrolladores pueden usar para controlar la llamada a la sala para sesión de subgrupo. Esta clase tiene la propiedad type igual a "join".

      export interface JoinBreakoutRoomEvent {
    /**
     * Breakout room event type
     */
    type: "join";
    /**
     * Breakoutroom call object
     */
    data: Call | TeamsCall;
  }

El siguiente código muestra información valiosa recibida en los eventos de la sala para sesión de subgrupo:

    const breakoutRoomsUpdatedListener = (event) => {
    switch(event.type) {
        case "breakoutRooms":
          const breakoutRooms = event.data;
          console.log(`Breakout rooms are created or updated. There are ${breakoutRooms.length} breakout rooms in total.`);
          breakoutRooms.forEach((room)=>{
          console.log(`- ${room.displayName}`);
          });    
          break;
        case "assignedBreakoutRooms":
          const assignedRoom = event.data;
          console.log(`You are assigned to breakout room named: ${assignedRoom.displayName}`);      
          console.log(`Assigned breakout room thread Id: ${assignedRoom.threadId}`);
          console.log(`Automatically move participants to breakout room: ${assignedRoom.autoMoveParticipantToBreakoutRoom}`);
          console.log(`Assigned breakout room state : ${assignedRoom.state }`);      
          break;
        case "breakoutRoomsSettings":
          const breakoutRoomSettings = event.data;
          console.log(`Breakout room ends at: ${breakoutRoomSettings.roomEndTime}`);          
          console.log(`Disable the user to return to main meeting from breakout room call : ${breakoutRoomSettings.disableReturnToMainMeeting}`);         
          break;
        case "join":
          const breakoutRoomCall = event.data;
          console.log(`You have joined breakout room with call ID: ${breakoutRoomCall.id}`);      
          break;      
      }
    }
breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Lista de las salas para sesión de subgrupo disponibles

Los usuarios de Microsoft 365 con organizador de roles, coorganizador o administrador de salas de interrupción pueden acceder a todas las salas de interrupción.

const breakoutRooms = breakoutRoomsFeature.breakoutRooms;
breakoutRooms.forEach((room)=>{
      console.log(`- ${room.displayName}`);
       });

Lista de invitados

El usuario de Microsoft 365 con el rol de organizador, coorganizador o administrador de salas para sesión de subgrupo puede acceder a los participantes asignados a salas para sesión de subgrupo individuales.

breakoutRooms.forEach((room)=>{
      console.log(`${room.displayName}`);
      room.invitees.forEach((invitee) => {
          console.log(`- ${invitee.id}`);         
          })
      })

Unirse a la sala para sesión de subgrupo

Si el assignedBreakoutRoom tiene la propiedad autoMoveParticipantToBreakoutRoom establecida en true, el usuario se mueve automáticamente a la sala para sesión de subgrupo cuando la propiedad state está establecida en open. Si autoMoveParticipantToBreakoutRoom se establece en false, use el siguiente código para unir la sala para sesión de subgrupo.

Esto desencadena el evento breakoutRoomsUpdated con clase JoinBreakoutRoomsEvent que tiene la propiedad type establecida como join. Puede usar la instancia de una clase call en la propiedad data para administrar la llamada a la sala para sesión de subgrupo.

const breakoutRoom = breakoutRoomsFeature.assignedBreakoutRoom;
if(breakoutRoom.state == 'open' && !breakoutRoom.autoMoveParticipantToBreakoutRoom) {
  const breakoutRoomCall = await breakoutRoom.join();
}

Cuando el usuario está en una sala para sesión de subgrupo y el organizador le asigna una nueva, el usuario obtiene el evento breakoutRoomsUpdated con el tipo assignedBreakoutRooms. Este evento contiene los detalles más recientes de la sala. El usuario tiene que hangUp() la llamada de sala anterior. Si autoMoveParticipantToBreakoutRoom se establece en true, el usuario se mueve automáticamente; de lo contrario, el usuario tiene que llamar al método join explícitamente en la nueva sala.

//Breakout room which is assigned initially.
const breakoutRoom = breakoutRoomsFeature.assignedBreakoutRoom;
if(breakoutRoom.state == 'open' && !breakoutRoom.autoMoveParticipantToBreakoutRoom) {
  const breakoutRoomCall = await breakoutRoom.join();
}

// `breakoutRoomsUpdated` event which contains the details of the new breakout room
let assignedRoom = undefined;
const breakoutRoomsUpdatedListener = (event) => {
     switch(event.type) {
          case "assignedBreakoutRooms":
          const assignedRoom = event.data;
          break;
     }
}

if(assignedRoom.threadId != breakoutRoom.threadId && breakoutRooms != null)
{
    await breakoutRoom.hangUp();
}
if(assignedRoom.state == 'open' && !assignedRoom.autoMoveParticipantToBreakoutRoom) {
  const breakoutRoomCall = await assignedRoom.join();
}

El usuario de Microsoft 365 con el organizador de roles, coorganizador o administrador de salas obtiene la lista de salas creada por el administrador de salas o el organizador de la reunión principal. En este caso, el comportamiento es ligeramente diferente. Este usuario tiene que llamar explícitamente al método join() para unirse a la sala. El usuario se mantiene en espera en la reunión principal inicialmente y finalmente se quita de la reunión principal. El usuario tiene que inicializar la característica breakoutRooms para breakoutRoomCall a fin de recibir actualizaciones sobre la sala.

Si el usuario quiere unirse a cualquiera de las salas, llama explícitamente al método join.

const breakoutRoom = breakoutRoomsFeature.breakoutRooms[0];
if(breakoutRoom.state == 'open') {
  const breakoutRoomCall = await breakoutRoom.join();
}

Para salir de una sala, los usuarios deben ejecutar la función hangUp() en la llamada a la sala. El usuario llamaría a ReturnToMainMeeting para reanudar la llamada a la reunión principal.

breakoutRoomCall.hangUp();
const mainMeetingCall = breakoutRoomCall.returnToMainMeeting();

Abandonar la sala para sesión de subgrupo

Cuando el estado de la sala es closed, se informa al usuario sobre el final de la sala al recibir el evento breakoutRoomsUpdated con la clase AssignedBreakoutRoomsEvent y la propiedad type igual a assignedBreakoutRooms que indica que assignedBreakoutRoom tiene la propiedad state establecida en closed. El usuario deja la sala automáticamente y puede volver a la reunión principal si llama a returnToMainMeeting() como se ha mostrado antes.

Si el usuario quiere abandonar la sala incluso antes de que se cierre y la configuración de la sala breakoutRoomsFeature.breakoutRoomsSettings tiene la propiedad disableReturnToMainMeeting establecida en false, el usuario puede volver a la llamada de la reunión principal con el siguiente código:

breakoutRoomCall.hangUp();
const mainMeetingCall = breakoutRoomCall.returnToMainMeeting();

Obtención de los participantes de la sala para sesión de subgrupo

Al unirse a la sala para sesión de subgrupo, puede usar el siguiente código para obtener la lista de participantes remotos de la sala para sesión de subgrupo:

const breakoutRoomParticipants = [breakoutRoomCall.remoteParticipants.values()].map((p: SDK.RemoteParticipant) => { p.displayName || p.identifier });
console.log(`Participants of the breakoutRoom : <br/>" + breakoutRoomParticipants.join("<br/>")`);

Deje de recibir eventos de salas para sesión de subgrupo

Use el código siguiente para dejar de recibir eventos breakoutRooms.

breakoutRoomsFeature.off('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Propiedades de la sala para sesión de subgrupo

Las salas para sesión de subgrupo tienen las siguientes propiedades:

Nota:

El código de ejemplo siguiente muestra eficazmente todas las propiedades de la sala de interrupción. No está pensado para reutilizarse como se muestra. En la práctica, solo se usan las propiedades necesarias para el escenario de sala de interrupción.

const displayName : string = breakoutRoom.displayName;
const threadId : string = breakoutRoom.threadId;
const state : BreakoutRoomState = breakoutRoom.state;
const autoMoveParticipantToBreakoutRoom : boolean = breakoutRoom.autoMoveParticipantToBreakoutRoom; 
const call : Call | TeamsCall = breakoutRoom.call;
const invitees : Invitee[] = breakoutRoom.invitees;
Propiedades de la sala para sesión de subgrupo Descripción
displayName Nombre de la sala de interrupción. Esta propiedad es de solo lectura.
threadId Use el identificador del subproceso de chat para unirse al chat del salón de interrupción. Esta propiedad es de solo lectura.
state Estado de la sala de interrupción. Puede ser open o closed. Los usuarios podrían unirse a la sala para sesión de subgrupo solo cuando el estado es open. Esta propiedad es de solo lectura.
autoMoveParticipantToBreakoutRoom Valor booleano que indica si los usuarios se mueven a salas de interrupción automáticamente cuando el state de assignedBreakoutRoom está establecido en open. Esta propiedad es de solo lectura. En la configuración de la interfaz de usuario de Teams para las salas para sesión de subgrupo, el organizador, el coorganizador o el administrador de la sala para sesión de subgrupo pueden ajustar esta configuración específica. Al establecer esta opción en true, los participantes se transfieren automáticamente a su sala de interrupción designada. Por el contrario, si establece esta propiedad en false, debe llamar manualmente al método join para mover los participantes a la sala de interrupción.
call Objeto de llamada de sala de interrupción. Este objeto se devuelve cuando el usuario se une automáticamente a la llamada a la sala de interrupción o llamando al método join en assignedBreakoutRoom objeto. Esta propiedad es de solo lectura.
invitees Lista de invitaciones asignadas al salón de interrupción. Esta propiedad es de solo lectura.

Configuración de la sala para sesión de subgrupo

Las salas para sesión de subgrupo comparten la configuración que tiene las siguientes propiedades:

const disableReturnToMainMeeting : boolean = breakoutRoomsSettings.disableReturnToMainMeeting;
const roomEndTime : TimestampInfo = breakoutRoomsSettings.roomEndTime;
Propiedades de la sala para sesión de subgrupo Descripción
disableReturnToMainMeeting Deshabilite a los participantes para volver a la reunión principal desde la llamada a la sala de interrupción. Esta propiedad es de solo lectura. En la configuración de la interfaz de usuario de Teams para las salas para sesión de subgrupo, el organizador, el coorganizador o el administrador de la sala para sesión de subgrupo pueden ajustar esta configuración específica para controlar cuándo los participantes de las salas para sesión de subgrupo pueden volver a la reunión principal.
roomEndTime Hora de finalización de la sala de interrupción establecida por el usuario de Microsoft 365 con organizador de roles, coorganizador o administrador de salas de interrupción de la reunión principal. Esta propiedad es de solo lectura.

Solución de problemas

Código de error SubCode Categoría de resultado Motivo Solución
400 46250 ExpectedError La característica Salas para sesión de subgrupo solo está disponible en las reuniones de Teams. Implemente su propio mecanismo de sala para sesión de subgrupo o use reuniones de Teams.
405 46251 ExpectedError Actualmente, Azure Communication Services ha deshabilitado esta característica. Pruebe las API en un par de días.
500 46254 UnexpectedServerError No se puede unir a la sala para sesión de subgrupo debido a un error inesperado. Asegúrese de que el state de assignedBreakoutRoom sea open y llame explícitamente al método breakoutRoomsFeature.assignedBreakoutRoom.join(). Si el problema persiste, recopile los registros de la consola del explorador y póngase en contacto con el soporte técnico de Azure Communication Services.
500 46255 UnexpectedServerError No se puede celebrar la reunión principal. Asegúrese de que el state de assignedBreakoutRoom sea open y llame explícitamente al método breakoutRoomsFeature.assignedBreakoutRoom.join(). Si el problema persiste, recopile los registros de la consola del explorador y póngase en contacto con el soporte técnico de Azure Communication Services.
412 46256 ExpectedError No se puede unir a la sala para sesión de subgrupo ya que la sala está cerrada. Asegúrese de que el state de assignedBreakoutRoom sea open y llame explícitamente al método breakoutRoomsFeature.assignedBreakoutRoom.join().
412 46257 UnexpectedServerError No se puede reanudar la reunión principal. Siga las instrucciones definidas en la sección Leave breakout room para la salida manual de la sala para sesión de subgrupo. Si el problema persiste, recopile los registros de la consola del explorador y póngase en contacto con el soporte técnico de Azure Communication Services.
412 46258 UnexpectedClientError No se pueden leer los detalles de la sala para sesión de subgrupo. Recopile los registros de la consola del explorador y póngase en contacto con el soporte técnico de Azure Communication Services.
500 46259 UnexpectedServerError No se pudo colgar la llamada a la sala para sesión de subgrupo. Siga las instrucciones definidas en la sección Leave breakout room para la salida manual de la sala para sesión de subgrupo.
412 46260 UnexpectedClientError No se puede unir a la sala para sesión de subgrupo ya que aún no está asignado. Asegúrese de que el breakoutRoomsFeature.assignedBreakoutRoom tenga los detalles de la sala para sesión de subgrupo asignada. Asegúrese de que el state de assignedBreakoutRoom sea open y llame explícitamente al método breakoutRoomsFeature.assignedBreakoutRoom.join().
412 46261 UnexpectedClientError No se puede unir a la reunión principal. Inténtelo de nuevo llamando al método breakoutRoomsFeature.assignedBreakoutRoom.returnToMainMeeting(). Si el problema persiste, recopile los registros de la consola del explorador y póngase en contacto con el soporte técnico de Azure Communication Services.
412 46262 ExpectedError Ya está en la reunión principal. Llame a este método solo cuando el participante esté en la sala y se quite de la reunión principal.
412 46263 UnexpectedClientError Error de bloqueo de la llamada a la sala existente. Intente llamar al método hangup() de nuevo para colgar la llamada. Llame al método join() para volver a unirse a la sala.

Pasos siguientes