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

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

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Um recurso de Serviços de Comunicação implantado. Crie um recurso de Serviços de Comunicação.
• A User Access Token para habilitar o cliente de chamada. Para 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

Instale o SDK

Use o npm install comando 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 CallClient instância para iniciar a pilha de chamadas. Você pode configurar o registro em log do SDK de chamada com a instância e setLogLevel o AzureLogger método. Você pode obter acesso ao deviceManager sistema operacional com o método getDeviceManager.

Em seguida, use o método createTeamsCallAgent para criar de forma assíncrona uma TeamsCallAgent instância 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 individual ou de grupo síncrona com startCall a API ativada teamsCallAgent. Você pode fornecer MicrosoftTeamsUserIdentifier ou PhoneNumberIdentifier como um parâmetro para definir o destino da chamada. O método retorna a TeamsCall instância que permite que você se inscreva para eventos de chamada.

Nota

Inicie uma chamada em grupo com teamsCallAgent o método requer bate-papo ao threadId ligar startCall . A instância criada TeamsCall tem propriedade threadId capturando esse thread. O SDK de Chamada dos Serviços de Comunicação não mantém os participantes no chat e na lista de chamadas sincronizados. A Microsft incentiva os desenvolvedores a manter a lista sincronizada para a melhor experiência do usuário. Saiba como gerenciar o tópico de bate-papo.

Inicie uma chamada de Voz sobre IP (VoIP) 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 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 (Voice-over 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>' });

Participe de uma chamada

Participar numa reunião do Teams

Você pode participar de reuniões do Teams com o método join na teamsCallAgent instância. Os usuários do Teams podem participar da reunião do Teams fornecendo um TeamsMeetingLinkLocator, TeamsMeetingCoordinatesLocatorou TeamsMeetingIdLocator.

Participar na reunião do Teams com o URL da reunião:

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

Participar na reunião do Teams com a combinação de ID de thread, ID de organizador, ID de inquilino e ID de mensagem:

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

Participar na reunião do Teams com o código e o código de acesso da reunião:

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

Participar na reunião do Teams com ID de reunião e código de acesso:

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

• Formato do ID e código de acesso da reunião:

  • ID da reunião: 12 dígitos.
  • Código de acesso: 6 caracteres

• Com que frequência precisa de atualizar o ID e o código de acesso da reunião?

  • O ID da reunião e o código de acesso não mudam depois de criados. Os desenvolvedores não precisam atualizar nenhum deles.
  • Um organizador de reunião do Teams não pode gerar novamente a ID e a senha da reunião.

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

  • Não, os participantes terão a mesma experiência se participarem numa reunião do Teams utilizando o URL da reunião do Teams ou o ID e código de acesso da reunião.

• Como os desenvolvedores devem armazenar e gerenciar senhas?

  • ID da reunião e código de acesso são coordenadas para participar da reunião. Os desenvolvedores devem tratá-los como segredos, que devem ser criptografados e, se armazenados, certifique-se de que estão em um ambiente de acesso controlado.
  • Se as coordenadas forem expostas, qualquer pessoa pode participar da reunião e arruinar a experiência para todos na reunião.

• Como obter o ID e o código de acesso da reunião?

  1. Graph API: use a Graph API para recuperar informações sobre onlineMeeting o recurso e verificar o objeto na propriedade joinMeetingIdSettings.
  2. Equipas: na aplicação Teams, aceda à aplicação e abra os Calendar detalhes de uma reunião. As reuniões online têm ID de reunião e código de acesso na definição da reunião.
  3. Outlook: Você pode encontrar a ID da reunião e a senha em eventos do calendário ou em convites para reuniões por email.
  4. Os desenvolvedores não podem recuperar a ID da reunião e a senha por meio do SDK de chamada ou recuperá-la de logs detalhados do console.

• Como posso verificar se o ID da reunião e o código de acesso estão corretos?

  • A verificação do MeetingId e da senha pode ser feita através de: https://www.microsoft.com/en-us/microsoft-teams/join-a-meeting.

Receber uma chamada recebida do Teams

Você pode se inscrever no incomingCall evento na teamsCallAgent instância para registrar chamadas recebidas para o usuário do Teams. O evento tem uma teamsIncomingCall propriedade com TeamsIncomingCall instância 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);

Ativar e desativar vídeo

Você pode obter sua coleção de fluxo de vídeo local da propriedade localVideoStreams na TeamsCall instância. Se habilitada, a coleção contém um fluxo de compartilhamento de tela e feeds de vídeo da câmera. Você pode 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 som

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

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

Silenciar outros participantes

Para silenciar todos os outros participantes ou silenciar um participante específico, você pode usar 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();

Nota

Esta API é fornecida como uma pré-visualização para os programadores e pode alterar-se com base nos comentários que recebermos. Não utilize esta API num ambiente de produção. Para usar essa api, use a versão 'beta' do SDK da Web de Chamada dos Serviços de Comunicação do Azure

Gerenciar participantes remotos

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

Nota

Adicionar um método de participante requer chat's threadId. O SDK de Chamada dos Serviços de Comunicação não mantém os participantes no chat e na lista de chamadas sincronizados. A Microsft incentiva os desenvolvedores a manter a lista sincronizada para a melhor experiência do usuário. Saiba como gerenciar o tópico de bate-papo.

Você pode adicionar um novo usuário ou número de telefone do Teams à chamada 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 TeamsCall instância.

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

Listar outros participantes da chamada:

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

Adicione o usuário e o número de telefone do Teams à chamada 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>' });

Remova o usuário e o número de telefone do Teams da chamada 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 ou reunião do Teams em andamento. A classe remoteParticipant tem o seguinte conjunto de propriedades e coleções:

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

const identifier = remoteParticipant.identifier;

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

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

Estados dos participantes remotos em chamadas individuais ou em grupo:

Estados dos participantes remotos nas reuniões do Teams:

const state = remoteParticipant.state;

• callEndReason: Retorna um objeto contendo 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, consulte 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 Boolean o valor que representa um status de mudo local.

const isMuted = remoteParticipant.isMuted;

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

const isSpeaking = remoteParticipant.isSpeaking;

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

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

• displayName: Devolve um string nome de apresentação representativo. O SDK de chamada dos Serviços de Comunicação não define esse valor para os usuários do Teams.

const displayName = remoteParticipant.displayName;

Chamada

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

const callId = call.id;

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

Nota

Esta API é fornecida como uma pré-visualização para os programadores e pode alterar-se com base nos comentários que recebermos. Não utilize esta API num ambiente de produção. Para usar essa API, use a versão 'beta' do SDK da Web de Chamada dos Serviços de Comunicação do Azure

info• : Retorna objeto contendo informações sobre a chamada. A propriedade threadId é uma cadeia de caracteres que representa o ID de thread do chat mostrado no cliente do Teams.

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

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

const remoteParticipants = call.remoteParticipants;

callerInfo• : Retorna o CallerInfo objeto para chamadas recebidas. A propriedade identifier pode ser um dos seguintes objetos CommunicationUserIdentifier, , PhoneNumberIdentifierMicrosoftTeamsUserIdentifier, 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• : Devolve uma cadeia de caracteres que representa o estado da chamada. A propriedade pode ter um dos seguintes valores:

Valor do estado	Quando	Description
None	Estado inicial	O estado inicial da chamada.
Connecting	Após None	O estado em que uma chamada ou reunião do Teams é feita, ingressada ou aceita.
Ringing	Após Connecting	O participante remoto recebeu o evento ou o incomingCall cliente do Teams está tocando.
EarlyMedia	Após Ringing ou Connecting	A mídia é reproduzida antes que a chamada seja conectada.
Connected	Depois de Ringing, EarlyMedia, InLobby, LocalHold, e RemoteHold	A chamada está ligada. A mídia está fluindo entre pontos finais locais e participantes remotos.
LocalHold	Após Connected	A chamada foi suspensa por um participante local. Nenhuma mídia está fluindo entre o ponto de extremidade local e os participantes remotos.
RemoteHold	Após Connected	A chamada foi suspensa 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	Depois de qualquer estado	O estado de transição antes da chamada ir para um Disconnected estado.
Disconnected	Estado final	O estado final da chamada. Se a conexão de rede for perdida, o estado muda para Disconnected após dois minutos.

Estados para chamadas individuais ou em grupo:

Estados para reuniões de Equipas:

const callState = call.state;

callEndReason• : Retorna objeto CallEndReason contendo informações adicionais sobre a chamada encerrada. 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, consulte 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• : Devolve um string que representa a direção da chamada. A propriedade pode ter um dos seguintes valores: "Incoming" ou Outgoing.

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

isMuted• : Devolve Boolean o valor que representa um estado de mudo local.

const muted = call.isMuted;

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

const isScreenSharingOn = call.isScreenSharingOn;

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

const localVideoStreams = call.localVideoStreams;

Gerenciar thread de bate-papo

Importante

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

Fornecer um ID de chat é opcional para fazer chamadas em grupo e adicionar participantes a chamadas existentes. O chat e a chamada associados têm uma lista separada de participantes. Antes de adicionar participantes à chamada, adicione o usuário ao bate-papo para fornecer a melhor experiência do usuário e satisfazer os requisitos de barreira de informações. Adicionar um usuário à chamada sem adicionar o usuário ao bate-papo pode resultar em exceções se uma barreira de informações for configurada.

Considere o seguinte cenário, onde Alice faz uma chamada para Bob, então Alice adiciona Charlie e, 3 minutos depois, Alice remove Charlie da chamada.

1. Crie um tópico de bate-papo entre Alice, Bob e Charlie. Mantenha o chat threadId para mais tarde.
2. Alice liga para Bob e Charlie usando startCall método na TeamsCallAgent instância.
3. Adicionar Dan ao tópico de bate-papo usando threadId a API do Chat Graph para adicionar membro
4. Alice adiciona Dan à chamada usando addParticipant o método on call e especifica o threadId
5. Alice remove Dan da chamada usando removeParticipant o método on call e especifica o threadId
6. Remova Dan do tópico de bate-papo usando threadId a API do Chat Graph para remover membros

Se o usuário do Teams parar a gravação de chamadas, a gravação será colocada no bate-papo associado ao thread. O ID de chat fornecido afeta a experiência dos usuários do Teams em clientes do Teams.

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

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

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

• Inicie uma chamada em grupo com um único usuário do Microsoft 365 e vários participantes do telefone:
  • A API do método startCall permite que você inicie uma chamada em grupo com vários participantes e, opcionalmente, forneça o ID do bate-papo. Se o parâmetro não for fornecido, um novo chat de 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 contínua associada a esse bate-papo em grupo no aplicativo Teams. Você pode criar um novo bate-papo em grupo via Graph API.

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

  • Use a API do Graph para obter o ID de bate-papo existente apenas com o usuário do Teams como participante ou crie um novo bate-papo em grupo com os participantes: ID de usuário do Teams e "00000000-0000-0000-000000000000000".
• Inicie uma chamada em grupo com mais de 2 utilizadores do Microsoft 365:
  • (Forma opcional) Ao fazer uma chamada em grupo com mais de 2 usuários do Microsoft 365 usando o ACS Calling SDK, 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 SDK de Chamada do ACS usará a ID de chat fornecida para criar a chamada de grupo. Um thread de bate-papo é 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 threads de bate-papo pode ser feito via Graph API