Skip to content

Commit 46d617c

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #226886 from ddematheu2/acs-events-docs
Acs events docs
2 parents cc2c403 + e002103 commit 46d617c

20 files changed

+689
-2
lines changed

‎articles/communication-services/how-tos/call-automation/record-every-call.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
title: Record a call when it starts
3+
titleSuffix: An Azure Communication Services how-to document
4+
description: In this how-to document, you can learn how to record a call through Azure Communication Services once it starts.
5+
author: ddematheu2
6+
manager: shahen
7+
services: azure-communication-services
8+
ms.author: dademath
9+
ms.topic: how-to
10+
ms.service: azure-communication-services
11+
ms.date: 03/01/2023
12+
---
13+
14+
# Record a call when it starts
15+
16+
Call recording is often used directly through the UI of a calling application, where the user triggers the recording. For applications within industries like banking or healthcare, call recording is required from the get-go. The service needs to automatically record for compliance purposes. This sample shows how to record a call when it starts. It uses Azure Communication Services and Azure Event Grid to trigger an Azure Function when a call starts. It automatically records every call within your Azure Communication Services resource.
17+
18+
In this QuickStart, we focus on showcasing the processing of call started events through Azure Functions using Event Grid triggers. We use the Call Automation SDK for Azure Communication Services to start recording.
19+
20+
The Call Started event when a call start is formatted in the following way:
21+
22+
```json
23+
24+
[
25+
{
26+
"id": "a8bcd8a3-12d7-46ba-8cde-f6d0bda8feeb",
27+
"topic": "/subscriptions/{subscription-id}/resourcegroups/{group-name}/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
28+
"subject": "call/{serverCallId}/startedBy/8:acs:bc360ba8-d29b-4ef2-b698-769ebef85521_0000000c-1fb9-4878-07fd-0848220077e1",
29+
"data": {
30+
"startedBy": {
31+
"communicationIdentifier": {
32+
"rawId": "8:acs:bc360ba8-d29b-4ef2-b698-769ebef85521_0000000c-1fb9-4878-07fd-0848220077e1",
33+
"communicationUser": {
34+
"id": "8:acs:bc360ba8-d29b-4ef2-b698-769ebef85521_0000000c-1fb9-4878-07fd-0848220077e1"
35+
}
36+
},
37+
"role": "{role}"
38+
},
39+
"serverCallId": "{serverCallId}",
40+
"group": {
41+
"id": "00000000-0000-0000-0000-000000000000"
42+
},
43+
"room": {
44+
"id": "{roomId}"
45+
},
46+
"isTwoParty": false,
47+
"correlationId": "{correlationId}",
48+
"isRoomsCall": true
49+
},
50+
"eventType": "Microsoft.Communication.CallStarted",
51+
"dataVersion": "1.0",
52+
"metadataVersion": "1",
53+
"eventTime": "2021-09-22T17:02:38.6905856Z"
54+
}
55+
]
56+
57+
```
58+
59+
## Pre-requisites
60+
61+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
62+
- An active Communication Services resource and connection string. [Create a Communication Services resource](../../quickstarts/create-communication-resource.md).
63+
- Install [Azure CLI](/cli/azure/install-azure-cli-windows?tabs=azure-cli).
64+
65+
## Setting up our local environment
66+
67+
1. Using [Visual Studio Code](https://code.visualstudio.com/), install the [Azure Functions Extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions).
68+
2. With the extension, create an Azure Function following these [instructions](../../../azure-functions/create-first-function-vs-code-csharp.md).
69+
70+
Configure the function with the following instructions:
71+
- Language: C#
72+
- Template: Azure Event Grid Trigger
73+
- Function Name: User defined
74+
75+
Once created, you see a function created in your directory like this:
76+
77+
```csharp
78+
79+
using System;
80+
using Microsoft.Azure.WebJobs;
81+
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
82+
using Microsoft.Extensions.Logging;
83+
using Azure.Messaging.EventGrid;
84+
using System.Threading.Tasks;
85+
86+
namespace Company.Function
87+
{
88+
public static class acs_recording_test
89+
{
90+
[FunctionName("acs_recording_test")]
91+
public static async Task RunAsync([EventGridTrigger]EventGridEvent eventGridEvent, ILogger log)
92+
{
93+
log.LogInformation(eventGridEvent.EventType);
94+
}
95+
96+
}
97+
}
98+
99+
```
100+
101+
## Configure Azure Function to receive `CallStarted` event
102+
103+
1. Configure Azure Function to perform actions when the `CallStarted` event triggers.
104+
105+
```csharp
106+
107+
public static async Task RunAsync([EventGridTrigger]EventGridEvent eventGridEvent, ILogger log)
108+
{
109+
if(eventGridEvent.EventType == "Microsoft.Communication.CallStarted")
110+
{
111+
log.LogInformation("Call started");
112+
var callEvent = eventGridEvent.Data.ToObjectFromJson<CallStartedEvent>();
113+
114+
// CallStartedEvent class is defined in documentation, but the objects looks like this:
115+
// public class CallStartedEvent
116+
// {
117+
// public StartedBy startedBy { get; set; }
118+
// public string serverCallId { get; set; }
119+
// public Group group { get; set; }
120+
// public bool isTwoParty { get; set; }
121+
// public string correlationId { get; set; }
122+
// public bool isRoomsCall { get; set; }
123+
// }
124+
// public class Group
125+
// {
126+
// public string id { get; set; }
127+
// }
128+
// public class StartedBy
129+
// {
130+
// public CommunicationIdentifier communicationIdentifier { get; set; }
131+
// public string role { get; set; }
132+
// }
133+
// public class CommunicationIdentifier
134+
// {
135+
// public string rawId { get; set; }
136+
// public CommunicationUser communicationUser { get; set; }
137+
// }
138+
// public class CommunicationUser
139+
// {
140+
// public string id { get; set; }
141+
// }
142+
}
143+
}
144+
145+
```
146+
147+
## Start recording
148+
149+
1. Create a method to handle the `CallStarted` events. This method trigger recording to start when the call started.
150+
151+
```csharp
152+
153+
public static async Task RunAsync([EventGridTrigger]EventGridEvent eventGridEvent, ILogger log)
154+
{
155+
if(eventGridEvent.EventType == "Microsoft.Communication.CallStarted")
156+
{
157+
log.LogInformation("Call started");
158+
var callEvent = eventGridEvent.Data.ToObjectFromJson<CallStartedEvent>();
159+
await startRecordingAsync(callEvent.serverCallId);
160+
}
161+
}
162+
163+
public static async Task startRecordingAsync (String serverCallId)
164+
{
165+
CallAutomationClient callAutomationClient = new CallAutomationClient(Environment.GetEnvironmentVariable("ACS_CONNECTION_STRING"));
166+
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator(serverCallId));
167+
recordingOptions.RecordingChannel = RecordingChannel.Mixed;
168+
recordingOptions.RecordingContent = RecordingContent.AudioVideo;
169+
recordingOptions.RecordingFormat = RecordingFormat.Mp4;
170+
var startRecordingResponse = await callAutomationClient.GetCallRecording()
171+
.StartRecordingAsync(recordingOptions).ConfigureAwait(false);
172+
}
173+
174+
```
175+
176+
### Running locally
177+
178+
To run the function locally, you can press `F5` in Visual Studio Code. We use [ngrok](https://ngrok.com/) to hook our locally running Azure Function with Azure Event Grid.
179+
180+
1. Once the function is running, we configure ngrok. (You need to [download ngrok](https://ngrok.com/download) for your environment.)
181+
182+
```bash
183+
184+
ngrok http 7071
185+
186+
```
187+
188+
Copy the ngrok link provided where your function is running.
189+
190+
2. Configure C`allStarted` events through Event Grid within your Azure Communication Services resource. We do this using the [Azure CLI](/cli/azure/install-azure-cli-windows?tabs=azure-cli). You need the resource ID for your Azure Communication Services resource found in the Azure portal. (The resource ID looks something like:  `/subscriptions/<<AZURE SUBSCRIPTION ID>>/resourceGroups/<<RESOURCE GROUP NAME>>/providers/Microsoft.Communication/CommunicationServices/<<RESOURCE NAME>>`)
191+
192+
```bash
193+
194+
az eventgrid event-subscription create --name "<<EVENT_SUBSCRIPTION_NAME>>" --endpoint-type webhook --endpoint "<<NGROK URL>>/runtime/webhooks/EventGrid?functionName=<<FUNCTION NAME>> " --source-resource-id "<<RESOURCE_ID>>" --included-event-types Microsoft.Communication.CallStarted
195+
196+
```
197+
198+
3. Now that everything is hooked up, test the flow by starting a call on your resource. You should see the console logs on your terminal where the function is running. You can check that the recording is starting by using the [call recording feature](../calling-sdk/record-calls.md?pivots=platform-web) on the calling SDK and check for the boolean to turn TRUE.
199+
200+
### Deploy to Azure
201+
202+
To deploy the Azure Function to Azure, you need to follow these [instructions](../../../azure-functions/create-first-function-vs-code-csharp.md#deploy-the-project-to-azure). Once deployed, we configure Event Grid for the Azure Communication Services resource. With the URL for the Azure Function that was deployed (URL found in the Azure portal under the function), we run a similar command:
203+
204+
```bash
205+
206+
az eventgrid event-subscription update --name "<<EVENT_SUBSCRIPTION_NAME>>" --endpoint-type azurefunction --endpoint "<<AZ FUNCTION URL>> " --source-resource-id "<<RESOURCE_ID>>"
207+
208+
```
209+
210+
Since we're updating the event subscription we created, make sure to use the same event subscription name you used in the previous step.
211+
212+
You can test by starting a call in your resource, similar to the previous step.

‎articles/communication-services/how-tos/event-grid/local-testing-event-grid.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Test your Event Grid handler locally
3+
titleSuffix: An Azure Communication Services how-to document
4+
description: In this how-to document, you can learn how to locally test your Event Grid handler for Azure Communication Services events with Postman.
5+
author: ddematheu2
6+
manager: shahen
7+
services: azure-communication-services
8+
ms.author: dademath
9+
ms.date: 02/09/2023
10+
ms.topic: how-to
11+
ms.service: azure-communication-services
12+
---
13+
14+
# Test your Event Grid handler locally
15+
16+
Testing Event Grid triggered Azure Functions locally can be complicated. You don't want to have to trigger events over and over to test your flow. It can also get expensive as triggering those events might require you perform an event that costs money like sending an SMS or placing a phone call. To help with testing, we show you how to use Postman to trigger your Azure Function with a payload that mimics the Event Grid event.
17+
18+
## Pre-requisites
19+
20+
- Install [Postman](https://www.postman.com/downloads/).
21+
- Have a running Azure Function that can be triggered by Event Grid. If you don't have one, you can follow the [quickstart](../../../azure-functions/functions-bindings-event-grid-trigger.md?tabs=in-process%2Cextensionv3&pivots=programming-language-javascript) to create one.
22+
23+
The Azure Function can be running either in Azure if you want to test it with some test events or if you want to test the entire flow locally (press `F5` in Visual Studio Code to run it locally). If you want to test the entire flow locally, you need to use [ngrok](https://ngrok.com/) to hook your locally running Azure Function. Configure ngrok by running the command:
24+
25+
```bash
26+
27+
ngrok http 7071
28+
29+
```
30+
31+
## Configure Postman
32+
33+
1. Open Postman and create a new request.
34+
35+
![Screenshot of Postman body configuration.](media/postman-body.png)
36+
37+
2. Select the `POST` method.
38+
39+
3. Enter the URL of your Azure Function. Can either be the URL of the Azure Function running in Azure or the ngrok URL if you're running it locally. Ensure that you add the function name at the end of the URL: `/runtime/webhooks/EventGrid?functionName=<<FUNCTION_NAME>>`.
40+
41+
4. Select the `Body` tab and select `raw` and `JSON` from the dropdown. In the body, you add a test schema for the event you want to trigger. For example, if you're testing an Azure Function that is triggered by receiving SMS events, you add the following:
42+
43+
```json
44+
45+
{
46+
"id": "Incoming_20200918002745d29ebbea-3341-4466-9690-0a03af35228e",
47+
"topic": "/subscriptions/50ad1522-5c2c-4d9a-a6c8-67c11ecb75b8/resourcegroups/acse2e/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
48+
"subject": "/phonenumber/15555555555",
49+
"data": {
50+
"MessageId": "Incoming_20200918002745d29ebbea-3341-4466-9690-0a03af35228e",
51+
"From": "15555555555",
52+
"To": "15555555555",
53+
"Message": "Great to connect with ACS events",
54+
"ReceivedTimestamp": "2020-09-18T00:27:45.32Z"
55+
},
56+
"eventType": "Microsoft.Communication.SMSReceived",
57+
"dataVersion": "1.0",
58+
"metadataVersion": "1",
59+
"eventTime": "2020-09-18T00:27:47Z"
60+
}
61+
62+
```
63+
64+
You can find more information for the different event types used for Azure Communication Services in the [documentation](../../../event-grid/event-schema-communication-services.md).
65+
66+
5. Select the `Headers` tab and add the following headers:
67+
68+
- `Content-Type`: `application/json`
69+
- `aeg-event-type`: `Notification`
70+
71+
![Screenshot of Postman headers configuration.](media/postman-header.png)
72+
73+
6. Select the `Send` button to trigger the event.
74+
75+
![Screenshot of Postman send button.](media/postman-send.png)
76+
77+
At this point, an event should trigger in your Azure Function. You can verify the event by looking at the execution of your Azure Function. You can then validate that the function is doing its job correctly.

‎articles/communication-services/how-tos/event-grid/media/acs-resource-events.png

10.3 KB
Loading

‎articles/communication-services/how-tos/event-grid/media/function-init-event-grid.png

27.9 KB
Loading

‎articles/communication-services/how-tos/event-grid/media/postman-body.png

39.4 KB
Loading

‎articles/communication-services/how-tos/event-grid/media/postman-header.png

22.2 KB
Loading

‎articles/communication-services/how-tos/event-grid/media/postman-send.png

4.12 KB
Loading

‎articles/communication-services/how-tos/event-grid/media/requestbin-url.png

43.8 KB
Loading

‎articles/communication-services/how-tos/event-grid/media/validation-request-bin.png

48.7 KB
Loading

‎articles/communication-services/how-tos/event-grid/view-events-request-bin.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Validate Azure Communication Services events
3+
titleSuffix: An Azure Communication Services how-to document
4+
description: In this how-to document, you can learn how to validate Azure Communication Services events with RequestBin or Azure Event Viewer.
5+
author: ddematheu2
6+
manager: shahen
7+
services: azure-communication-services
8+
ms.author: dademath
9+
ms.date: 02/09/2023
10+
ms.topic: how-to
11+
ms.service: azure-communication-services
12+
---
13+
14+
# Validate Azure Communication Services events
15+
16+
This document shows you how to validate that your Azure Communication Services resource sends events using Azure Event Grid viewer or RequestBin.
17+
18+
## Pre-requisites
19+
20+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
21+
- An active Communication Services resource and connection string. [Create a Communication Services resource](../../quickstarts/create-communication-resource.md).
22+
- Install [Azure CLI](/cli/azure/install-azure-cli-windows?tabs=azure-cli).
23+
24+
If you already have an Azure Event Grid viewer deployed or would like to have a more robust viewer in place, you can follow instructions to [deploy it](/samples/azure-samples/azure-event-grid-viewer/azure-event-grid-viewer/). You need the endpoint generated by the Event Grid viewer.
25+
26+
Alternatively, if you want a quick and easy way to validate your events, you can use [RequestBin](https://requestbin.com/). RequestBin offers two modalities to pick from. If you want to quickly test your events, you can use the [public endpoint](https://requestbin.com/r) setup. These public endpoints make event data accessible to anyone with a URL. If you prefer to keep it private, you can create a RequestBin account and create a private endpoint. For more information, see RequestBin [public vs private endpoints](https://requestbin.com/docs/#public-vs-private-endpoints).
27+
28+
![Screenshot of RequestBin URL configuration.](./media/requestbin-url.png)
29+
30+
The next steps are the same for both options.
31+
32+
## Configure your Azure Communication Services resource to send events to your endpoint
33+
34+
1. Using [Azure CLI](/cli/azure/install-azure-cli-windows?tabs=azure-cli), we configure the endpoint we created in the pre-requisites to receive events from your Azure Communication Services resource. You need the resource ID for your Azure Communication Services resource found in the Azure portal.
35+
36+
```bash
37+
38+
az eventgrid event-subscription create --name "<<EVENT_SUBSCRIPTION_NAME>>" --endpoint-type webhook --endpoint "<<URL>> " --source-resource-id "<<RESOURCE_ID>>" --included-event-types Microsoft.Communication.SMSReceived
39+
40+
```
41+
42+
In the command, we only added the `Microsoft.Communication.SMSReceived` event type. You can add more event types to the command if you would like to receive more events. For a list of all the event types, see [Azure Communication Services events](../../../event-grid/event-schema-communication-services.md).
43+
44+
2. (Optional, only if using RequestBin) You need to copy the `validationURL` on the first event the gets posted to your endpoint. You need to paste that URL on your browser to validate the endpoint. The page should saw 'Webhook successfully validated as a subscription endpoint'.
45+
46+
![Screenshot showing event in RequestBin.](./media/validation-request-bin.png)
47+
48+
## View events
49+
50+
Now that you've configured your endpoint to receive events, you can use it to view events as they come through.

0 commit comments

Comments
 (0)