|
| 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’ll use the Azure Communication Services Call Automation APIs to add, remove and transfer to a Teams user. |
| 21 | + |
| 22 | +You will need to be part of Azure Communication Services TAP program. It is likely that you’re already part of this program, and if you are not, please sign-up using https://aka.ms/acs-tap-invite. To access to the specific Teams Interop functionality for Call Automation, please submit your Teams Tenant Ids and Azure Communication Services Resource Ids by filling this form – https://aka.ms/acs-ca-teams-tap. You will 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](../../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](../../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#install-the-nuget-package) 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 ad hoc 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 ad hoc calling. They can further restrict ad hoc calling at the user level, so that only designated users in the tenant can communicate with ACS users. |
| 37 | + |
| 38 | +[Set-CsTeamsAcsFederationConfiguration (MicrosoftTeamsPowerShell)](~/powershell/module/teams/set-csteamsacsfederationconfiguration?view=teams-ps) |
| 39 | +This is the tenant level setting that enables/disables federation between their tenant and specific ACS resources. |
| 40 | + |
| 41 | +[Set-CsExternalAccessPolicy (SkypeForBusiness)](~/powershell/module/skype/set-csexternalaccesspolicy?view=skype-ps) |
| 42 | +This is a 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 AAD object ID for Teams users and optionally check their presence |
| 45 | +A Teams user’s AAD object ID (OID) is required to add them to or transfer to them from an ACS call. This 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 AAD 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?view=graph-rest-1.0&tabs=http): |
| 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?view=graph-rest-1.0&tabs=http). |
| 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 will need to complete the pre-requisite 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 | + |
| 91 | + |
| 92 | + |
| 93 | + |
| 94 | +## Step 4: Remove a Teams user from an existing ACS call controlled by Call Automation APIs |
| 95 | +```csharp |
| 96 | +await answer.Value.CallConnection.RemoveParticipantAsync(new MicrosoftTeamsUserIdentifier('<Teams_User_Guid>')); |
| 97 | +``` |
| 98 | + |
| 99 | +### Additional optional feature: Transfer to a Teams user from an existing ACS call controlled by Call Automation APIs |
| 100 | +```csharp |
| 101 | +await answer.Value.CallConnection.TransferCallToParticipantAsync(new CallInvite(new MicrosoftTeamsUserIdentifier('<Teams_User_Guid>'))); |
| 102 | +``` |
| 103 | +### How to tell if your Tenant is not enabled for this preview? |
| 104 | + |
| 105 | + |
| 106 | +## Clean up resources |
| 107 | + |
| 108 | +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). |
| 109 | + |
| 110 | +## Next steps |
| 111 | + |
| 112 | +- Learn more about [Call Automation](../../concepts/call-automation/call-automation.md) and its features. |
| 113 | +- Learn about [Play action](../../concepts/call-automation/play-Action.md) to play audio in a call. |
| 114 | +- Learn how to build a [call workflow](../../quickstarts/call-automation/callflows-for-customer-interactions.md) for a customer support scenario. |
0 commit comments