Edit

Transfer calls

  • Article

Important

Functionality described in this document is currently in public preview. This preview version is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

During an active call, you may want to transfer the call to another person or number. Let's learn how.

Prerequisites

Install the SDK

Use the npm install command to install the Azure Communication Services calling and common SDKs for JavaScript.

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

Initialize required objects

A CallClient, instance is required for most call operations. Let's create a new CallClient instance. You can configure it with custom options like a Logger instance.

When you have a CallClient instance, you can create a CallAgent instance by calling the createCallAgent method on the CallClient instance. This method asynchronously returns a CallAgent instance object.

The createCallAgent method uses CommunicationTokenCredential as an argument. It accepts a user access token.

You can use the getDeviceManager method on the CallClient instance to access 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 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(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Note

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

Call transfer is an extended feature of the core Call API. You first need to import calling Features from the Calling SDK:

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

Then you can get the transfer feature API object from the call instance:

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

Call transfers involve three parties:

  • Transferor: The person who initiates the transfer request.
  • Transferee: The person who is being transferred.
  • Transfer target: The person who is being transferred to.

Transfer to participant:

  1. There's already a connected call between the transferor and the transferee. The transferor decides to transfer the call from the transferee to the transfer target.
  2. The transferor calls the transfer API.
  3. The transferee decides whether to accept or reject the transfer request to the transfer target by using a transferRequested event.
  4. The transfer target receives an incoming call only if the transferee accepts the transfer request.

To transfer a current call, you can use the transfer API. transfer takes the optional transferCallOptions, which allows you to set a disableForwardingAndUnanswered flag:

  • disableForwardingAndUnanswered = false: If the transfer target doesn't answer the transfer call, the transfer follows the transfer target forwarding and unanswered settings.
  • disableForwardingAndUnanswered = true: If the transfer target doesn't answer the transfer call, the transfer attempt ends.
// transfer target can be an Azure Communication Services user
const id = { communicationUserId: <ACS_USER_ID> };

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

Transfer to call:

  1. There's already a connected call between the transferor and the transferee.
  2. There's already a connected call between the transferor and the transfer target.
  3. The transferor decides to transfer the call with the transferee to the call with transfer target.
  4. The transferor calls the transfer API.
  5. The transferee decides whether to accept or reject the transfer request to the transfer target by using a transferRequested event.
  6. The transfer target receives an incoming call only if the transferee accepts the transfer request.

To transfer a current call, you can use the transfer API.

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

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

The transfer API allows you to subscribe to transferStateChanged and transferRequested events. A transferRequested event comes from a call instance; a transferStateChanged event and transfer state and error come from a transfer instance.

// 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

The transferee can accept or reject the transfer request initiated by the transferor in the transferRequested event by using accept() or reject() in transferRequestedEventArgs. You can access targetParticipant information and accept or reject methods in transferRequestedEventArgs.

// Transferee to accept the transfer request
callTransferApi.on('transferRequested', args => {
    args.accept();
});

// Transferee to reject the transfer request
callTransferApi.on('transferRequested', args => {
    args.reject();
});

The transferor can subscribe to events for change of the state of the transfer. If the call to the transferee was successfully connected with Transfer target, transferor can hang up the original call with transferee.

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

Next steps