Compartilhar via

Salas para sessão de grupo

  • Artigo

Este artigo descreve como implementar salas para sessão de grupo do Microsoft Teams com os Serviços de Comunicação do Azure. Esta capacidade habilita que os usuários dos Serviços de Comunicação do Azure em reuniões do Teams participem de salas para sessão de grupo. Os administradores do Teams controlam a disponibilidade das salas para sessão de grupo na reunião do Teams com a política de reunião do Teams. Você pode encontrar mais informações sobre as salas para sessão de grupo na Documentação do Teams.

Pré-requisitos

Somente usuários do Microsoft 365 com funções de organizador, co-organizador ou gerente de sala podem gerenciar as salas para sessão de grupo.

Suporte

As tabelas a seguir definem o suporte às salas para reunião de grupo nos Serviços de Comunicação do Azure.

Identidades e tipos de chamadas

A tabela a seguir mostra o suporte em salas para sessão de grupo para tipo de chamada e identidade específicos.

Identidades Reunião do Teams Sala Chamada 1:1 Chamada em grupo Chamada de interoperabilidade do Teams 1:1 Chamada de interoperabilidade de Grupo do Teams
Usuário dos Serviços de Comunicação ✔️
Usuário do Microsoft 365 ✔️

Operações

A tabela a seguir mostra o suporte para APIs individuais no SDK de chamadas relacionadas a tipos de identidade individuais.

Operações Usuário dos Serviços de Comunicação Usuário do Microsoft 365
Obter sala para sessão de grupo atribuída ✔️ ✔️
Obter todas as salas para sessão de grupo ✔️[1]
Ingressar na sala para sessão de grupo ✔️ ✔️
Gerenciar salas para sessão de grupo
Participar do chat da sala para sessão de grupo ✔️[2]
Obter configurações da sala para sessão de grupo ✔️ ✔️

[1] Apenas os usuários do Microsoft 365 com função de organizador, co-organizador ou gerente de sala.

[2] Os usuários do Microsoft 365 podem usar a API do Graph para participar do chat da sala para sessão de grupo. A ID da conversa de chat é fornecida no objeto da sala para sessão de grupo atribuída.

SDKs

As tabelas a seguir mostram o suporte para o recurso de salas para sessão de grupo nos SDKs individuais dos Serviços de Comunicação do Azure.

Status de suporte Web Interface do usuário da Web iOS Interface do usuário do iOS Android Interface do usuário do Android Windows
Tem suporte ✔️

Instalar o SDK

Use o comando npm install para instalar o SDK Comum e de Chamada dos Serviços de Comunicação do Azure para JavaScript:

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

Inicializar objetos necessários

Uma instância CallClient é necessária para a maioria das operações de chamada. Ao criar uma instância de CallClient, você pode configurá-la com opções personalizadas, como uma instância de Logger.

Com a instância de CallClient, você pode criar uma instância de CallAgent chamando o createCallAgent. Esse método retorna de modo assíncrono um objeto de instância CallAgent.

O método createCallAgent usa CommunicationTokenCredential como um argumento. Ele aceita um token de acesso do usuário.

Você pode usar o método getDeviceManager na instância CallClient para acessar o 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()

Como gerenciar melhor a conectividade do SDK com a infraestrutura da Microsoft

A instância Call Agent ajuda você a gerenciar chamadas (para ingressar ou iniciar chamadas). Para trabalhar, o SDK de chamada precisa se conectar à infraestrutura da Microsoft para receber notificações de chamadas de entrada e coordenar outros detalhes da chamada. O seu Call Agent tem dois estados possíveis:

Conectado: um valor connectionStatue Call Agent de Connected significa que o SDK do cliente está conectado e capaz de receber notificações da infraestrutura da Microsoft.

Desconectado: um valor connectionStatue Call Agent de Disconnected declara que há um problema que está impedindo o SDK de se conectar corretamente. Call Agent deve ser recriado.

  • invalidToken: se um token tiver expirado ou for inválido, a instância Call Agent se desconecta com este erro.
  • connectionIssue: se houver um problema com o cliente se conectando à infraestrutura da Microsoft, depois de muitas tentativas Call Agent expõe o erro connectionIssue.

Você pode verificar se o local Call Agent está conectado à infraestrutura da Microsoft inspecionando o valor atual da propriedade connectionState. Durante uma chamada ativa, você pode ouvir o evento connectionStateChanged para determinar se Call Agent muda do estado Conectado para 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);

Implementar salas para sessão de grupo

BreakoutRooms é um feature da classe Call. Primeiro, você precisa importar o pacote Features do SDK de Chamadas:

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

Criar o recurso breakoutRoom

Em seguida, obtenha o objeto da API de recurso da instância de chamada:

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

Assinar aos eventos breakoutRoom

A API BreakoutRooms permite que você assine os eventos BreakoutRooms. Um evento breakoutRoomsUpdated vem de uma instância BreakoutRoomsCallFeature e contém informações sobre as salas para sessão de grupo criadas, atualizadas e atribuídas.

Para receber informações sobre a sala para sessão de grupo, inscreva-se no evento breakoutRoomsUpdated.

breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Manipular eventos breakoutRoom

O evento breakoutRoomsUpdated fornece uma instância de uma das seguintes classes como um parâmetro de entrada. Você pode usar a propriedade type para distinguir entre os diferentes tipos de eventos.

  • Classe BreakoutRoomsEvent: Este evento é acionado quando um usuário com a função de organizador, co-organizador ou gerente de sala para sessão de grupo cria ou atualiza as salas para sessão de grupo. Usuários do Microsoft 365 com a função de organizador, co-organizador ou gerente de sala para sessão de grupo podem receber este tipo de evento. Os desenvolvedores podem usar essas salas para sessão de grupo na propriedade data para renderizar detalhes sobre todas elas. Essa classe tem uma propriedade type igual a "breakoutRooms".

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

  • Classe BreakoutRoomsSettingsEvent: Quando um usuário com a função de organizador, co-organizador ou gerente de sala para sessão de grupo atualiza as configurações da sala para sessão de grupo, isso aciona este evento. Os desenvolvedores podem usar estas informações para renderizar o tempo quando a sala para sessão de grupo termina ou decidir se devem renderizar um botão para ingressar na sala principal. Essa classe tem uma propriedade type igual a "breakoutRoomSettings".

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

  • Classe AssignedBreakoutRoomsEvent: esse evento é disparado quando os usuários são atribuídos a uma sala para sessão de grupo ou quando a sala para sessão de grupo atribuída é atualizada. Os usuários podem ingressar na sala para sessão de grupo quando a propriedade state estiver definida como open, sair da sala para sessão de grupo quando a propriedade state estiver definida como closed ou renderizar os detalhes da sala para sessão de grupo. Essa classe tem uma propriedade type igual a "assignedBreakoutRoom".

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

  • Classe JoinBreakoutRoomsEvent: Este evento é acionado quando o participante está ingressando em uma chamada de sala para sessão de grupo. Este evento pode ocorrer quando um usuário é movido automaticamente para a sala para sessão de grupo (ou seja, se assignedBreakoutRoom tiver a propriedade state definida como open e autoMoveParticipantToBreakoutRoom estiver definida como true) ou quando um usuário ingressa explicitamente em uma sala para sessão de grupo (ou seja, chama o método join na instância assignedBreakoutRoom quando autoMoveParticipantToBreakoutRoom estiver definida como false). A propriedade data contém a instância call da sala para sessão de grupo, que os desenvolvedores podem usar para controlar a chamada da sala. Essa classe tem uma propriedade type igual a "join".

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

O código a seguir mostra informações valiosas recebidas nos eventos da sala para sessão de grupo:

    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);

Listar salas para sessão de grupo disponíveis

Usuários do Microsoft 365 com função organizador, co-organizador ou gerente da sala para sessão de grupo podem acessar todas as salas para sessão de grupo.

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

Listar convites

Usuários do Microsoft 365 com as funções de organizador, co-organizador ou gerente de sala podem acessar os participantes atribuídos a salas de reunião individuais.

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

Ingressar na sala para sessão de grupo

Se assignedBreakoutRoom tiver a propriedade autoMoveParticipantToBreakoutRoom definida como true, os usuários são movido automaticamente para a sala quando a propriedade state estiver definida como open. Se autoMoveParticipantToBreakoutRoom estiver definida como false, use o seguinte código para ingressar na sala para sessão de grupo.

Isso dispara o evento breakoutRoomsUpdated com a classe JoinBreakoutRoomsEvent, que tem a propriedade type definida como join. Você pode usar a instância de uma classe call na propriedade data para gerenciar a chamada da sala para sessão de grupo.

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

Quando o usuário estiver em uma sala para sessão de grupo e o organizador atribuir uma nova sala para sessão de grupo ao usuário, ele receberá o evento breakoutRoomsUpdated com o tipo assignedBreakoutRooms. Esse evento conterá os detalhes mais recentes da sala para sessão de grupo. O usuário precisará hangUp() a chamada anterior da sala para sessão de grupo. Se autoMoveParticipantToBreakoutRoom estiver definido como true, o usuário será movido automaticamente, caso contrário, ele deverá chamar explicitamente o método join na nova sala para sessão de grupo.

//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();
}

Os usuários do Microsoft 365 com função de organizador, co-organizador ou gerente de sala para sessão de grupo receberão a lista de salas para sessão de grupo criadas pelo gerente de sala para sessão de grupo ou pelo organizador da reunião principal. Nesse caso, o comportamento será ligeiramente diferente. Esse usuário deverá chamar explicitamente o método join() para ingressar na sala para sessão de grupo. O usuário será mantido em espera na reunião principal inicialmente e, por fim, será removido da reunião principal. O usuário deverá inicializar o Recurso breakoutRooms para breakoutRoomCall a fim de receber atualizações sobre a sala para sessão de grupo.

Se o usuário quiser ingressar em uma das salas para sessão de grupo, ele deverá chamar explicitamente o método join.

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

Para sair de uma sala para sessão de grupo, os usuários deverão executar a função hangUp() na chamada da sala para sessão de grupo. O usuário deverá chamar ReturnToMainMeeting para retomar a chamada da reunião principal.

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

Sair da sala para sessão de grupo

Quando o estado da sala para sessão de grupo for closed, o usuário será informado sobre o fim da sala para sessão de grupo ao receber o evento breakoutRoomsUpdated com a classe AssignedBreakoutRoomsEvent e a propriedade type igual a assignedBreakoutRooms, que indicará que assignedBreakoutRoom tem a propriedade state definida como closed. O usuário sairá da sala para sessão de grupo automaticamente e poderá retornar à reunião principal chamando returnToMainMeeting() conforme mostrado acima.

Se o usuário quiser sair da sala para sessão de grupo mesmo antes de ela ser fechada e as configurações da sala para sessão de grupo breakoutRoomsFeature.breakoutRoomsSettings tiverem a propriedade disableReturnToMainMeeting definida como false, o usuário poderá retornar à chamada da reunião principal com o seguinte código:

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

Obter participantes da sala para sessão de grupo

Ao ingressar na sala para sessão de grupo, você pode usar o seguinte código para obter a lista de participantes remotos da sala:

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

Parar de receber eventos de salas para sessão de grupo

Usar o seguinte código para parar de receber eventos breakoutRooms.

breakoutRoomsFeature.off('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Propriedades da sala para sessão de grupo

As salas para sessão de grupo têm as seguintes propriedades:

Observação

O seguinte código de exemplo exibe eficientemente todas as propriedades da sala para sessão de grupo. Não se destina a ser reutilizado como mostrar. Na prática, você só usar as propriedades necessárias para o seu cenário da sala para sessão de grupo.

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;
Propriedades da sala para sessão de grupo Descrição
displayName Nome da sala para sessão de grupo. Esta propriedade é somente para leitura.
threadId Use a ID do chat conversa para ingressar no chat da sala para sessão de grupo. Esta propriedade é somente para leitura.
state Estado da sala para sessão de grupo. Pode ser open ou closed. Os usuários poderão ingressar na sala somente quando o estado for open. Esta propriedade é somente para leitura.
autoMoveParticipantToBreakoutRoom Valor booliano indicando se os usuários são movidos para salas para sessão de grupo automaticamente quando o state de assignedBreakoutRoom está definido para open. Esta propriedade é somente para leitura. Nas configurações da interface do usuário do Teams para salas para sessão de grupo, o organizador, co-organizador ou gerente da sala para sessão de grupo pode ajustar essa configuração específica. Ao definir esta opção para true, os participantes são transferidos automaticamente para a sala para sessão de grupo designada. Por outro lado, se você definir esta propriedade para false, então você deve chamar manualmente o método join para mover os participantes para a sala para sessão de grupo.
call Objeto de chamada da sala para sessão de grupo. Este objeto é retornado quando o usuário ingressa na chamada da sala para sessão de grupo automaticamente ou ao chamar o método join no objeto assignedBreakoutRoom. Esta propriedade é somente para leitura.
invitees A lista de convidados que estão atribuídos a sala para sessão de grupo. Esta propriedade é somente para leitura.

Configurações da sala para sessão de grupo

As salas para sessão de grupo compartilham configurações que têm as seguintes propriedades:

const disableReturnToMainMeeting : boolean = breakoutRoomsSettings.disableReturnToMainMeeting;
const roomEndTime : TimestampInfo = breakoutRoomsSettings.roomEndTime;
Propriedades da sala para sessão de grupo Descrição
disableReturnToMainMeeting Desabilitar participantes para devolução à reunião principal da chamada da sala para sessão de grupo. Esta propriedade é somente para leitura. Nas configurações de interface do usuário do Teams para salas de grupos, o organizador, coorganizador ou gerente da sala para sessão de grupo pode ajustar essa configuração específica para controlar quando os participantes das salas de grupos podem retornar à reunião principal.
roomEndTime Hora de término da sala para sessão de grupo definida pelo usuário do Microsoft 365 com função organizador, co-organizador ou gerente da reunião principal. Esta propriedade é somente para leitura.

Solução de problemas

Código do erro Subcódigo Categoria de resultado Motivo Resolução
400 46250 ExpectedError O recurso Salas para Sessão de Grupo só está disponível em reuniões do Teams. Implemente seu próprio mecanismo de sala para sessão de grupo ou use as reuniões do Teams.
405 46251 ExpectedError No momento, os Serviços de Comunicação do Azure desabilitaram esse recurso. Experimente as APIs em alguns dias.
500 46254 UnexpectedServerError Não foi possível ingressar na sala de reunião devido a um erro inesperado. Verifique se o state de assignedBreakoutRoom é open e chame o método breakoutRoomsFeature.assignedBreakoutRoom.join() explicitamente. Se o problema persistir, colete os logs do console do navegador e entre em contato com o suporte dos Serviços de Comunicação do Azure.
500 46255 UnexpectedServerError Não é possível realizar a reunião principal. Verifique se o state de assignedBreakoutRoom é open e chame o método breakoutRoomsFeature.assignedBreakoutRoom.join() explicitamente. Se o problema persistir, colete os logs do console do navegador e entre em contato com o suporte dos Serviços de Comunicação do Azure.
412 46256 ExpectedError Não foi possível ingressar na Sala para sessão de grupo, pois a sala está fechada. Verifique se o state de assignedBreakoutRoom é open e chame o método breakoutRoomsFeature.assignedBreakoutRoom.join() explicitamente.
412 46257 UnexpectedServerError Não foi possível retomar a reunião principal. Siga as instruções definidas na seção Leave breakout room para sair manualmente da sala para sessão de grupo. Se o problema persistir, colete os logs do console do navegador e entre em contato com o suporte dos Serviços de Comunicação do Azure.
412 46258 UnexpectedClientError Não é possível ler os detalhes da sala para sessão de grupo. Colete os logs do console do navegador e entre em contato com o suporte dos Serviços de Comunicação do Azure.
500 46259 UnexpectedServerError Não foi possível desligar a chamada da sala para sessão de grupo. Siga as instruções definidas na seção Leave breakout room para sair manualmente da sala para sessão de grupo.
412 46260 UnexpectedClientError Não é possível ingressar na Sala para sessão de grupo, pois ela ainda não foi atribuída. Verifique se breakoutRoomsFeature.assignedBreakoutRoom está contém os detalhes da sala para sessão de grupo atribuída. Verifique se o state de assignedBreakoutRoom é open e chame o método breakoutRoomsFeature.assignedBreakoutRoom.join() explicitamente.
412 46261 UnexpectedClientError Não será possível entrar na reunião principal. Tente novamente chamando o método breakoutRoomsFeature.assignedBreakoutRoom.returnToMainMeeting(). Se o problema persistir, colete os logs do console do navegador e entre em contato com o suporte dos Serviços de Comunicação do Azure.
412 46262 ExpectedError Já está na reunião principal. Chame esse método somente quando o participante estiver na sala para sessão de grupo e removido da reunião principal.
412 46263 UnexpectedClientError Falha ao encerrar a chamada da sala para sessão de grupo existente. Tente chamar o método hangup() novamente para encerrar a chamada. Chame o método join() para entrar na sala para sessão de grupo novamente.

Próximas etapas