Gerenciar chamadas para usuários do Teams com o SDK de chamada dos Serviços de Comunicação

Saiba como gerenciar chamadas com os SDKs dos Serviços de Comunicação do Azure. Vamos aprender como fazer chamadas, gerenciar seus participantes e propriedades.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Um recurso dos Serviços de Comunicação implantado. Crie um recurso dos Serviços de Comunicação.
• Um User Access Token para habilitar o cliente de chamada. Para obter mais informações sobre como obter um User Access Token
• Opcional: conclua o guia de início rápido para começar a adicionar chamadas de vídeo ao seu aplicativo

Instalar o SDK

Use o comando npm install para instalar a chamada dos Serviços de Comunicação do Azure e SDKs comuns para JavaScript.

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

Inicializar objetos necessários

Crie uma instância CallClient para iniciar a pilha de chamadas. Você pode configurar o registro em log do SDK de chamada com a instância AzureLogger e o método setLogLevel. Você pode obter acesso a deviceManager para o sistema operacional com o método getDeviceManager.

Em seguida, use o método createTeamsCallAgent para criar de forma assíncrona uma instância TeamsCallAgent que gerenciará chamadas de entrada e saída para um usuário do Teams. O método usa CommunicationTokenCredential como um argumento que representa o token de acesso para o usuário do Teams.

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 wherever desired. To console, file, buffer, REST API, etc...
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient();
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const teamsCallAgent = await callClient.createTeamsCallAgent(tokenCredential);
const deviceManager = await callClient.getDeviceManager();

Fazer uma chamada

Inicie uma chamada síncrona individual ou em grupo com a API startCall em teamsCallAgent. Você pode fornecer MicrosoftTeamsUserIdentifier ou PhoneNumberIdentifier como um parâmetro para definir o destino da chamada. O método retorna a instância TeamsCall que permite que você assine eventos de chamada.

Observação

Iniciar uma chamada em grupo com teamsCallAgent requer chat's threadId ao chamar o método startCall. A instância TeamsCall criada tem propriedade threadId capturando esse thread. O SDK de Chamadas dos Serviços de Comunicação não mantém os participantes no chat e n lista de chamadas sincronizada. A Microsft recomenda que os desenvolvedores mantenham a lista sincronizada para obter a melhor experiência do usuário. Saiba como gerenciar conversas de chat.

Inicie uma chamada VoIP (voz sobre IP) individual para o usuário do Teams:

const userCallee = { microsoftTeamsUserId: '<MICROSOFT_TEAMS_USER_ID>' };
const oneToOneCall = teamsCallAgent.startCall(userCallee);

Inicie uma chamada telefônica individual para o número de telefone do E.164:

const phoneCallee = { phoneNumber: '<PHONE_NUMBER_E164_FORMAT>' }
const oneToOneCall = teamsCallAgent.startCall(phoneCallee );

Inicie uma chamada em grupo para o usuário do Teams com VoIP (voz sobre IP) e número de telefone:

const userCallee = { microsoftTeamsUserId: '<MICROSOFT_TEAMS_USER_ID>' }
const phoneCallee = { phoneNumber: '<PHONE_NUMBER_E164_FORMAT>'};
const groupCall = teamsCallAgent.startCall([userCallee, phoneCallee], { threadId: '<THREAD_ID>' });

Ingressar em uma chamada

Ingressar em uma reunião do Teams

Você pode ingressar em reuniões do Teams com o método join na instância teamsCallAgent. Os usuários do Teams podem ingressar na reunião do Teams fornecendo um TeamsMeetingLinkLocator, TeamsMeetingCoordinatesLocator ou TeamsMeetingIdLocator.

Ingressar na reunião do Teams com a URL da reunião:

const meetingCall = teamsCallAgent.join({ meetingLink: '<MEETING_LINK>' });

Ingresse na reunião do Teams com a combinação de ID da conversa, ID do organizador, ID do locatário e ID da mensagem:

const meetingCall = teamsCallAgent.join({ threadId: '<THREAD_ID>', organizerId: '<ORGANIZER_ID>', tenantId: '<TENANT_ID>', messageId: '<MESSAGE_ID>' });

Participe da reunião do Teams com código de reunião e senha:

const meetingCall = teamsCallAgent.join({ meetingId: '<MEETING_CODE>', passcode: '<PASSCODE>'});

Participe da reunião do Teams com a ID e a senha da reunião:

Os desenvolvedores podem conectar os participantes a uma reunião do Teams de várias maneiras. Uma maneira é usar uma ID e senha da reunião, que permite que as pessoas participem da reunião do Teams para a qual são convidadas de um dispositivo ou aplicativo. Você sempre precisa fornecer a ID da reunião e a senha para ingressar na reunião. A senha diferencia maiúsculas de minúsculas.

• Formato da ID e da senha da reunião:

  • ID da reunião: 12 dígitos.
  • Senha: 6 caracteres

• Com que frequência você precisa atualizar a ID a senha da reunião?

  • Depois de criada, a ID e a senha da reunião não serão alteradas. Os desenvolvedores não precisam atualizar nenhuma das duas.
  • O organizador do Teams não pode gerar novamente a ID e a senha da reunião.

• Há alguma diferença em uma experiência de reunião do Teams se uma pessoa ingressar por meio do URL ou da ID e senha da reunião?

  • Não, os participantes terão a mesma experiência se ingressarem em uma reunião do Teams usando o URL de reunião do Teams ou a ID e senha da reunião.

• Como os desenvolvedores devem armazenar e gerenciar as senhas?

  • A ID da reunião e a senha são coordenadas para ingressar na reunião. Os desenvolvedores devem tratá-las como segredos, que devem ser criptografados e, se armazenados, verifique se estão em um ambiente com acesso controlado.
  • Se as coordenadas forem expostas, qualquer pessoa poderá participar da reunião e arruinar a experiência de todos na reunião.

• Como obter a ID e a senha da reunião?

  1. API do Graph: use a API do Graph para recuperar informações sobre o recurso onlineMeeting e verificar o objeto na propriedade joinMeetingIdSettings.
  2. Teams: em seu aplicativo do Teams, acesse o aplicativo Calendar e abra os detalhes de uma reunião. As reuniões online têm ID e senha na definição da reunião.
  3. Outlook: encontre a ID e senha da reunião nos eventos de calendário ou nos convites de reunião por email.
  4. Os desenvolvedores não podem recuperar a ID e a senha da reunião por meio da chamada do SDK ou recuperá-las de logs de console detalhados.

• Como posso verificar se a ID e a senha da reunião estão corretas?

  • A verificação de MeetingId e senha pode ser feita por meio de: https://www.microsoft.com/en-us/microsoft-teams/join-a-meeting.

Receber uma chamada de entrada do Teams

Você pode assinar o evento incomingCall na instância teamsCallAgent para registrar chamadas de entrada para o usuário do Teams. O evento tem uma propriedade teamsIncomingCall com uma instância TeamsIncomingCall que permite que você accept ou reject a chamada de entrada.

const incomingCallHandler = async (args: { teamsIncomingCall: TeamsIncomingCall }) => {
    const incomingCall = args.teamsIncomingCall;
    // Get Teams incoming call ID
    const incomingCallId = incomingCall.id;
    // Get information about this Call. This API is provided as a preview for developers
    // and may change based on feedback that we receive. Do not use this API in a production environment.
    // To use this API please use 'beta' release of Azure Communication Services Calling Web SDK
    const callInfo = incomingCall.info;
    // Get information about caller
    const callerInfo = incomingCall.callerInfo
    // Accept the call
    const teamsCall = await incomingCall.accept();
    // Reject the call
    incomingCall.reject();
    // Subscribe to callEnded event and get the call end reason
    incomingCall.on('callEnded', args => {
        console.log(args.callEndReason);
    });
    // callEndReason is also a property of IncomingCall
    var callEndReason = incomingCall.callEndReason;
};
teamsCallAgent.on('incomingCall', incomingCallHandler);

Habilitar e desabilitar o vídeo

Você pode obter sua coleção de fluxo de vídeo local da propriedade localVideoStreams na instância TeamsCall. Se habilitada, a coleção conterá um fluxo de compartilhamento de tela e feeds de vídeo da câmera. É possível obter fluxos de vídeo de participantes remotos inspecionando a propriedade TeamsCall.remoteParticipants onde cada participante tem uma coleção de fluxos de vídeo na propriedade videoStreams.

Ativar e desativar mudo

Você pode usar as APIs assíncronas mute e unmute na instância TeamsCall para ativar ou desativar o mudo de usuários do Teams localmente. O mudo local impedirá que o áudio seja enviado para outros participantes.

//mute local device
await call.mute();
//unmute local device
await call.unmute();

Ativar mudo para outros participantes

Para ativar mudo de todos os outros participantes ou ativar mudo de um participante específico, use as APIs muteAllRemoteParticipants assíncronas na chamada e mute no participante remoto:

//mute all participants except yourself
await call.muteAllRemoteParticipants();

//mute a specific participant
await call.remoteParticipants[0].mute();

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção. Para usar essa API, use a versão beta do SDK de chamadas da Web dos Serviços de Comunicação do Azure

Gerenciar participantes remotos

Outros participantes da chamada estão disponíveis na instância TeamsCall na propriedade remoteParticipants. É uma coleção de objetos RemoteParticipant. Você pode listar, adicionar e remover outros participantes da chamada.

Observação

A adição de um método de participante requer chat's threadId. O SDK de Chamadas dos Serviços de Comunicação não mantém os participantes no chat e n lista de chamadas sincronizada. A Microsft recomenda que os desenvolvedores mantenham a lista sincronizada para obter a melhor experiência do usuário. Saiba como gerenciar conversas de chat.

Você pode adicionar um novo usuário do Teams ou número de telefone à chamada do Teams ou à reunião do Teams chamando o método addParticipant no objeto TeamsCall. O método aceita identificadores MicrosoftTeamsUserIdentifier ou PhoneNumberIdentifier como entrada e retorna de forma síncrona a instância de RemoteParticipant e dispara o evento remoteParticipantsUpdated na instância TeamsCall.

É possível remover um participante da chamada do Teams ou da reunião do Teams invocando o método removeParticipant na instância TeamsCall de forma assíncrona. O método aceita identificadores MicrosoftTeamsUserIdentifier ou PhoneNumberIdentifier como uma entrada. O método é resolvido quando RemoteParticipant é removido da coleção remoteParticipants e o evento remoteParticipantsUpdated na instância TeamsCall é disparado.

Listar outros participantes da chamada:

const participants = call.remoteParticipants; // [remoteParticipant, remoteParticipant....]

Adicionar um usuário do Teams e um número de telefone à chamada do Teams ou à reunião do Teams:

const teamsUser = { microsoftTeamsUserId: '<MICROSOFT_TEAMS_USER_ID>' };
const phoneUser = { phoneNumber: '<PHONE_NUMBER_E164_FORMAT>' }
const remoteParticipant = call.addParticipant(teamsUser , { threadId: '<THREAD_ID>' });
const remoteParticipant2 = call.addParticipant(phoneUser , { threadId: '<THREAD_ID>' });

Remover um usuário do Teams e um número de telefone da chamada do Teams ou da reunião do Teams:

const teamsUser = { microsoftTeamsUserId: '<MICROSOFT_TEAMS_USER_ID>' };
const phoneUser = { phoneNumber: '<PHONE_NUMBER_E164_FORMAT>' }
await call.removeParticipant(teamsUser);
await call.removeParticipant(phoneUser);

Participantes remotos

Os participantes remotos representam um ponto de extremidade conectado à chamada em andamento do Teams ou à reunião do Teams. A classe remoteParticipant tem o seguinte conjunto de propriedades e coleções:

• identifier: retorna um dos seguintes identificadores: CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifier ou UnknownIdentifier.

const identifier = remoteParticipant.identifier;

• state: retorna um string que representa um estado de um participante remoto. O estado pode ter um dos seguintes valores:

Valor de estado	Quando	Descrição
Idle	Estado inicial	Este é o primeiro estado do participante
Connecting	Depois Idle	Estado de transição enquanto um participante está se conectando à chamada.
Ringing	Depois Connecting	O participante recebeu uma notificação incomingCall ou o cliente do Teams está tocando
Connected	Após Ringing, Connecting, EarlyMedia ou InLobby	O participante aceitou o convite da chamada ou ingressou na chamada. A mídia flui em direção ao participante.
Hold	Depois Connected	O participante da chamada está em espera.
EarlyMedia	Depois Connecting	A mídia é reproduzida antes que um participante se conecte à chamada
InLobby	Após Ringing, Connecting ou EarlyMedia	O participante está no lobby da reunião do Teams.
Disconnected	Estado final	O participante está desconectado da chamada. Se o participante remoto perder sua conectividade de rede, seu estado mudará para Disconnected depois de dois minutos.

Estados de participantes remotos em chamadas individuais ou em grupo:

Estados de participantes remotos em reuniões do Teams:

const state = remoteParticipant.state;

• callEndReason: retorna um objeto que contém informações adicionais sobre o motivo pelo qual a chamada terminou. A propriedade code retorna um número associado ao motivo e subCode retorna um número associado ao código e ao motivo. Para obter mais informações sobre códigos de erro, confira Solução de problemas de códigos de resposta de fim de chamada.

const callEndReason = remoteParticipant.callEndReason;
const callEndReasonCode = callEndReason.code
const callEndReasonSubCode = callEndReason.subCode

• isMuted: retorna o valor Boolean que representa um status de mudo local.

const isMuted = remoteParticipant.isMuted;

• isSpeaking: retorna o valor Boolean que representa o status do áudio não vazio que está sendo enviado.

const isSpeaking = remoteParticipant.isSpeaking;

• videoStreams: retorna a coleção de objetos RemoteVideoStream enviados pelos participantes.

const videoStreams = remoteParticipant.videoStreams; // [RemoteVideoStream, ...]

• displayName: retorna um string que representa o nome de exibição. Os Serviços de Comunicação que chamam o SDK não definem esse valor para os usuários do Teams.

const displayName = remoteParticipant.displayName;

Chamar

• id: retorna uma cadeia de caracteres que representa um identificador de chamada exclusivo.

const callId = call.id;

• info: retorna informações sobre a chamada:

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção. Para usar essa API, use a versão beta do SDK de chamadas da Web dos Serviços de Comunicação do Azure

• info: retorna um objeto que contém informações sobre a chamada. A propriedade threadId é uma cadeia de caracteres que representa a ID da conversa do chat mostrada no cliente do Teams.

const callInfo = call.info;
const threadId = call.info.threadId;

• remoteParticipants: retorna uma coleção de objetos remoteParticipant que representam outros participantes na chamada do Teams ou na reunião do Teams.

const remoteParticipants = call.remoteParticipants;

• callerInfo: retorna o objeto CallerInfo para chamadas de entrada. A propriedade identifier pode ser um dos seguintes objetos CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifier ou UnknownIdentifier. A propriedade displayName é uma cadeia de caracteres que representa o nome a ser exibido, se definido.

const callerIdentity = call.callerInfo.identifier;
const callerIdentity = call.callerInfo.displayName;

• state: retorna uma cadeia de caracteres que representa o estado da chamada. A propriedade pode ter um dos seguintes valores:

Valor de estado	Quando	Descrição
None	Estado inicial	O estado inicial da chamada.
Connecting	Depois None	O estado quando uma chamada do Teams ou uma reunião do Teams é colocada, ingressada ou aceita.
Ringing	Depois Connecting	O participante remoto recebeu o evento incomingCall ou o cliente do Teams está tocando.
EarlyMedia	Após Ringing ou Connecting	A mídia é reproduzida antes da chamada ser conectada.
Connected	Após Ringing, EarlyMedia, InLobby, LocalHold e RemoteHold	A chamada está conectada. A mídia está fluindo entre os pontos de extremidade locais e os participantes remotos.
LocalHold	Depois Connected	A chamada foi colocada em espera por um participante local. Nenhuma mídia está fluindo entre o ponto de extremidade local e os participantes remotos.
RemoteHold	Depois Connected	A chamada foi colocada em espera por um participante remoto. Nenhuma mídia está fluindo entre o ponto de extremidade local e os participantes remotos.
InLobby	Após Ringing ou Connecting	O participante remoto está no lobby da reunião do Teams. Nenhuma mídia está fluindo entre o ponto de extremidade local e os participantes remotos.
Disconnecting	Após qualquer estado	O estado de transição antes que a chamada vá para um estado Disconnected.
Disconnected	Estado final	O estado final da chamada. Se a conexão de rede for perdida, o estado será alterado para Disconnected depois de dois minutos.

Estados de chamadas individuais ou em grupo:

Estados de reuniões do Teams:

const callState = call.state;

• callEndReason: retorna um objeto CallEndReason que contém informações adicionais sobre a chamada terminada. A propriedade code retorna um número associado ao motivo e subCode retorna um número associado ao código e ao motivo. Para obter mais informações sobre códigos de erro, confira Solução de problemas de códigos de resposta de fim de chamada.

const callEndReason = call.callEndReason;
const callEndReasonCode = callEndReason.code
const callEndReasonSubCode = callEndReason.subCode

• direction: retorna um string que representa a direção da chamada. A propriedade pode ter um dos seguintes valores: "Entrada' ou Outgoing.

const isIncoming = call.direction == 'Incoming';
const isOutgoing = call.direction == 'Outgoing';

• isMuted: retorna o valor Boolean que representa um status de mudo local.

const muted = call.isMuted;

• isScreenSharingOn: retorna o valor Boolean verdadeiro se você estiver enviando fluxo de compartilhamento de tela para outros participantes.

const isScreenSharingOn = call.isScreenSharingOn;

• localVideoStreams: retorna uma coleção de objetos LocalVideoStream, representando fluxos de vídeo sendo enviados para participantes remotos.

const localVideoStreams = call.localVideoStreams;

Gerenciar a conversa de chat

Importante

O ID de chat opcional só está disponível na versão 1.29.1 ou posterior do Calling SDK para JavaScript. Se você estiver usando uma versão anterior, certifique-se de fornecer manualmente um ID de chat exclusivo.

É obrigatório fornecer uma ID de chat para fazer chamadas em grupo e adicionar participantes às chamadas existentes. O chat e a chamada associados têm uma lista diferente de participantes. Antes de adicionar participantes à chamada, adicione o usuário ao chat para fornecer a melhor experiência e atender aos requisitos de barreira de informações. Se você adicionar um usuário à chamada sem adicioná-lo ao chat, poderá causar exceções se uma barreira de informações estiver configurada.

Considere o cenário a seguir, em que a Alice faz uma chamada para o Bob, em seguida, a Alice adiciona o Carlos e, três minutos depois, a Alice remove o Carlos da chamada.

1. Crie uma conversa entre Alice, Bob e Charlie. Salve o chat threadId para mais tarde.
2. Alice chama Bob e Charlie usando o método startCall na instância TeamsCallAgent.
3. Adicionar Dan à conversa de chat com threadId usando a API do Graph para Chat para adicionar membro
4. A Alice adiciona o Dan à chamada usando o método addParticipant em call e especifica o threadId
5. A Alice remove o Dan da chamada usando o método removeParticipant em call e especifica o threadId
6. Remover Dan da conversa de chat com threadId usando a API do Graph para Chat para remover membro

Se o usuário do Teams parar a gravação de chamada, a gravação será colocada no chat associado à conversa. A ID de chat fornecida afeta a experiência de usuários do Teams em clientes do Teams.

Recomendações para o gerenciamento da ID de chat:

• Escalonamento da chamada telefônica individual adicionando outro participante do telefone:
  • O método addParticipant permite que você forneça o ID do chat do parâmetro opcional. Se o parâmetro não for fornecido, um novo chat em grupo será criado e todos os participantes serão adicionados à lista de participantes da chamada e do chat. Se o parâmetro for fornecido, os usuários do Teams poderão ver a chamada em andamento associada a esse chat de grupo no aplicativo Teams. Você pode criar um novo chat em grupo por meio da API do Graph.

    addParticipant(participant: MicrosoftTeamsUserIdentifier | PhoneNumberIdentifier | MicrosoftTeamsAppIdentifier | UnknownIdentifier)
    

• Inicie a chamada em grupo com um único usuário do Microsoft 365 e vários participantes do telefone:
  • Método *startCall API permite que você inicie uma chamada em grupo com vários participantes e, opcionalmente, forneça o ID do chat. Se o parâmetro não for fornecido, um novo chat em grupo será criado e todos os participantes do Microsoft 365 serão adicionados à lista de participantes de chamada e chat. Se o parâmetro for fornecido, os usuários do Teams poderão ver a chamada em andamento associada a esse chat de grupo no aplicativo Teams. Você pode criar um novo chat em grupo por meio da API do Graph.

    startCall(MicrosoftTeamsUserIdentifier | PhoneNumberIdentifier | MicrosoftTeamsAppIdentifier | UnknownIdentifier)[])
    

  • Use a API do Graph para obter a ID de chat existente apenas com o usuário do Teams como participante ou criar um novo chat em grupo com os participantes: ID de usuário do Teams e "00000000-0000-0000-0000-000000000000".
• Inicie a chamada em grupo com mais de dois usuários do Microsoft 365:
  • (Modo opcional) Ao fazer uma chamada em grupo com mais de dois usuários do Microsoft 365 usando o SDK de Chamada do ACS, o SDK criará automaticamente o thread por padrão.

    startCall(MicrosoftTeamsUserIdentifier | PhoneNumberIdentifier | MicrosoftTeamsAppIdentifier | UnknownIdentifier)[])
    

  • Se desejar, o desenvolvedor pode fornecer um ID de chat exclusivo para iniciar a chamada em grupo ou adicionar participantes. Nesse caso, o ACS Calling SDK usará o ID de chat fornecido para criar a chamada em grupo. Um thread de chat é criado para os usuários do Teams e esse thread é associado à chamada de grupo para usuários no aplicativo Teams. Isso permite que eles conversem durante a chamada. O gerenciamento de thread de chat pode ser feito por meio da API do Graph