Merge pull request #14 from valindrae/ca-ai-1

tidy up docs

Author: valindrae

articles/communication-services/concepts/call-automation/azure-communication-services-azure-cognitive-services-integration.md

@@ -8,7 +8,6 @@ ms.subservice: call-automation
 ms.topic: include
 ms.date: 02/15/2023
 ms.author: kpunjabi
-ms.custom: private_preview
 ms.custom: references_regions
 services: azure-communication-services
 ---

articles/communication-services/concepts/call-automation/media/add-role.png

@@ -150,27 +150,36 @@ Assert.AreEqual(202, playResponse.Status) // The request was accepted.
 
 Your application receives action lifecycle event updates on the callback URL that was provided to Call Automation service at the time of answering the call. An example of a successful play event update.
 
-```json 
-[{
-    "id": "704a7a96-4d74-4ebe-9cd0-b7cc39c3d7b1",
-    "source": "calling/callConnections/<callConnectionId>/PlayCompleted",
-    "type": "Microsoft.Communication.PlayCompleted",
-    "data": {
-        "resultInfo": {
-            "code": 200,
-            "subCode": 0,
-            "message": "Action completed successfully."
-        },
-        "type": "playCompleted",
-        "callConnectionId": "<callConnectionId>",
-        "serverCallId": "<serverCallId>",
-        "correlationId": "<correlationId>"
-        },
-    "time": "2022-08-12T03:13:25.0252763+00:00",
-    "specversion": "1.0",
-    "datacontenttype": "application/json",
-    "subject": "calling/callConnections/<callConnectionId>/PlayCompleted"
-}]
+### Example of how you can deserialize the *PlayCompleted* event:
+
+``` csharp
+ if (@event is PlayCompleted { OperationContext: "PlayAudio" })
+        {
+            var playCompletedEvent = (PlayCompleted)@event;
+
+            if (ReasonCode.CompletedSuccessfully.Equals(playCompletedEvent.ReasonCode))
+            {
+                //Play audio succeeded, take action on success.
+                await callConnection.HangUpAsync(forEveryone: true);
+            }
+        }
+```
+
+### Example of how you can deserialize the *PlayFailed* event:
+
+``` csharp
+if (@event is PlayFailed { OperationContext: "PlayAudio" })
+        {
+            var playFailedEvent = (PlayFailed)@event;
+
+            if (ReasonCode.PlayDownloadFailed.Equals(playFailedEvent.ReasonCode) ||
+            ReasonCode.PlayInvalidFileFormat.Equals(playFailedEvent.ReasonCode))
+            {
+                //Play audio failed, Take some action on failed event.
+                logger.LogInformation($"PlayFailed event received for call connection id: {@event.CallConnectionId}");
+                await callConnection.HangUpAsync(forEveryone: true);
+            }
+        }
 ```
 
 To learn more about other supported events, visit the [Call Automation overview document](../../../concepts/call-automation/call-automation.md#call-automation-webhook-events).
@@ -184,3 +193,16 @@ var callMedia = callAutomationClient.GetCallConnection(<callConnectionId>).GetCa
 var cancelResponse = await callMedia.CancelAllMediaOperations();
 Assert.AreEqual(202, cancelResponse.Status) // The request was accepted.
 ```
+
+### Example of how you can deserialize the *PlayCanceled* event:
+
+``` csharp
+if (@event is PlayCanceled { OperationContext: "PlayAudio" })
+        {
+            var playFailedEvent = (PlayCanceled)@event;
+
+            logger.LogInformation($"PlayCanceled event received for call connection id: {@event.CallConnectionId}");
+            //Take action on recognize canceled operation
+            await callConnection.HangUpAsync(forEveryone: true);
+        }
+```

articles/communication-services/concepts/call-automation/media/cognitive-service-user.png

@@ -71,12 +71,7 @@ You can test creating your own audio file using our [Speech synthesis with Audio
 
 ## (Optional) Connect your Azure Cognitive Service to your Azure Communication Service
 
-If you would like to use Text-To-Speech capabilities, then it's required for you to connect your Azure Cognitive Service to your Azure Communication Service.
-
-``` code
-az communication bind-cognitive-service --name “{Azure Communication resource name}” --resource-group “{Azure Communication resource group}” --resource-id “{Cognitive service resource id}” --subscription{subscription Name of Cognitive service} –identity{Cognitive Services Identity}
-
-```
+If you would like to use Text-To-Speech capabilities, then it's required for you to connect your [Azure Cognitive Service to your Azure Communication Service](../../../concepts/call-automation/azure-communication-services-azure-cognitive-services-integration.md).
 
 ## Update App.java with code
 
@@ -171,27 +166,30 @@ assertEquals(202, playResponse.getStatusCode()); // The request was accepted
 
 Your application receives action lifecycle event updates on the callback URL that was provided to Call Automation service at the time of answering the call. An example of a successful play event update.
 
-```json 
-[{
-    "id": "704a7a96-4d74-4ebe-9cd0-b7cc39c3d7b1",
-    "source": "calling/callConnections/<callConnectionId>/PlayCompleted",
-    "type": "Microsoft.Communication.PlayCompleted",
-    "data": {
-        "resultInfo": {
-            "code": 200,
-            "subCode": 0,
-            "message": "Action completed successfully."
-        },
-        "type": "playCompleted",
-        "callConnectionId": "<callConnectionId>",
-        "serverCallId": "<serverCallId>",
-        "correlationId": "<correlationId>"
-        },
-    "time": "2022-08-12T03:13:25.0252763+00:00",
-    "specversion": "1.0",
-    "datacontenttype": "application/json",
-    "subject": "calling/callConnections/<callConnectionId>/PlayCompleted"
-}]
+### Example of how you can deserialize the *PlayCompleted* event:
+
+``` java
+if (callEvent instanceof PlayCompleted) {
+     CallAutomationEventWithReasonCodeBase playCompleted= (CallAutomationEventWithReasonCodeBase) callEvent;
+     Reasoncode reasonCode = playCompleted.getReasonCode();
+     ResultInformation = playCompleted.getResultInformation();
+     //Play audio completed, Take some action on completed event.
+     // Hang up call
+     callConnection.hangUp(true);
+}
+```
+
+### Example of how you can deserialize the *PlayFailed* event:
+
+``` java
+if (callEvent instanceof PlayFailed) {
+     CallAutomationEventWithReasonCodeBase playFailed = (CallAutomationEventWithReasonCodeBase) callEvent;
+     Reasoncode reasonCode = playFailed.getReasonCode();
+     ResultInformation = playFailed.getResultInformation();
+     //Play audio failed, Take some action on failed event.
+     // Hang up call
+     callConnection.hangUp(true);
+}
 ```
 
 To learn more about other supported events, visit the [Call Automation overview document](../../../concepts/call-automation/call-automation.md#call-automation-webhook-events).
@@ -205,3 +203,16 @@ var callConnection = callAutomationAsyncClient.getCallConnectionAsync(<callConne
 var cancelResponse = callConnection.getCallMediaAsync().cancelAllMediaOperationsWithResponse().block();
 assertEquals(202, cancelResponse.getStatusCode()); // The request was accepted
 ```
+
+### Example of how you can deserialize the *PlayCanceled* event:
+
+``` java
+if (callEvent instanceof PlayCanceled {
+     CallAutomationEventWithReasonCodeBase playCanceled= (CallAutomationEventWithReasonCodeBase) callEvent;
+     Reasoncode reasonCode = playCanceled.getReasonCode();
+     ResultInformation = playCanceled.getResultInformation();
+     //Play audio completed, Take some action on canceled event.
+     // Hang up call
+     callConnection.hangUp(true);
+}
+```

articles/communication-services/concepts/call-automation/media/enable-system-identity.png

@@ -30,7 +30,7 @@ The following parameters are available to customize the Recognize function:
 | InterToneTimeout | TimeSpan | 2 seconds <br/><br/>**Min:** 1 second <br/>**Max:** 60 seconds | Limit in seconds that ACS will wait for the caller to press another digit (inter-digit timeout). | Optional |
 | InitialSegmentationSilenceTimeoutInSeconds | Integer | 0.5 seconds | How long recognize action will wait for input before considering it a timeout. [Read more here](../../../../../articles/cognitive-services/Speech-Service/how-to-recognize-speech.md). | Optional |
 | RecognizeInputsType | Enum | dtmf | Type of input that will be recognized. Options will be dtmf and choices. | Required |
-| InitialSilenceTimeout | TimeSpan | 5 seconds<br/><br/>**Min:** 0 seconds <br/>**Max:** 300 seconds | Initial silence timeout adjusts how much non-speech audio is allowed before a phrase before the recognition attempt ends in a "no match" result. [Read more here](../../../../../articles/cognitive-services/Speech-Service/how-to-recognize-speech.md). | Optional |
+| InitialSilenceTimeout | TimeSpan | 5 seconds<br/><br/>**Min:** 0 seconds <br/>**Max:** 300 seconds (DTMF) <br/>**Max:** 20 seconds (Choices)| Initial silence timeout adjusts how much non-speech audio is allowed before a phrase before the recognition attempt ends in a "no match" result. [Read more here](../../../../../articles/cognitive-services/Speech-Service/how-to-recognize-speech.md). | Optional |
 | MaxTonesToCollect | Integer | No default<br/><br/>**Min:** 1|Number of digits a developer expects as input from the participant.| Required |
 | StopTones |IEnumeration\<DtmfTone\> | Not set | The digit participants can press to escape out of a batch DTMF event. | Optional |
 | InterruptPrompt | Bool | True | If the participant has the ability to interrupt the playMessage by pressing a digit. | Optional |
@@ -128,74 +128,6 @@ var targetParticipant = new PhoneNumberIdentifier("+1XXXXXXXXXXX");
 
 Developers can subscribe to the *RecognizeCompleted* and *RecognizeFailed* events on the webhook callback they registered for the call to create business logic in their application for determining next steps when one of the previously mentioned events occurs. 
 
-### Example of DTMF *RecognizeCompleted* event:
-``` json
-[
-    {
-        "id": "e9cf1c71-f119-48db-86ca-4f2530a2004d",
-        "source": "calling/callConnections/411f0b00-d97f-49ad-a6ff-3f8c05dc64d7/RecognizeCompleted",
-        "type": "Microsoft.Communication.RecognizeCompleted",
-        "data": {
-            "eventSource": "calling/callConnections/411f0b00-d97f-49ad-a6ff-3f8c05dc64d7/RecognizeCompleted",
-            "operationContext": "267e33a9-c28e-4ecf-a33e-b3abd9526e32",
-            "resultInformation": {
-                "code": 200,
-                "subCode": 8531,
-                "message": "Action completed, max digits received."
-            },
-            "recognitionType": "dtmf",
-            "collectTonesResult": {
-                "tones": [
-                    "nine",
-                    "eight",
-                    "zero",
-                    "five",
-                    "two"
-                ]
-            },
-            "callConnectionId": "411f0b00-d97f-49ad-a6ff-3f8c05dc64d7",
-            "serverCallId": "aHR0cHM6Ly9hcGkuZmxpZ2h0cHJveHkuc2t5cGUuY29tL2FwaS92Mi9jcC9jb252LXVzZWEyLTAxLmNvbnYuc2t5cGUuY29tL2NvbnYvQzNuT3lkY3E0VTZCV0gtcG1GNmc1Zz9pPTQmZT02Mzc5ODYwMDMzNDQ2MTA5MzM=",
-            "correlationId": "53be6977-d832-4c42-8527-fb2aa4a78b74"
-        },
-        "time": "2022-09-13T00:55:08.2240104+00:00",
-        "specversion": "1.0",
-        "datacontenttype": "application/json",
-        "subject": "calling/callConnections/411f0b00-d97f-49ad-a6ff-3f8c05dc64d7/RecognizeCompleted"
-    }
-]
-```
-### Example of Choices *RecognizeCompleted* event:
-``` json
-[
-    {
-        "id": "cf41d1b3-663d-45ab-94d6-7ff130f41839",
-        "source": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41",
-        "type": "Microsoft.Communication.RecognizeCompleted",
-        "data": {
-            "eventSource": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41",
-            "operationContext": "AppointmentReminderMenu",
-            "resultInformation": {
-                "code": 200,
-                "subCode": 8545,
-                "message": "Action completed, Recognized phrase matches a valid option."
-            },
-            "recognitionType": "choices",
-            "choiceResult": {
-                "label": "Confirm",
-                "recognizedPhrase": "confirm"
-            },
-            "callConnectionId": "411f7000-1831-48f7-95f3-b8ee7470dd41",
-            "serverCallId": "aHR0cHM6Ly9hcGkuZXAtZGV2LnNreXBlLm5ldC9hcGerteeqwertrtertsdfrYtMjAwLmNvbnYtZGV2LnNreXBlLm5ldC9jb252L3dIMTZkNk1VxTjNtajc5M2w2eXc/aTyJmU9N45dfg4MDg5MDEyOTMyODg1OTY5",
-            "correlationId": "0f40d4ea-2e26-412a-ad43-171411927bf3"
-        },
-        "time": "2023-01-10T00:28:56.7369845+00:00",
-        "specversion": "1.0",
-        "datacontenttype": "application/json",
-        "subject": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41"
-    }
-]
-```
-
 ### Example of how you can deserialize the *RecognizeCompleted* event:
 ``` csharp
         if (@event is RecognizeCompleted { OperationContext: "AppointmentReminderMenu" })
@@ -225,60 +157,6 @@ Developers can subscribe to the *RecognizeCompleted* and *RecognizeFailed* event
         }
 ```
 
-### Example of DTMF *RecognizeFailed* event:
-``` json
-[
-    {
-        "id": "47d9cb04-7039-427b-af50-aebdd94db054",
-        "source": "calling/callConnections/411f0b00-bb72-4d5b-9524-ae1c29713335/RecognizeFailed",
-        "type": "Microsoft.Communication.RecognizeFailed",
-        "data": {
-            "eventSource": "calling/callConnections/411f0b00-bb72-4d5b-9524-ae1c29713335/RecognizeFailed",
-            "operationContext": "267e33a9-c28e-4ecf-a33e-b3abd9526e32",
-            "resultInformation": {
-                "code": 500,
-                "subCode": 8511,
-                "message": "Action failed, encountered failure while trying to play the prompt."
-            },
-            "callConnectionId": "411f0b00-bb72-4d5b-9524-ae1c29713335",
-            "serverCallId": "aHR0cHM6Ly9hcGkuZmxpZ2h0cHJveHkuc2t5cGUuY29tL2FwaS92Mi9jcC9jb252LXVzZWEyLTAxLmNvbnYuc2t5cGUuY29tL2NvbnYvQzNuT3lkY3E0VTZCV0gtcG1GNmc1Zz9pPTQmZT02Mzc5ODYwMDMzNDQ2MTA5MzM=",
-            "correlationId": "53be6977-d832-4c42-8527-fb2aa4a78b74"
-        },
-        "time": "2022-09-13T00:55:37.0660233+00:00",
-        "specversion": "1.0",
-        "datacontenttype": "application/json",
-        "subject": "calling/callConnections/411f0b00-bb72-4d5b-9524-ae1c29713335/RecognizeFailed"
-    }
-]
-```
-
-### Example of Choices *RecognizeFailed* event: 
-``` json
-[
-    {
-        "id": "264be623-5915-415e-bf06-2165e3fa0a08",
-        "source": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41",
-        "type": "Microsoft.Communication.RecognizeFailed",
-        "data": {
-            "eventSource": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41",
-            "operationContext": "AppointmentReminderMenu",
-            "resultInformation": {
-                "code": 400,
-                "subCode": 8547,
-                "message": "Action failed, recognized phrase does not match a valid option."
-            },
-            "callConnectionId": "411f7000-1831-48f7-95f3-b8ee7470dd41",
-            "serverCallId": "aHR0cHM6Ly9hcGkuZXAtZGV2LnNreXBlLm5ldC9hcGkvdjIvY3AvY29udi1kZXYtMjAwLmNvbnYtZGV2LnNreXBlLm5ldC9jb252L3dIMTZkNkJYU1VxTjNtajc5M2w2eXc/aT0yJmU9NjM4MDg5MDEyOTMyODg1OTY5",
-            "correlationId": "0f40d4ea-2e26-412a-ad43-171411927bf3"
-        },
-        "time": "2023-01-10T00:29:30.300373+00:00",
-        "specversion": "1.0",
-        "datacontenttype": "application/json",
-        "subject": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41"
-    }
-]
-```
-
 ### Example of how you can deserialize the *RecognizeFailed* event:
 ``` csharp
 if (@event is RecognizeFailed { OperationContext: "AppointmentReminderMenu" })
@@ -308,28 +186,6 @@ if (@event is RecognizeFailed { OperationContext: "AppointmentReminderMenu" })
         }
 ```
 
-### Example of *RecognizeCanceled* event:
-``` json
-[
-    {
-        "id": "d4f2e476-fb8f-43c2-abf8-0981f8e70df9",
-        "source": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41",
-        "type": "Microsoft.Communication.RecognizeCanceled",
-        "data": {
-            "eventSource": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41",
-            "operationContext": "AppointmentChoiceMenu",
-            "callConnectionId": "411f7000-1831-48f7-95f3-b8ee7470dd41",
-            "serverCallId": "aHR0cHM6Ly9hcGkuZXAtZGV2LnNreXBlLm5ldC9hcGkvdjIvY3AvY29udi1kZXYtMjAwLmNvbnYtZGV2LnNreXBlLm5ldC9jb252L3dIMTZkNkJYU1VxTjNtajc5M2w2eXc/aT0yJmU9NjM4MDg5MDEyOTMyODg1OTY5",
-            "correlationId": "0f40d4ea-2e26-412a-ad43-171411927bf3"
-        },
-        "time": "2023-01-10T00:31:15.3606572+00:00",
-        "specversion": "1.0",
-        "datacontenttype": "application/json",
-        "subject": "calling/callConnections/411f7000-1831-48f7-95f3-b8ee7470dd41"
-    }
-]
-```
-
 ### Example of how you can deserialize the *RecognizeCanceled* event:
 ``` csharp
 if (@event is RecognizeCanceled { OperationContext: "AppointmentReminderMenu" })