Merge pull request #219338 from jasonshave/jasonshave/known-issues

Fixing several articles and adding images

Author: 19BMG00

articles/communication-services/concepts/call-automation/call-automation.md

@@ -144,6 +144,8 @@ To understand which events are published for different actions, refer to [this g
 
 1. Using the incorrect IdentifierType for endpoints for `Transfer` requests (like using CommunicationUserIdentifier to specify a phone number) returns a 500 error instead of a 400 error code. Solution: Use the correct type, CommunicationUserIdentifier for Communication Users and PhoneNumberIdentifier for phone numbers. 
 2. Taking a pre-call action like Answer/Reject on the original call after redirected it gives a 200 success instead of failing on 'call not found'.
+3. Transferring a call with more than two participants is currently not supported.
+4. After transferring a call, you may receive two `CallDisconnected` events and will need to handle this behavior by ignoring the duplicate.
 
 ## Next steps
 

articles/communication-services/concepts/call-automation/incoming-call-notification.md

@@ -47,10 +47,21 @@ This architecture has the following benefits:
 
 To check out a sample payload for the event and to learn about other calling events published to Event Grid, check out this [guide](../../../event-grid/communication-services-voice-video-events.md#microsoftcommunicationincomingcall).
 
+Below is an example of an Event Grid Webhook subscription where the event type filter is listening only to the `IncomingCall` event.
+
+![Image showing IncomingCall subscription.](./media/subscribe-incoming-call-event-grid.png)
+
 ## Call routing in Call Automation or Event Grid
 
 You can use [advanced filters](../../../event-grid/event-filtering.md) in your Event Grid subscription to subscribe to an `IncomingCall` notification for a specific source/destination phone number or Azure Communication Services identity and sent it to an endpoint such as a Webhook subscription. That endpoint application can then make a decision to **redirect** the call using the Call Automation SDK to another Azure Communication Services identity or to the PSTN.
 
+> [!NOTE]
+> In many cases you will want to configure filtering in Event Grid due to the scenarios described above generating an `IncomingCall` event so that your application only receives events it should be responding to. For example, if you want to redirect an inbound PSTN call to an ACS endpoint and you don't use a filter, your Event Grid subscription will receive two `IncomingCall` events; one for the PSTN call and one for the ACS user even though you had not intended to receive the second notification. Failure to handle these scenarios using filters or some other mechanism in your application can cause infinite loops and/or other undesired behavior.
+
+Below is an example of an advanced filter on an Event Grid subscription watching for the `data.to.PhoneNumber.Value` string starting with a PSTN phone number of `+18005551212.
+
+![Image showing Event Grid advanced filter.](./media/event-grid-advanced-filter.png)
+
 ## Number assignment
 
 Since the `IncomingCall` notification doesn't have a specific destination other than the Event Grid subscription you've created, you're free to associate any particular number to any endpoint in Azure Communication Services. For example, if you acquired a PSTN phone number of `+14255551212` and want to assign it to a user with an identity of `375f0e2f-e8db-4449-9bf7-2054b02e42b4` in your application, you'll maintain a mapping of that number to the identity. When an `IncomingCall` notification is sent matching the phone number in the **to** field, you'll invoke the `Redirect` API and supply the identity of the user. In other words, you maintain the number assignment within your application and route or answer calls at runtime.

articles/communication-services/concepts/call-automation/media/event-grid-advanced-filter.png

@@ -21,7 +21,8 @@ You can download the sample app from [GitHub](https://github.com/Azure-Samples/c
 - An Azure account with an active subscription.
 - Azure Communication Services resource. See [Create an Azure Communication Services resource](../../create-communication-resource.md?tabs=windows&pivots=platform-azp). Note the resource connection string for this quickstart by navigating to your resource selecting 'Keys' from the left side menu.
 - [Acquire a phone number for your Communication Service resource](../../telephony/get-phone-number.md?pivots=programming-language-csharp). Note the phone number you acquired for use in this quickstart. 
-- The latest [.NET library](https://dotnet.microsoft.com/download/dotnet-core) for your operating system. .NET 6.0 or higher is recommended as this quickstart uses the minimal API feature. 
+- The latest [.NET library](https://dotnet.microsoft.com/download/dotnet-core) for your operating system. .NET 6.0 or higher is recommended as this quickstart uses the minimal API feature.
+- The latest version of Visual Studio 2022 (17.4.0 or higher)
 - An audio file for the message you want to play in the call. This audio should be accessible via a url. 
 
 ## Create a new C# application
@@ -38,16 +39,15 @@ In the console window of your operating system, use the `dotnet` command to crea
 2. Install the NuGet packages: [Azure.Communication.CallAutomation](https://dev.azure.com/azure-sdk/public/_artifacts/feed/azure-sdk-for-net/NuGet/Azure.Communication.CallAutomation/versions/) and [Azure.Messaging.EventGrid](https://dev.azure.com/azure-sdk/public/_artifacts/feed/azure-sdk-for-net/NuGet/Azure.Messaging.EventGrid/versions/) to your project. 
 ```console 
 dotnet add <path-to-project> package Azure.Communication.CallAutomation --prerelease
-dotnet add <path-to-project> package Azure.Messaging.EventGrid --prerelease
+dotnet add <path-to-project> package Azure.Messaging.EventGrid
 ```
-## Set up a public URI for the local application 
+## Use Visual Studio Dev Tunnels for your webhook
 
-In this quick-start, you'll use [Ngrok tool](https://ngrok.com/) to project a public URI to the local port so that your local application can be visited by the internet. The public URI is needed to receive the Event Grid `IncomingCall` event and Call Automation events using webhooks.
+In this quick-start, you'll use the new [Visual Studio Dev Tunnels](/connectors/custom-connectors/port-tunneling) feature to obtain a public domain name so that your local application is reachable by the Call Automation platform on the Internet. The public name is needed to receive the Event Grid `IncomingCall` event and Call Automation events using webhooks.
 
-First, determine the port of the .NET application. Minimal API dynamically allocates a port for the project at the time of creation. Find out the http port in <PROJECT_ROOT>\Properties\launchSettings.json.
-:::image type="content" source="./../media/dotnet-application-port.jpg" alt-text="Screenshot of demo application's launchsetting.json file":::
+If you haven't already configured your workstation, be sure to follow the steps in [this guide](/connectors/custom-connectors/port-tunneling). Once configured, your workstation will acquire a public domain name automatically allowing us to use the environment variable `["VS_TUNNEL_URL"]` as shown below.
 
-Then, [install Ngrok](https://ngrok.com/download) and run Ngrok with the following command: `ngrok http <port>`. This command will create a public URI like `https://ff2f-75-155-253-232.ngrok.io/`, and it is your Ngrok Fully Qualified Domain Name(Ngrok_FQDN). Keep Ngrok running while following the rest of this quick-start.
+Set up your Event Grid subscription to receive the `IncomingCall` event by reading [this guide](../../../concepts/call-automation/incoming-call-notification.md).
 
 ## Update Program.cs
 
@@ -69,22 +69,24 @@ using System.Text.Json.Nodes;
 
 var builder = WebApplication.CreateBuilder(args);
 
-var client = new CallAutomationClient("<resource_connection_string>"); //noted from pre-requisite step
-var callbackUriBase = "<public_url_generated_by_ngrok>"; 
-var mediaFileSource = new Uri("<url_to_media_file>"); //This URL should be public accessible and the file format should be WAV, 16KHz, Mono.
+var client = new CallAutomationClient("<resource_connection_string"); //noted from pre-requisite step
+var tunnelUrl = builder.Configuration["VS_TUNNEL_URL"]; // Visual Studio Dev Tunnel's dynamic FQDN
+var mediaFileSource = new Uri("<link_to_media_file>"); //This URL should be public accessible and the file format should be WAV, 16KHz, Mono.
 var applicationPhoneNumber = "<phone_number_acquired_as_prerequisite>";
-var phoneNumberToAddToCall = "<phone_number_to_add_to_call>"; //in format of +1...
+var phoneNumberToAddToCall = "<phone_number_to_add_to_call>"; //in E.164 format starting +...
+
+Console.WriteLine($"Tunnel URL:{builder.Configuration["VS_TUNNEL_URL"]}"); // echo Tunnel URL to screen to configure Event Grid webhook
 
 var app = builder.Build();
+
 app.MapPost("/api/incomingCall", async (
     [FromBody] EventGridEvent[] eventGridEvents) =>
 {
     foreach (var eventGridEvent in eventGridEvents)
     {
-        // Handle system events
         if (eventGridEvent.TryGetSystemEventData(out object eventData))
         {
-            // Handle the subscription validation event.
+            // Handle the webhook subscription validation event.
             if (eventData is SubscriptionValidationEventData subscriptionValidationEventData)
             {
                 var responseData = new SubscriptionValidationResponse
@@ -97,7 +99,7 @@ app.MapPost("/api/incomingCall", async (
         var jsonObject = JsonNode.Parse(eventGridEvent.Data).AsObject();
         var callerId = (string)(jsonObject["from"]["rawId"]);
         var incomingCallContext = (string)jsonObject["incomingCallContext"];
-        var callbackUri = new Uri(callbackUriBase + $"/api/calls/{Guid.NewGuid()}?callerId={callerId}");
+        var callbackUri = new Uri(tunnelUrl + $"api/calls/{Guid.NewGuid()}?callerId={callerId}");
 
         AnswerCallResult answerCallResult = await client.AnswerCallAsync(incomingCallContext, callbackUri);
     }
@@ -145,8 +147,14 @@ app.MapPost("/api/calls/{contextId}", async (
 
 app.Run();
 ```
-Replace the placeholders with the actual values in lines 12-16. In your production code, we recommend using [Secret Manager](https://learn.microsoft.com/aspnet/core/security/app-secrets) for storing sensitive information like this.  
+Replace the placeholders with the actual values in lines 12-16. In your production code, we recommend using [Secret Manager](/aspnet/core/security/app-secrets) for storing sensitive information.
 
 ## Run the app
 
-Open Your_Project_Name.csproj file in your project with Visual Studio, and then select Run button or press F5 on your keyboard.
+Within Visual Studio select the Run button or press F5 on your keyboard. You should have a dynamic FQDN echoed to the screen as per the above `Console.WriteLine()` command above. Use this FQDN to now configure your Event Grid webhook subscription to receive the inbound call.
+
+## Configure Event Grid webhook subscription
+
+In order to receive the `IncomingCall` event for the inbound PSTN call, you must configure an Event Grid subscription as described in this [concepts guide](../../../concepts/call-automation/incoming-call-notification.md). The most important thing to remember is that an Event Grid webhook subscription must be validated against a working web server. Since you've started the project in the previous step, and you have a public FQDN, set the webhook address in your subscription to the Dev Tunnel obtained by Visual Studio plus the path to your POST endpoint (i.e. `https://<dev_tunnel_fqdn>/api/incomingCall`).
+
+Once your webhook subscription has been validated, it will show up in the portal and you're now ready to test your application by making an inbound call.

articles/communication-services/concepts/call-automation/media/subscribe-incoming-call-event-grid.png

@@ -17,6 +17,8 @@ ms.author: askaur
 - A deployed [Communication Service resource](../../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](../../telephony/get-phone-number.md). Note the phone number you acquired to use in this quickstart. 
 - The latest [.NET library](https://dotnet.microsoft.com/download/dotnet-core) for your operating system.
+- The latest version of Visual Studio 2022 (17.4.0 or higher).
+- An Azure Event Grid subscription to receive the `IncomingCall` event.
 
 ## Create a new C# application
 
@@ -36,13 +38,13 @@ dotnet add <path-to-project> package Azure.Communication.CallAutomation --prerel
 dotnet add <path-to-project> package Azure.Messaging.EventGrid --prerelease
 ```
 
-## Set up a public URI for the local application
-In this quick-start, you'll use Ngrok tool to project a public URI to the local port so that your local application can be visited by the internet. The public URI is needed to receive the Event Grid IncomingCall event and Call Automation events using webhooks.
+## Use Visual Studio Dev Tunnels for your Event Grid subscription
 
-First, determine the port of the .NET application. Minimal API dynamically allocates a port for the project at the time of creation. Find out the http port in <PROJECT_ROOT>\Properties\launchSettings.json. 
-![Screenshot of demo application's launchsetting.json file.](../media/dotnet-application-port.jpg)
+In this quick-start, you'll use the new [Visual Studio Dev Tunnels](/connectors/custom-connectors/port-tunneling) feature to obtain a public domain name so that your local application is reachable by the Call Automation platform on the Internet. The public name is needed to receive the Event Grid `IncomingCall` event and Call Automation events using webhooks.
 
-Then, install Ngrok and run Ngrok with the following command: ngrok http <replace_with_port>. This command will create a public URI like `https://ff2f-75-155-253-232.ngrok.io/`, and it is your Ngrok Fully Qualified Domain Name(Ngrok_FQDN). Keep Ngrok running while following the rest of this quick-start.
+If you haven't already configured your workstation, be sure to follow the steps in [this guide](/connectors/custom-connectors/port-tunneling). Once configured, your workstation will acquire a public domain name automatically allowing us to use the environment variable `["VS_TUNNEL_URL"]` as shown below.
+
+Set up your Event Grid subscription to receive the `IncomingCall` event by reading [this guide](../../../concepts/call-automation/incoming-call-notification.md).
 
 ## Configure Program.cs to redirect the call
 
@@ -61,6 +63,8 @@ var builder = WebApplication.CreateBuilder(args);
 
 var client = new CallAutomationClient("<resource_connection_string_obtained_in_pre-requisites>");
 
+Console.WriteLine($"Tunnel URL:{builder.Configuration["VS_TUNNEL_URL"]}"); // echo Tunnel URL to screen to configure Event Grid webhook
+
 var app = builder.Build();
 
 app.MapPost("/api/incomingCall", async (

articles/communication-services/quickstarts/call-automation/includes/callflow-for-customer-interactions-csharp.md

@@ -18,6 +18,7 @@ ms.author: askaur
 - [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.
 - [Java Development Kit (JDK)](/java/azure/jdk/?preserve-view=true&view=azure-java-stable) version 8 or above.
 - [Apache Maven](https://maven.apache.org/download.cgi).
+- An Azure Event Grid subscription to receive the `IncomingCall` event.
 
 ## Create a new Java Spring application