Merge pull request #271120 from williamzhao87/williamzhao/update-ca-quickstart

prmerger-automator[bot] · web-flow · commit cd6c8762b181 · 2024-04-04T19:42:20.000Z
Update CA quickstart with Teams add participant
diff --git a/articles/communication-services/how-tos/call-automation/teams-interop-call-automation.md b/articles/communication-services/how-tos/call-automation/teams-interop-call-automation.md
@@ -23,7 +23,7 @@ In this quickstart, we use the Azure Communication Services Call Automation APIs
 ## Prerequisites
 
 - An Azure account with an active subscription.
-- A Microsoft Teams phone license and a Teams tenant with administrative privileges. Teams phone license is a must in order to use this feature, learn more about Teams licenses [here](https://www.microsoft.com/en-us/microsoft-teams/compare-microsoft-teams-bundle-options). Administrative privileges are required to authorize Communication Services resource to call Teams users, explained later in Step 1.  
+- A Microsoft Teams phone license and a Teams tenant with administrative privileges. Teams phone license is a must in order to use this feature, learn more about Teams licenses [here](https://www.microsoft.com/microsoft-teams/compare-microsoft-teams-bundle-options). Administrative privileges are required to authorize Communication Services resource to call Teams users, explained later in Step 1.  
 - 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.
 - [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. 
 - An Azure Event Grid subscription to receive the `IncomingCall` event.
@@ -222,4 +222,4 @@ If you want to clean up and remove a Communication Services subscription, you ca
 - Learn more about [Call Automation](../../concepts/call-automation/call-automation.md) and its features.
 - Learn more about capabilities of [Teams Interoperability support with Azure Communication Services Call Automation](../../concepts/call-automation/call-automation-teams-interop.md)
 - Learn about [Play action](../../concepts/call-automation/play-Action.md) to play audio in a call.
-- Learn how to build a [call workflow](../../quickstarts/call-automation/callflows-for-customer-interactions.md) for a customer support scenario. 
+- Learn how to build a [call workflow](../../quickstarts/call-automation/callflows-for-customer-interactions.md) for a customer support scenario.
diff --git a/articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-csharp.md b/articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-csharp.md
@@ -19,10 +19,11 @@ ms.custom: mode-other
 - Create and host an Azure Dev Tunnel. Instructions [here](/azure/developer/dev-tunnels/get-started).
 - Create and connect [a Multi-service Azure AI services to your Azure Communication Services resource](../../../concepts/call-automation/azure-communication-services-azure-cognitive-services-integration.md).
 - Create a [custom subdomain](../../../../ai-services/cognitive-services-custom-subdomains.md) for your Azure AI services resource. 
+- (Optional) A Microsoft Teams user with a phone license. Teams phone license is required to add Teams users to the call. Learn more about Teams licenses [here](https://www.microsoft.com/microsoft-teams/compare-microsoft-teams-bundle-options).
 
 ## Sample code
-Download or clone quickstart sample code from [GitHub](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/CallAutomation_OutboundCalling).
 
+Download or clone quickstart sample code from [GitHub](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/CallAutomation_OutboundCalling).
 
 Navigate to `CallAutomation_OutboundCalling` folder and open the solution in a code editor.
 
@@ -45,6 +46,7 @@ Next update your `Program.cs` file with the following values:
 - `acsPhonenumber`: update this field with the Azure Communication Services phone number you have acquired. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
 - `targetPhonenumber`: update field with the phone number you would like your application to call. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
 - `cognitiveServiceEndpoint`: update field with your Azure AI services endpoint.
+- `targetTeamsUserId`: (Optional) update field with the Microsoft Teams user Id you would like to add to the call. See [Use Graph API to get Teams user Id](../../../how-tos/call-automation/teams-interop-call-automation.md#step-2-use-the-graph-api-to-get-microsoft-entra-object-id-for-teams-users-and-optionally-check-their-presence).
 
 ```csharp
 // Your ACS resource connection string 
@@ -60,7 +62,10 @@ var targetPhonenumber = "<TARGET_PHONE_NUMBER>";
 var callbackUriHost = "<CALLBACK_URI_HOST_WITH_PROTOCOL>"; 
 
 // Your cognitive service endpoint 
-var cognitiveServiceEndpoint = "<COGNITIVE_SERVICE_ENDPOINT>"; 
+var cognitiveServiceEndpoint = "<COGNITIVE_SERVICE_ENDPOINT>";
+
+// (Optional) User Id of the target teams user you want to receive the call.
+var targetTeamsUserId = "<TARGET_TEAMS_USER_ID>";
 ```
 
 ## Make an outbound call
@@ -99,6 +104,18 @@ app.MapPost("/api/callbacks", async (CloudEvent[] cloudEvents, ILogger < Program
 });
 ```
 
+## (Optional) Add a Microsoft Teams user to the call
+
+You can add a Microsoft Teams user to the call using the `AddParticipantAsync` method with a `MicrosoftTeamsUserIdentifier` and the Teams user's Id. You first need to complete the prerequisite step [Authorization for your Azure Communication Services Resource to enable calling to Microsoft Teams users](../../../how-tos/call-automation/teams-interop-call-automation.md#step-1-authorization-for-your-azure-communication-services-resource-to-enable-calling-to-microsoft-teams-users). Optionally, you can also pass in a `SourceDisplayName` to control the text displayed in the toast notification for the Teams user.
+
+```csharp
+await callConnection.AddParticipantAsync(
+    new CallInvite(new MicrosoftTeamsUserIdentifier(targetTeamsUserId))
+    {
+        SourceDisplayName = "Jack (Contoso Tech Support)"
+    });
+```
+
 ## Start recording a call
 
 The Call Automation service also enables the capability to start recording and store recordings of voice and video calls. You can learn more about the various capabilities in the Call Recording APIs [here](../../voice-video-calling/get-started-call-recording.md).
@@ -109,9 +126,9 @@ var recordingResult = await callAutomationClient.GetCallRecording().StartAsync(n
 recordingId = recordingResult.Value.RecordingId;
 ```
 
-## Play welcome message and recognize 
+## Play welcome message and recognize
 
-Using the `TextSource`, you can provide the service with the text you want synthesized and used for your welcome message. The Azure Communication Services Call Automation service plays this message upon the `CallConnected` event. 
+Using the `TextSource`, you can provide the service with the text you want synthesized and used for your welcome message. The Azure Communication Services Call Automation service plays this message upon the `CallConnected` event.
 
 Next, we pass the text into the `CallMediaRecognizeChoiceOptions` and then call `StartRecognizingAsync`. This allows your application to recognize the option the caller chooses.
 
@@ -192,8 +209,8 @@ async Task HandlePlayAsync(CallMedia callConnectionMedia, string text) {
   };
   await callConnectionMedia.PlayToAllAsync(GoodbyePlaySource);
 }
-
 ```
+
 ## Hang up and stop recording
 
 Finally, when we detect a condition that makes sense for us to terminate the call, we can use the `HangUpAsync` method to hang up the call.
@@ -220,5 +237,3 @@ dotnet run
 # [Visual Studio](#tab/visual-studio)
 
 Press Ctrl+F5 to run without the debugger.
-
-
diff --git a/articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-java.md b/articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-java.md
@@ -21,9 +21,11 @@ ms.custom: mode-other
 - Create a [custom subdomain](../../../../ai-services/cognitive-services-custom-subdomains.md) for your Azure AI services resource. 
 - [Java Development Kit (JDK) version 11 or above](/azure/developer/java/fundamentals/java-jdk-install).
 - [Apache Maven](https://maven.apache.org/download.cgi).
+- (Optional) A Microsoft Teams user with a phone license. Teams phone license is required to add Teams users to the call. Learn more about Teams licenses [here](https://www.microsoft.com/microsoft-teams/compare-microsoft-teams-bundle-options).
 
 ## Sample code
-Download or clone quickstart sample code from [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/CallAutomation_OutboundCalling). 
+
+Download or clone quickstart sample code from [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/CallAutomation_OutboundCalling).
 
 Navigate to `CallAutomation_OutboundCalling` folder and open the solution in a code editor.
 
@@ -46,14 +48,16 @@ Then open the `application.yml` file in the `/resources` folder to configure the
 - `callerphonenumber`: update this field with the Azure Communication Services phone number you have acquired. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
 - `targetphonenumber`: update field with the phone number you would like your application to call. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
 - `cognitiveServiceEndpoint`: update field with your Azure AI services endpoint.
+- `targetTeamsUserId`: (Optional) update field with the Microsoft Teams user Id you would like to add to the call. See [Use Graph API to get Teams user Id](../../../how-tos/call-automation/teams-interop-call-automation.md#step-2-use-the-graph-api-to-get-microsoft-entra-object-id-for-teams-users-and-optionally-check-their-presence).
 
 ```yaml
 acs:
   connectionstring: <YOUR ACS CONNECTION STRING> 
   basecallbackuri: <YOUR DEV TUNNEL ENDPOINT> 
   callerphonenumber: <YOUR ACS PHONE NUMBER ex. "+1425XXXAAAA"> 
   targetphonenumber: <YOUR TARGET PHONE NUMBER ex. "+1425XXXAAAA"> 
-  cognitiveServiceEndpoint: <YOUR COGNITIVE SERVICE ENDPOINT> 
+  cognitiveServiceEndpoint: <YOUR COGNITIVE SERVICE ENDPOINT>
+  targetTeamsUserId: <(OPTIONAL) YOUR TARGET TEAMS USER ID ex. "ab01bc12-d457-4995-a27b-c405ecfe4870">
 ```
 
 
@@ -68,7 +72,17 @@ CallInvite callInvite = new CallInvite(target, caller);
 CreateCallOptions createCallOptions = new CreateCallOptions(callInvite, appConfig.getCallBackUri());
 CallIntelligenceOptions callIntelligenceOptions = new CallIntelligenceOptions().setCognitiveServicesEndpoint(appConfig.getCognitiveServiceEndpoint());
 createCallOptions = createCallOptions.setCallIntelligenceOptions(callIntelligenceOptions);
-Response < CreateCallResult > result = client.createCallWithResponse(createCallOptions, Context.NONE);
+Response<CreateCallResult> result = client.createCallWithResponse(createCallOptions, Context.NONE);
+```
+
+## (Optional) Add a Microsoft Teams user to the call
+
+You can add a Microsoft Teams user to the call using the `addParticipant` method with a `MicrosoftTeamsUserIdentifier` and the Teams user's Id.  You first need to complete the prerequisite step [Authorization for your Azure Communication Services Resource to enable calling to Microsoft Teams users](../../../how-tos/call-automation/teams-interop-call-automation.md#step-1-authorization-for-your-azure-communication-services-resource-to-enable-calling-to-microsoft-teams-users).  Optionally, you can also pass in a `SourceDisplayName` to control the text displayed in the toast notification for the Teams user.
+
+```java
+client.getCallConnection(callConnectionId).addParticipant(
+    new CallInvite(new MicrosoftTeamsUserIdentifier(targetTeamsUserId))
+        .setSourceDisplayName("Jack (Contoso Tech Support)"));
 ```
 
 ## Start recording a call
@@ -90,7 +104,6 @@ Response<RecordingStateResult> response = client.getCallRecording()
 recordingId = response.getValue().getRecordingId();
 ```
 
-
 ## Respond to calling events
 
 Earlier in our application, we registered the `basecallbackuri` to the Call Automation Service. The URI indicates endpoint the service will use to notify us of calling events that happen. We can then iterate through the events and detect specific events our application wants to understand. In the code be below we respond to the `CallConnected` event.
diff --git a/articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-node.md b/articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-node.md
@@ -21,8 +21,10 @@ ms.custom: mode-other
 - Create a [custom subdomain](../../../../ai-services/cognitive-services-custom-subdomains.md) for your Azure AI services resource. 
 - [Node.js](https://nodejs.org/en/) LTS installation.
 - [Visual Studio Code](https://code.visualstudio.com/download) installed.
+- (Optional) A Microsoft Teams user with a phone license. Teams phone license is required to add Teams users to the call. Learn more about Teams licenses [here](https://www.microsoft.com/microsoft-teams/compare-microsoft-teams-bundle-options).
 
 ## Sample code
+
 Download or clone quickstart sample code from [GitHub](https://github.com/Azure-Samples/communication-services-javascript-quickstarts/tree/main/CallAutomation_OutboundCalling).
 
 Navigate to `CallAutomation_OutboundCalling` folder and open the solution in a code editor.
@@ -54,16 +56,17 @@ Then update your `.env` file with following values:
 - `TARGET_PHONE_NUMBER`: update field with the phone number you would like your application to call. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
 - `ACS_RESOURCE_PHONE_NUMBER`: update this field with the Azure Communication Services phone number you have acquired. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
 - `COGNITIVE_SERVICES_ENDPOINT`: update field with your Azure AI services endpoint.
+- `TARGET_TEAMS_USER_ID`: (Optional) update field with the Microsoft Teams user Id you would like to add to the call. See [Use Graph API to get Teams user Id](../../../how-tos/call-automation/teams-interop-call-automation.md#step-2-use-the-graph-api-to-get-microsoft-entra-object-id-for-teams-users-and-optionally-check-their-presence).
 
 ```dosini
 CONNECTION_STRING="<YOUR_CONNECTION_STRING>" 
 ACS_RESOURCE_PHONE_NUMBER ="<YOUR_ACS_NUMBER>" 
 TARGET_PHONE_NUMBER="<+1XXXXXXXXXX>" 
 CALLBACK_URI="<VS_TUNNEL_URL>" 
-COGNITIVE_SERVICES_ENDPOINT="<COGNITIVE_SERVICEs_ENDPOINT>" 
+COGNITIVE_SERVICES_ENDPOINT="<COGNITIVE_SERVICES_ENDPOINT>" 
+TARGET_TEAMS_USER_ID="<TARGET_TEAMS_USER_ID>"
 ```
 
-
 ## Make an outbound call and play media
 
 To make the outbound call from Azure Communication Services, you use the phone number you provided to the environment. Ensure that the phone number is in the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
@@ -86,6 +89,17 @@ console.log("Placing outbound call...");
 acsClient.createCall(callInvite, process.env.CALLBACK_URI + "/api/callbacks", options);
 ```
 
+## (Optional) Add a Microsoft Teams user to the call
+
+You can add a Microsoft Teams user to the call using the `addParticipant` method with the `microsoftTeamsUserId` property. You first need to complete the prerequisite step [Authorization for your Azure Communication Services Resource to enable calling to Microsoft Teams users](../../../how-tos/call-automation/teams-interop-call-automation.md#step-1-authorization-for-your-azure-communication-services-resource-to-enable-calling-to-microsoft-teams-users).  Optionally, you can also pass in a `sourceDisplayName` to control the text displayed in the toast notification for the Teams user.
+
+```typescript
+await acsClient.getCallConnection(callConnectionId).addParticipant({
+    targetParticipant: { microsoftTeamsUserId: TARGET_TEAMS_USER_ID },
+    sourceDisplayName: "Jack (Contoso Tech Support)"
+});
+```
+
 ## Start recording a call
 
 The Call Automation service also enables the capability to start recording and store recordings of voice and video calls. You can learn more about the various capabilities in the Call Recording APIs [here](../../voice-video-calling/get-started-call-recording.md).
diff --git a/articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-python.md b/articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-python.md
@@ -20,8 +20,10 @@ ms.custom: mode-other
 - Create and connect [a Multi-service Azure AI services to your Azure Communication Services resource](../../../concepts/call-automation/azure-communication-services-azure-cognitive-services-integration.md).
 - Create a [custom subdomain](../../../../ai-services/cognitive-services-custom-subdomains.md) for your Azure AI services resource. 
 - [Python](https://www.python.org/downloads/) 3.7+.
+- (Optional) A Microsoft Teams user with a phone license. Teams phone license is required to add Teams users to the call. Learn more about Teams licenses [here](https://www.microsoft.com/microsoft-teams/compare-microsoft-teams-bundle-options).
 
 ## Sample code
+
 Download or clone quickstart sample code from [GitHub](https://github.com/Azure-Samples/communication-services-python-quickstarts/tree/main/callautomation-outboundcalling).
 
 Navigate to `CallAutomation_OutboundCalling` folder and open the solution in a code editor.
@@ -53,7 +55,7 @@ Then update your `main.py` file with the following values:
 - `TARGET_PHONE_NUMBER`: update field with the phone number you would like your application to call. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
 - `ACS_PHONE_NUMBER`: update this field with the Azure Communication Services phone number you have acquired. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
 - `COGNITIVE_SERVICES_ENDPOINT`: update field with your Azure AI services endpoint.
-
+- `TARGET_TEAMS_USER_ID`: (Optional) update field with the Microsoft Teams user Id you would like to add to the call. See [Use Graph API to get Teams user Id](../../../how-tos/call-automation/teams-interop-call-automation.md#step-2-use-the-graph-api-to-get-microsoft-entra-object-id-for-teams-users-and-optionally-check-their-presence).
 
 ```python
 # Your ACS resource connection string 
@@ -71,6 +73,9 @@ CALLBACK_EVENTS_URI = CALLBACK_URI_HOST + "/api/callbacks"
 
 #Your Cognitive service endpoint 
 COGNITIVE_SERVICES_ENDPOINT = "<COGNITIVE_SERVICES_ENDPOINT>" 
+
+#(OPTIONAL) Your target Microsoft Teams user Id ex. "ab01bc12-d457-4995-a27b-c405ecfe4870"
+TARGET_TEAMS_USER_ID = "<TARGET_TEAMS_USER_ID>"
 ```
 
 ## Make an outbound call
@@ -90,6 +95,16 @@ call_connection_properties.call_connection_id)
 return redirect("/") 
 ```
 
+## (Optional) Add a Microsoft Teams user to the call
+
+You can add a Microsoft Teams user to the call using the `add_participant` method with a `MicrosoftTeamsUserIdentifier` and the Teams user's Id. You first need to complete the prerequisite step [Authorization for your Azure Communication Services Resource to enable calling to Microsoft Teams users](../../../how-tos/call-automation/teams-interop-call-automation.md#step-1-authorization-for-your-azure-communication-services-resource-to-enable-calling-to-microsoft-teams-users).  Optionally, you can also pass in a `source_display_name` to control the text displayed in the toast notification for the Teams user.
+
+```python
+call_connection_client.add_participant(target_participant = CallInvite(
+    target = MicrosoftTeamsUserIdentifier(user_id=TARGET_TEAMS_USER_ID),
+    source_display_name = "Jack (Contoso Tech Support)"))
+```
+
 ## Start recording a call
 
 The Call Automation service also enables the capability to start recording and store recordings of voice and video calls. You can learn more about the various capabilities in the Call Recording APIs [here](../../voice-video-calling/get-started-call-recording.md).
