Merge pull request #306704 from dmceachernmsft/dmceachernmsft/active-call-transfer-docs

[ACS Calling SDK] active call transfer docs

Author: JillGrant615

articles/communication-services/how-tos/calling-sdk/active-call-transfer.md

@@ -0,0 +1,37 @@
+---
+title: Active Call Transfer
+titleSuffix: An Azure Communication Services how-to guide
+description: Use Azure Communication Services SDKs to transfer active calls between clients.
+author: probableprime
+ms.author: dmceachern
+ms.service: azure-communication-services
+ms.subservice: calling
+ms.topic: how-to 
+ms.date: 10/03/2025
+ms.custom: template-how-to
+
+#Customer intent: As a developer, I want to learn how to transfer calls between devices so that users have the option to transfer calls to their other devices while in a call.
+---
+
+# Active Call Transfer
+
+[!INCLUDE [Public Preview Notice](../../includes/public-preview-include.md)]
+
+During an active call, you may want to transfer the call to device that you are signed in on. Let's learn how. 
+
+
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). 
+- A deployed Communication Services resource. [Create a Communication Services resource](../../quickstarts/create-communication-resource.md).
+- A user access token to enable the calling client. For more information, see [Create and manage access tokens](../../quickstarts/identity/access-tokens.md).
+- Complete the quickstart to [add voice calling to your application](../../quickstarts/voice-video-calling/getting-started-with-calling.md)
+
+[!INCLUDE [Transfer active calls Client-side JavaScript](./includes/active-call-transfer/active-call-transfer.md)]
+
+## Next steps
+- [Learn how to manage calls](./manage-calls.md)
+- [Learn how to manage video](./manage-video.md)
+- [Learn how to record calls](./record-calls.md)
+- [Learn how to transcribe calls](./call-transcription.md)

articles/communication-services/how-tos/calling-sdk/includes/active-call-transfer/active-call-transfer.md

@@ -0,0 +1,70 @@
+---
+author: probableprime
+ms.service: azure-communication-services
+ms.topic: include
+ms.date: 10/03/2025
+ms.author: dmceachern
+---
+
+[!INCLUDE [Install SDK](../install-sdk/install-sdk-web.md)]
+
+## Active Call Management
+Active Call Transfer is a feature of the core `CallAgent` API. This guide talks about how you can manage and track any ongoing calls for your users and how to transfer their client to that active call.
+
+**Note:** This feature is also enabled for the `TeamsCallAgent` as this feature is supported for Teams users as well.
+
+This guide assumes you went through the QuickStart or that you implemented an application that is able to make and receive calls. If you didn't complete the getting starting guide, refer to our [Quickstart](../../../../quickstarts/voice-video-calling/getting-started-with-calling.md).
+
+### Fetch your Active Call
+
+When your user signs to the `CallAgent` there is a new method that you can use to fetch the ongoing calls `getActiveCallDetails` the response will return to you the active call, or active meeting that your users are in.
+
+```js
+const activeCallDetails = await callAgent.getActiveCallDetails();
+```
+
+The function `getActiveCallDetails` a way that you can manually query for this data. Once you have the active call details, you can use it to switch the client to the call that was found. This function returns `undefined` if there is no active call ongoing for your user. You can use `getActiveCallDetails` to fetch any ongoing calls when you first sign into the `CallAgent` to pick up on any calls that are already ongoing.
+
+### Switch your Active Call
+
+Once you have your active call data, you can switch the client over to the new call. This call switching behavior can be done with the `activeCallTransfer` function.
+
+```js
+const activeCallDetails = await callAgent.getActiveCallDetails();
+const call = await callAgent.activeCallTransfer(activeCallDetails, {isTransfer: true});
+```
+
+This function returns the call object for your applications state.
+
+### Companion mode
+
+When transferring the active call to your client, you can just bring the client into the call without hanging up on the device that initiated the call the user is in.
+
+```js
+const activeCallDetails = await callAgent.getActiveCallDetails();
+const call = await callAgent.activeCallTransfer(activeCallDetails, {isTransfer: false}); // <-- isTransfer: false - does not remove the original client. 
+```
+
+### Subscribe to Active Call Notification events
+
+There are two new events that you can subscribe to so you can receive events notifying you of your user joining a call on another client. The first event notifies the application that the user is in a call on another device. This event is also emitted when the user logs into the `CallAgent` if they are on a call already elsewhere.
+
+```js
+callAgent.on("activeCallsUpdated", (args) => {
+    // show UI indicating that the user is in another call on another device
+    await callAgent.activeCallTransfer(args.activeCallDetails, {isTransfer: true});
+});
+```
+The second event notifies the application that the user is no longer in an active call anywhere else. This event is to be used to hide any UI indicating that they are in a call elsewhere, and any controls to manually transfer the call over.
+
+```js
+callAgent.on("NoActiveCalls", () => {
+    // hide UI indicating that the user is in a call elsewhere
+});
+```
+
+
+
+
+
+

articles/communication-services/toc.yml

@@ -499,6 +499,8 @@ items:
         href: how-tos/calling-sdk/dominant-speaker.md
       - name: Transfer calls
         href: how-tos/calling-sdk/transfer-calls.md
+      - name: Active Call Transfer
+        href: how-tos/calling-sdk/active-call-transfer.md
       - name: Get local capabilities
         href: how-tos/calling-sdk/capabilities.md
       - name: View PowerPoint Live