Merge pull request #217513 from ashwinder/master

Update Call Automation Quickstart

Author: jborsecnik

articles/communication-services/.openpublishing.redirection.communication-services.json

@@ -69,6 +69,11 @@
           "source_path_from_root": "/articles/communication-services/quickstarts/telephony/manage-inbound-calls.md",
           "redirect_url": "/azure/communication-services/how-tos/call-automation-sdk/redirect-inbound-telephony-calls",
           "redirect_document_id": false
+      },
+      {
+        "source_path_from_root": "/articles/communication-services/how-tos/call-automation-sdk/subscribe-to-incoming-call.md",
+        "redirect_url": "/azure/communication-services/concepts/voice-video-calling/incoming-call-notification",
+        "redirect_document_id": false
       }
     ]
 }

articles/communication-services/concepts/voice-video-calling/incoming-call-notification.md

@@ -30,7 +30,7 @@ Given the above examples, the following scenarios will trigger an `IncomingCall`
 | Source | Destination | Scenario(s) |
 | ------ | ----------- | -------- |
 | Azure Communication Services identity | Azure Communication Services identity | Call, Redirect, Add Participant, Transfer |
-| Azure Communication Services identity | PSTN number owned by your Azure Communication Services resource  | Call, Redirect, Add Participant
+| Azure Communication Services identity | PSTN number owned by your Azure Communication Services resource  | Call, Redirect, Add Participant, Transfer
 | Public PSTN | PSTN number owned by your Azure Communication Services resource  | Call, Redirect, Add Participant, Transfer
 
 > [!NOTE]
@@ -46,7 +46,7 @@ This architecture has the following benefits:
 - PSTN number assignment and routing logic can exist in your application versus being statically configured online.
 - As identified in the above [calling scenarios](#calling-scenarios) section, your application can be notified even when users make calls between each other. You can then combine this scenario together with the [Call Recording APIs](../voice-video-calling/call-recording.md) to meet compliance needs.
 
-To subscribe to the `IncomingCall` notification from Event Grid, [follow this how-to guide](../../how-tos/call-automation-sdk/subscribe-to-incoming-call.md).
+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).
 
 ## Call routing in Call Automation or Event Grid
 
@@ -55,3 +55,7 @@ You can use [advanced filters](../../../event-grid/event-filtering.md) in your E
 ## 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.
+
+## Next steps
+- [Build a Call Automation application](../../quickstarts/voice-video-calling/callflows-for-customer-interactions.md) to simulate a customer interaction.
+- [Redirect an inbound PSTN call](../../how-tos/call-automation-sdk/redirect-inbound-telephony-calls.md) to your resource.

articles/communication-services/how-tos/call-automation-sdk/media/subscription-validation.png

@@ -21,7 +21,7 @@ zone_pivot_groups: acs-csharp-java
 In this quickstart, you'll learn how to build an application that uses the Azure Communication Services Call Automation SDK to handle the following scenario:
 - handling the `IncomingCall` event from Event Grid
 - answering a call
-- playing an audio file
+- playing an audio file and recognizing input(DTMF) from caller
 - adding a communication user to the call such as a customer service agent who uses a web application built using Calling SDKs to connect to Azure Communication Services
 
 ::: zone pivot="programming-language-csharp"
@@ -32,13 +32,28 @@ In this quickstart, you'll learn how to build an application that uses the Azure
 [!INCLUDE [Call flows for customer interactions with Java](./includes/call-automation/Callflow-for-customer-interactions-java.md)]
 ::: zone-end
 
+## Subscribe to IncomingCall event
+
+IncomingCall is an Azure Event Grid event for notifying incoming calls to your Communication Services resource. To learn more about it, see [this guide](../../concepts/voice-video-calling/incoming-call-notification.md). 
+1. Navigate to your resource on Azure portal and select `Events` from the left side menu.
+1. Select `+ Event Subscription` to create a new subscription. 
+1. Filter for Incoming Call event. 
+1. Choose endpoint type as web hook and provide the public url generated for your application by ngrok. Make sure to provide the exact api route that you programmed to receive the event previously. In this case, it would be <ngrok_url>/api/incomingCall. 
+![Screenshot of portal page to create a new event subscription.](./media/call-automation/event-susbcription.png)
+
+1. Select create to start the creation of subscription and validation of your endpoint as mentioned previously. The subscription is ready when the provisioning status is marked as succeeded. 
+
+This subscription currently has no filters and hence all incoming calls will be sent to your application. To filter for specific phone number or a communication user, use the Filters tab.
+
 ## Testing the application
 
-1. Place a call to the number you acquired in the Azure portal (see prerequisites above).
-2. Your Event Grid subscription to the `IncomingCall` should execute and call your web server.
-3. The call will be answered, and an asynchronous web hook callback will be sent to the NGROK callback URI.
-4. When the call is connected, a `CallConnected` event will be sent to your web server, wrapped in a `CloudEvent` schema and can be easily deserialized using the Call Automation SDK parser. At this point, the application will request audio to be played and input from a targeted phone number.
-5. When the input has been received and recognized, the web server will make a request to add a participant to the call.
+1. Place a call to the number you acquired in the Azure portal.
+2. Your Event Grid subscription to the `IncomingCall` should execute and call your application that will request to answer the call. 
+3. When the call is connected, a `CallConnected` event will be sent to your application's callback url. At this point, the application will request audio to be played and to receive input from the caller.
+4. From your phone, press any three number keys, or press one number key and then # key. 
+5. When the input has been received and recognized, the application will make a request to add a participant to the call.
+6. Once the added user answers, you can talk to them. 
+
 
 ## Clean up resources