Transfer calls
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
- An Azure account with an active subscription. Create an account for free.
- A deployed Communication Services resource. Create a Communication Services resource.
- A user access token to enable the calling client. For more information, see Create and manage access tokens.
- Optional: Complete the quickstart to add voice calling to your application
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:
- 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.
- The transferor calls the
transfer
API. - The transferee decides whether to
accept
orreject
the transfer request to the transfer target by using atransferRequested
event. - 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:
- There's already a connected call between the transferor and the transferee.
- There's already a connected call between the transferor and the transfer target.
- The transferor decides to transfer the call with the transferee to the call with transfer target.
- The transferor calls the
transfer
API. - The transferee decides whether to
accept
orreject
the transfer request to the transfer target by using atransferRequested
event. - 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
Feedback
Submit and view feedback for