|
| 1 | +--- |
| 2 | +title: Azure Communication Services Call Automation how-to for adding Microsoft Teams User into an existing call |
| 3 | +titleSuffix: An Azure Communication Services how-to document |
| 4 | +description: ProvIDes a how-to for adding a Microsoft Teams user to a call with Call Automation. |
| 5 | +author: visho |
| 6 | + |
| 7 | +ms.service: azure-communication-services |
| 8 | +ms.topic: include |
| 9 | +ms.date: 03/28/2023 |
| 10 | +ms.author: visho |
| 11 | +ms.custom: private_preview |
| 12 | +services: azure-communication-services |
| 13 | +zone_pivot_groups: acs-csharp-java |
| 14 | +--- |
| 15 | + |
| 16 | +# Add a Microsoft Teams user to an existing call using Call Automation |
| 17 | + |
| 18 | +[!INCLUDE [Private Preview Notice](../../includes/private-preview-include.md)] |
| 19 | + |
| 20 | +In this quickstart, we use the Azure Communication Services Call Automation APIs to add, remove and transfer to a Teams user. |
| 21 | + |
| 22 | +You need to be part of the Azure Communication Services TAP program. It's likely that you’re already part of this program, and if you aren't, sign-up using https://aka.ms/acs-tap-invite. To access to the specific Teams Interop functionality for Call Automation, submit your Teams Tenant IDs and Azure Communication Services Resource IDs by filling this form – https://aka.ms/acs-ca-teams-tap. You need to fill the form every time you need a new tenant ID and new resource ID allow-listed. |
| 23 | + |
| 24 | +## Prerequisites |
| 25 | + |
| 26 | +- An Azure account with an active subscription. |
| 27 | +- A Microsoft Teams tenant with administrative privileges. |
| 28 | +- A deployed [Communication Service resource](../../quickstarts/create-communication-resource.md) and valid connection string found by selecting Keys in left side menu on Azure portal. |
| 29 | +- [Acquire a PSTN phone number from the Communication Service resource](../../quickstarts/telephony/get-phone-number.md). Note the phone number you acquired to use in this quickstart. |
| 30 | +- An Azure Event Grid subscription to receive the `IncomingCall` event. |
| 31 | +- The latest [Azure Communication Service Call Automation API library](./callflows-for-customer-interactions.md) for your operating system. |
| 32 | +- A web service that implements the Call Automation API library, follow [this tutorial](./callflows-for-customer-interactions.md). |
| 33 | + |
| 34 | +## Step 1: Authorization for your Azure Communication Services Resource to enable calling to Microsoft Teams users |
| 35 | + |
| 36 | +To enable calling through Call Automation APIs, a [Microsoft Teams Administrator](/azure/active-directory/roles/permissions-reference#teams-administrator) or [Global Administrator](/en-us/azure/active-directory/roles/permissions-reference#global-administrator) must explicitly enable the ACS resource(s) access to their tenant to allow calling. |
| 37 | + |
| 38 | +[Set-CsTeamsAcsFederationConfiguration (MicrosoftTeamsPowerShell)](/powershell/module/teams/set-csteamsacsfederationconfiguration) |
| 39 | +Tenant level setting that enables/disables federation between their tenant and specific ACS resources. |
| 40 | + |
| 41 | +[Set-CsExternalAccessPolicy (SkypeForBusiness)](/powershell/module/skype/set-csexternalaccesspolicy) |
| 42 | +User policy that allows the admin to further control which users in their organization can participate in federated communications with ACS users. |
| 43 | + |
| 44 | +## Step 2: Use the Graph API to get Azure AD object ID for Teams users and optionally check their presence |
| 45 | +A Teams user’s Azure Active Directory (Azure AD) object ID (OID) is required to add them to or transfer to them from an ACS call. The OID can be retrieved through 1) Office portal, 2) Azure AD portal, 3) Azure AD Connect; or 4) Graph API. The example below uses Graph API. |
| 46 | + |
| 47 | +Consent must be granted by an Azure AD admin before Graph can be used to search for users, learn more by following on the [Microsoft Graph Security API overview](/graph/security-concept-overview) document. The OID can be retrieved using the list users API to search for users. The following shows a search by display name, but other properties can be searched as well: |
| 48 | + |
| 49 | +[List users using Microsoft Graph v1.0](/graph/api/user-list): |
| 50 | +```rest |
| 51 | +Request: |
| 52 | + https://graph.microsoft.com/v1.0/users?$search="displayName:Art Anderson" |
| 53 | +Permissions: |
| 54 | + Application and delegated. Refer to documentation. |
| 55 | +Response: |
| 56 | + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users", |
| 57 | + "value": [ |
| 58 | + { |
| 59 | + "displayName": "Art Anderson", |
| 60 | + |
| 61 | + "id": "fc4ccb5f-8046-4812-803f-6c344a5d1560" |
| 62 | + } |
| 63 | +``` |
| 64 | +Optionally, Presence for a user can be retrieved using the get presence API and the user ObjectId. Learn more on the [Microsoft Graph v1.0 documentation](/graph/api/presence-get). |
| 65 | +```rest |
| 66 | +Request: |
| 67 | +https://graph.microsoft.com/v1.0/users/fc4ccb5f-8046-4812-803f-6c344a5d1560/presence |
| 68 | +Permissions: |
| 69 | +Delegated only. Application not supported. Refer to documentation. |
| 70 | +Response: |
| 71 | + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('fc4ccb5f-8046-4812-803f-6c344a5d1560')/presence/$entity", |
| 72 | + "id": "fc4ccb5f-8046-4812-803f-6c344a5d1560", |
| 73 | + "availability": "Offline", |
| 74 | + "activity": "Offline" |
| 75 | +
|
| 76 | +``` |
| 77 | + |
| 78 | +## Step 3: Add a Teams user to an existing ACS call controlled by Call Automation APIs |
| 79 | +You need to complete the prerequisite step and have a web service app to control an ACS call. Using the callConnection object, add a participant to the call. |
| 80 | + |
| 81 | +```csharp |
| 82 | +CallAutomationClient client = new CallAutomationClient('<Connection_String>'); |
| 83 | +AnswerCallResult answer = await client.AnswerCallAsync(incomingCallContext, new Uri('<Callback_URI>')); |
| 84 | +await answer.Value.CallConnection.AddParticipantAsync( |
| 85 | + new CallInvite(new MicrosoftTeamsUserIdentifier('<Teams_User_Guid>')) |
| 86 | + { |
| 87 | + SourceDisplayName = "Jack (Contoso Tech Support)" |
| 88 | + }); |
| 89 | +``` |
| 90 | +On the Microsoft Teams desktop client, Jack's call will be sent to the Microsoft Teams user through an incoming call toast notification. |
| 91 | + |
| 92 | + |
| 93 | +After the Microsoft Teams user accepts the call, the in-call experience for the Microsoft Teams user will have all the participants displayed on the Microsoft Teams roster. |
| 94 | + |
| 95 | + |
| 96 | +## Step 4: Remove a Teams user from an existing ACS call controlled by Call Automation APIs |
| 97 | +```csharp |
| 98 | +await answer.Value.CallConnection.RemoveParticipantAsync(new MicrosoftTeamsUserIdentifier('<Teams_User_Guid>')); |
| 99 | +``` |
| 100 | + |
| 101 | +### Optional feature: Transfer to a Teams user from an existing ACS call controlled by Call Automation APIs |
| 102 | +```csharp |
| 103 | +await answer.Value.CallConnection.TransferCallToParticipantAsync(new CallInvite(new MicrosoftTeamsUserIdentifier('<Teams_User_Guid>'))); |
| 104 | +``` |
| 105 | +### How to tell if your Tenant isn't enabled for this preview? |
| 106 | + |
| 107 | + |
| 108 | +## Clean up resources |
| 109 | + |
| 110 | +If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about [cleaning up resources](../../quickstarts/create-communication-resource.md#clean-up-resources). |
| 111 | + |
| 112 | +## Next steps |
| 113 | + |
| 114 | +- Learn more about [Call Automation](../../concepts/call-automation/call-automation.md) and its features. |
| 115 | +- Learn about [Play action](../../concepts/call-automation/play-Action.md) to play audio in a call. |
| 116 | +- Learn how to build a [call workflow](../../quickstarts/call-automation/callflows-for-customer-interactions.md) for a customer support scenario. |
0 commit comments