Transferir e encaminhar chamadas

  • Artigo

Durante uma chamada ativa, talvez você queira transferir a chamada para outra pessoa ou número. Vamos aprender como.

Pré-requisitos

Instalar o SDK

Use o comando npm install para instalar os SDKs Comuns 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()

Gerenciar a conectividade do SDK do ACS para chamadas de entrada

Uma instância Call Agent permite iniciar/ingressar e gerenciar chamadas de entrada. Sua instância Call Agent precisa estar conectada à infraestrutura do ACS para receber chamadas de entrada. Esta conexão é estabelecida quando uma instância Call Agent é criada, mas às vezes, por exemplo, quando a rede está instável, a conexão pode não ser configurada ou pode ser interrompida durante o ciclo de vida de Call Agent. O SDK do ACS sempre tenta se manter conectado à infraestrutura do ACS. Ele continua tentando se conectar novamente quando a conexão é perdida.

Você pode verificar se Call Agent está conectado à infraestrutura ACS examinando o valor atual da propriedade connectionState e escutando o evento connectionStateChanged de Call Agent.

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

O exemplo acima ilustra como gerenciar o estado da conexão sempre que o estado da conexão for:

  • A instância Connected - Call Agent está conectada e é capaz de receber notificações de infraestrutura ACS. Por exemplo, o recebimento de notificações de chamadas recebidas.
  • A instância Disconnected - Call Agent está desconectada. É um estado terminal. Call Agent deve ser recriado. Os usuários devem se certificar de que não há problemas de rede. -- motivo invalidToken – se o token ACS expirou ou é inválido e o aplicativo não forneceu um novo token válido. A instância Call Agent será desconectada por esse motivo. -- motivo connectionIssue: se a rede estiver inoperante e, após várias tentativas, o Call Agent não conseguir se reconectar, ele se desconectará com esse motivo. Geralmente, isso indica problemas de rede do cliente e pode ser resolvido assim que o problema de conectividade for resolvido.

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

Próximas etapas