|
| 1 | +--- |
| 2 | +title: include file |
| 3 | +description: C# recognize action quickstart |
| 4 | +services: azure-communication-services |
| 5 | +author: Kunaal |
| 6 | +ms.service: azure-communication-services |
| 7 | +ms.subservice: azure-communication-services |
| 8 | +ms.date: 09/16/2022 |
| 9 | +ms.topic: include |
| 10 | +ms.topic: include file |
| 11 | +ms.author: kpunjabi |
| 12 | +--- |
| 13 | + |
| 14 | +## Prerequisites |
| 15 | +- Azure account with an active subscription, for details see [Create an account for free.](https://azure.microsoft.com/free/) |
| 16 | +- Azure Communication Services resource. See [Create an Azure Communication Services resource](../../../create-communication-resource.md?tabs=windows&pivots=platform-azp) |
| 17 | +- Create a new web service application using the [Call Automation SDK](../../Callflows-for-customer-interactions.md). |
| 18 | +- The latest [.NET library](https://dotnet.microsoft.com/download/dotnet-core) for your operating system. |
| 19 | +- [Apache Maven](https://maven.apache.org/download.cgi). |
| 20 | +- Obtain the NuGet package from the [Azure SDK Dev Feed](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md#nuget-package-dev-feed) |
| 21 | + |
| 22 | +## Technical specifications |
| 23 | + |
| 24 | +The following parameters are available to customize the Recognize function: |
| 25 | + |
| 26 | +| Parameter | Type|Default (if not specified) | Description | Required or Optional | |
| 27 | +| ------- |--| ------------------------ | --------- | ------------------ | |
| 28 | +| Prompt <br/><br/> *(for details on Play action, refer to [this quickstart](../../play-action.md))* | FileSource | Not set |This will be the message you wish to play before recognizing input. | Optional | |
| 29 | +| 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 | |
| 30 | +| InitialSilenceTimeout | TimeSpan | 5seconds<br/><br/>**Min:** 0 seconds <br/>**Max:** 300 seconds | How long recognize action will wait for input before considering it a timeout. | Optional | |
| 31 | +| MaxTonesToCollect | Integer | No default<br/><br/>**Min:** 1|Number of digits a developer expects as input from the participant.| Required | |
| 32 | +| StopTones |IEnumeration\<DtmfTone\> | Not set | The digit participants can press to escape out of a batch DTMF event. | Optional | |
| 33 | +| InterruptPrompt | Bool | True | If the participant has the ability to interrupt the playMessage by pressing a digit. | Optional | |
| 34 | +| InterruptCallMediaOperation | Bool | True | If this flag is set it will interrupt the current call media operation if any (for example if play is going on) and initiate recognize. | Optional | |
| 35 | +| OperationContext | String | Not set | String that developers can pass mid action, useful for allowing developers to store context about the events they receive. | Optional | |
| 36 | + |
| 37 | +## Create a new C# application |
| 38 | + |
| 39 | +In the console window of your operating system, use the `dotnet` command to create a new web application. |
| 40 | + |
| 41 | +```console |
| 42 | +dotnet new web -n MyApplication |
| 43 | +``` |
| 44 | + |
| 45 | +## Install the NuGet package |
| 46 | + |
| 47 | +During the preview phase, the NuGet package can be obtained by configuring your package manager to use the Azure SDK Dev Feed from [here](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md#nuget-package-dev-feed) |
| 48 | + |
| 49 | +## Obtain your connection string |
| 50 | + |
| 51 | +From the Azure portal, locate your Communication Service resource and click on the Keys section to obtain your connection string. |
| 52 | + |
| 53 | +:::image type="content" source="./../../media/call-automation/Key.png" alt-text="Screenshot of Communication Services resource page on portal to access keys"::: |
| 54 | + |
| 55 | +## Establish a call |
| 56 | + |
| 57 | +By this point you should be familiar with starting calls, if you need to learn more about how to start a call view our [quickstart](../../Callflows-for-customer-interactions.md). In this instance, we'll answer an incoming call. |
| 58 | + |
| 59 | +## Call the recognize action |
| 60 | + |
| 61 | +When your application answers the call, you can provide information about recognizing participant input and playing a prompt. |
| 62 | + |
| 63 | +``` csharp |
| 64 | +var targetParticipant = new PhoneNumberIdentifier("+1XXXXXXXXXXX"); |
| 65 | + var recognizeOptions = new CallMediaRecognizeDtmfOptions(targetParticipant, maxTonesToCollect) |
| 66 | + { |
| 67 | + InterruptCallMediaOperation = true, |
| 68 | + InitialSilenceTimeout = TimeSpan.FromSeconds(30), |
| 69 | + Prompt = new FileSource(new System.Uri("file://path/to/file")), |
| 70 | + InterToneTimeout = TimeSpan.FromSeconds(5), |
| 71 | + InterruptPrompt = true, |
| 72 | + StopTones = new DtmfTone[] { DtmfTone.Pound }, |
| 73 | + }; |
| 74 | + await _callConnection.GetCallMedia().StartRecognizingAsync(recognizeOptions).ConfigureAwait(false); |
| 75 | + |
| 76 | +``` |
| 77 | + |
| 78 | +**Note:** If parameters aren't set, the defaults will be applied where possible. |
| 79 | + |
| 80 | +## Receiving recognize event updates |
| 81 | + |
| 82 | +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 aforementioned events occurs. |
| 83 | + |
| 84 | +Example of *RecognizeCompleted* event: |
| 85 | +``` json |
| 86 | +[ |
| 87 | + { |
| 88 | + "id": "e9cf1c71-f119-48db-86ca-4f2530a2004d", |
| 89 | + "source": "calling/callConnections/411f0b00-d97f-49ad-a6ff-3f8c05dc64d7/RecognizeCompleted", |
| 90 | + "type": "Microsoft.Communication.RecognizeCompleted", |
| 91 | + "data": { |
| 92 | + "eventSource": "calling/callConnections/411f0b00-d97f-49ad-a6ff-3f8c05dc64d7/RecognizeCompleted", |
| 93 | + "operationContext": "267e33a9-c28e-4ecf-a33e-b3abd9526e32", |
| 94 | + "resultInformation": { |
| 95 | + "code": 200, |
| 96 | + "subCode": 8531, |
| 97 | + "message": "Action completed, max digits received." |
| 98 | + }, |
| 99 | + "recognitionType": "dtmf", |
| 100 | + "collectTonesResult": { |
| 101 | + "tones": [ |
| 102 | + "nine", |
| 103 | + "eight", |
| 104 | + "zero", |
| 105 | + "five", |
| 106 | + "two" |
| 107 | + ] |
| 108 | + }, |
| 109 | + "callConnectionId": "411f0b00-d97f-49ad-a6ff-3f8c05dc64d7", |
| 110 | + "serverCallId": "aHR0cHM6Ly9hcGkuZmxpZ2h0cHJveHkuc2t5cGUuY29tL2FwaS92Mi9jcC9jb252LXVzZWEyLTAxLmNvbnYuc2t5cGUuY29tL2NvbnYvQzNuT3lkY3E0VTZCV0gtcG1GNmc1Zz9pPTQmZT02Mzc5ODYwMDMzNDQ2MTA5MzM=", |
| 111 | + "correlationId": "53be6977-d832-4c42-8527-fb2aa4a78b74" |
| 112 | + }, |
| 113 | + "time": "2022-09-13T00:55:08.2240104+00:00", |
| 114 | + "specversion": "1.0", |
| 115 | + "datacontenttype": "application/json", |
| 116 | + "subject": "calling/callConnections/411f0b00-d97f-49ad-a6ff-3f8c05dc64d7/RecognizeCompleted" |
| 117 | + } |
| 118 | +] |
| 119 | +``` |
| 120 | + |
| 121 | +Example of how you can deserialize the *RecognizeCompleted* event: |
| 122 | +``` csharp |
| 123 | +app.MapPost("<WEB_HOOK_ENDPOINT>", async ( |
| 124 | + [FromBody] CloudEvent[] cloudEvents, |
| 125 | + [FromRoute] string contextId) =>{ |
| 126 | + foreach (var cloudEvent in cloudEvents) |
| 127 | + { |
| 128 | + CallAutomationEventBase @event = CallAutomationEventParser.Parse(cloudEvent); |
| 129 | + If (@event is RecognizeCompleted recognizeCompleted) |
| 130 | + { |
| 131 | + // Access to the Collected Tones |
| 132 | + foreach(DtmfTone tone in recognizeCompleted.CollectTonesResult.Tones) { |
| 133 | + // work on each of the Dtmf tones. |
| 134 | + } |
| 135 | + } |
| 136 | +``` |
| 137 | + |
| 138 | +Example of *RecognizeFailed* event: |
| 139 | + |
| 140 | +``` json |
| 141 | +[ |
| 142 | + { |
| 143 | + "id": "47d9cb04-7039-427b-af50-aebdd94db054", |
| 144 | + "source": "calling/callConnections/411f0b00-bb72-4d5b-9524-ae1c29713335/RecognizeFailed", |
| 145 | + "type": "Microsoft.Communication.RecognizeFailed", |
| 146 | + "data": { |
| 147 | + "eventSource": "calling/callConnections/411f0b00-bb72-4d5b-9524-ae1c29713335/RecognizeFailed", |
| 148 | + "operationContext": "267e33a9-c28e-4ecf-a33e-b3abd9526e32", |
| 149 | + "resultInformation": { |
| 150 | + "code": 500, |
| 151 | + "subCode": 8511, |
| 152 | + "message": "Action failed, encountered failure while trying to play the prompt." |
| 153 | + }, |
| 154 | + "callConnectionId": "411f0b00-bb72-4d5b-9524-ae1c29713335", |
| 155 | + "serverCallId": "aHR0cHM6Ly9hcGkuZmxpZ2h0cHJveHkuc2t5cGUuY29tL2FwaS92Mi9jcC9jb252LXVzZWEyLTAxLmNvbnYuc2t5cGUuY29tL2NvbnYvQzNuT3lkY3E0VTZCV0gtcG1GNmc1Zz9pPTQmZT02Mzc5ODYwMDMzNDQ2MTA5MzM=", |
| 156 | + "correlationId": "53be6977-d832-4c42-8527-fb2aa4a78b74" |
| 157 | + }, |
| 158 | + "time": "2022-09-13T00:55:37.0660233+00:00", |
| 159 | + "specversion": "1.0", |
| 160 | + "datacontenttype": "application/json", |
| 161 | + "subject": "calling/callConnections/411f0b00-bb72-4d5b-9524-ae1c29713335/RecognizeFailed" |
| 162 | + } |
| 163 | +] |
| 164 | + |
| 165 | +``` |
| 166 | + |
| 167 | +Example of how you can deserialize the *RecognizeFailed* event: |
| 168 | + |
| 169 | +``` csharp |
| 170 | +app.MapPost("<WEB_HOOK_ENDPOINT>", async ( |
| 171 | + [FromBody] CloudEvent[] cloudEvents, |
| 172 | + [FromRoute] string contextId) =>{ |
| 173 | + foreach (var cloudEvent in cloudEvents) |
| 174 | + { |
| 175 | + CallAutomationEventBase @event = CallAutomationEventParser.Parse(cloudEvent); |
| 176 | + If (@event is RecognizeFailed recognizeFailed) |
| 177 | + { |
| 178 | + Log.error($”Recognize failed due to: {recognizeFailed.ResultInformation.Message}”); |
| 179 | + |
| 180 | + } |
| 181 | + } |
| 182 | +``` |
0 commit comments