Compartilhar via

Transferir e encaminhar chamadas

  • Artigo

Durante uma chamada ativa, pode querer transferir a chamada para outra pessoa, número ou para o correio de voz. Vamos aprender como.

Pré-requisitos

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

A transferência de chamadas é um recurso estendido da API Call principal. Primeiro, você precisa importar recursos de chamada do SDK de Chamada:

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

Em seguida, você pode obter o objeto de API de recurso de transferência da instância de chamada:

const callTransferApi = call.feature(Features.Transfer);

As transferências de chamada envolvem três partes:

  • Emitente da transferência : Aquele que inicia a solicitação de transferência.
  • Destino de transferência: a pessoa que está sendo transferida.
  • Destino da transferência: a pessoa que está sendo transferida.

Transferir para o participante:

  1. Já existe uma chamada conectada entre o emitente da transferência e o destinatário da transferência. O emitente da transferência decide transferir a chamada do transferida para o destino de transferência.
  2. O emitente da transferência chama a transfer API.
  3. Odestino de transferência recebe uma chamada de entrada somente se odestinatário da transferência aceitar a solicitação de transferência.

Para transferir uma chamada atual, você pode usar a API transfer. O transfer usa o transferCallOptions opcional, que permite que você defina um sinalizador disableForwardingAndUnanswered:

  • disableForwardingAndUnanswered = false: Se o destino da transferência não responder à chamada de transferência, a transferência segue as configurações não respondidas e de encaminhamento do destino de transferência.
  • disableForwardingAndUnanswered = true: Se o destino da transferência não responder à chamada de transferência, a tentativa de transferência se encerra.
// transfer target can be an Azure Communication Services user
const id = { communicationUserId: <ACS_USER_ID> };

// call transfer API
const transfer = callTransferApi.transfer({targetParticipant: id});

Transferir para a chamada:

  1. Já existe uma chamada conectada entre o emitente da transferência e o destinatário da transferência.
  2. Já existe uma chamada conectada entre o emitente da transferência e o destino da transferência.
  3. O emitente da transferência decide transferir a chamada do destinatário da transferência para o destino de transferência.
  4. O emitente da transferência chama a transfer API.
  5. Odestino de transferência recebe uma chamada de entrada somente se odestinatário da transferência aceitar a solicitação de transferência.

Para transferir uma chamada atual, você pode usar a API transfer.

// transfer to the target call specifying the call id
const id = { targetCallId: <CALL_ID> };

// call transfer API
const transfer = callTransferApi.transfer({ targetCallId: <CALL_ID> });

A API transfer permite que você assine stateChanged. Ela também vem com uma transferência state e propriedades error

// transfer state
const transferState = transfer.state; // None | Transferring | Transferred | Failed

// to check the transfer failure reason
const transferError = transfer.error; // transfer error code that describes the failure if a transfer request failed

O beneficiário pode ouvir um evento transferAccepted. O ouvinte desse evento tem TransferEventArgs que contém o objeto de chamada da nova chamada de transferência entre o beneficiário e o destino da transferência.

// Transferee can subscribe to the transferAccepted event
callTransferApi.on('transferAccepted', args => {
    const newTransferCall =  args.targetCall;
});

O emitente da transferência pode assinar eventos para obter a alteração do estado da transferência. Se a chamada para o destinatário da transferência tiver sido conectada com êxito ao destino de transferência, o emitente da transferência poderá desligar a chamada original com o destinatário da transferência.

transfer.on('stateChanged', () => {
   if (transfer.state === 'Transferred') {
       call.hangUp();
   }
});

Transferir para a caixa postal:

  1. Há uma chamada conectada entre o emissor da transferência e o receptor da transferência.
  2. O Identificador de Usuário do Teams da caixa postal do participante de destino é conhecido.
  3. O emissor da transferência decide transferir a chamada com o receptor da transferência para a caixa postal do participante de destino usando o Identificador de Usuário do Teams do participante de destino.
  4. O emitente da transferência chama a transfer API.
  5. O transferido recebe a solicitação de transferência.

Para transferir uma chamada atual, você pode usar a API transfer.

// transfer to the target participant voicemail specified by their Teams User Identifier
const id: MicrosoftTeamsUserIdentifier = { microsoftTeamsUserId: userId}

// call transfer API
const transfer = callTransferApi.transfer({ targetParticipantVoicemail: id });

A API transfer permite que você assine stateChanged. Ela também vem com uma transferência state e propriedades error

// transfer state
const transferState = transfer.state; // None | Transferring | Transferred | Failed

// to check the transfer failure reason
const transferError = transfer.error; // transfer error code that describes the failure if a transfer request failed

O beneficiário pode ouvir um evento transferAccepted. O ouvinte deste evento tem TransferEventArgs que contém o objeto de chamada da nova chamada de transferência entre o transferido da transferência e o correio de voz do participante de destino .

// Transferee can subscribe to the transferAccepted event
callTransferApi.on('transferAccepted', args => {
    const newTransferCall =  args.targetCall;
});

O emitente da transferência pode assinar eventos para obter a alteração do estado da transferência. Se a chamada para otransferido tiver sido conectada com êxito ao voicemail do participante de destino, o transferidor pode desligar a chamada original com o transferido.

transfer.on('stateChanged', () => {
   if (transfer.state === 'Transferred') {
       call.hangUp();
   }
});

Próximas etapas