Quickstart - Subscribe to Azure Communication Services Events - An Azure Communication Services quickstart

Article
02/02/2024

In this quickstart, you learn how to subscribe to events from Azure Communication Services through the portal, Azure CLI, PowerShell and .NET SDK.

You can set up event subscriptions for Communication Services resources through the Azure portal or Azure CLI, PowerShell or with the Azure Event Grid Management SDK.

For this Quickstart, we walk through the process of setting up webhook as a subscriber for SMS events from Azure Communication Services. For a full list of events, see this page.

Prerequisites

An Azure account with an active subscription. Create an account for free.
An Azure Communication Services resource.
Create a Webhook to receive events. Webhook Event Delivery.

Register the Event Grid resource provider

This article describes how to register the Event Grid resource provider. If you used Event Grid before in the same subscription, skip to the next section.

In the Azure portal, do the following steps:

On the left menu, select Subscriptions.
Select the Subscription you want to use for Event Grid from the subscription list.
On the Subscription page, select Resource providers under Settings on the left menu.
Search for Microsoft.EventGrid, and confirm that the Status is Not Registered.
Select Microsoft.EventGrid in the provider list.
Select Register on the command bar.
Refresh to make sure the status of Microsoft.EventGrid is changed to Registered.

Create event subscription

To create an Event subscription for Azure Communication Services, use the following steps. This article shows how to create an Event subscription for Azure Communication Services to receive events via Webhook.

To create an Event subscription for Azure Communication Services resource, first sign in to the Azure portal. In the upper-left corner of the page, select the Communication Services resource.

Select on the Events tab on the left menu.
Select on + Event Subscription.

On the Create Event Subscription page, follow these steps:

Enter a name for the event subscription.
Enter a name for the System topic name.
Select the event types that you want to receive on the event subscription.

For more information on Communication Services events, see Communication Services Events
Select the Endpoint Type as Web Hook.
Select Configure an Endpoint
Enter the link to the webhook and Select Confirm Selection.
In the Filters tab, add the names of the event types you want to filter in the subscription and add context attribute filters you want to use in the subscription. Then, select Next: Additional features at the bottom of the page.
To enable dead lettering and customize retry policies, select Additional Features.
When done, select Create.

Update event subscription

To update an Event subscription for Azure Communication Services, use the following steps. This section shows how to update an Event subscription for Azure Communication Services to update the events you want to receive via Webhook.

To update an Event subscription for Azure Communication Services resource, first sign in to the Azure portal. In the upper-left corner of the page, select the Communication Services resource.

Select the Events tab on the left menu.
Select the Event Subscriptions and select on the Event subscription you want to update.
On the Event Subscription page, select on Filters tab. Select the event types that you want to receive on the event subscription.
To enable dead lettering and customize retry policies, select Additional Features.
To update the webhook to receive events, select on Change next to the webhook link and enter the new webhook endpoint.
When done, select Save,

Delete event subscription

To delete an Event subscription for Azure Communication Services, use the following steps.

To delete an Event subscription for Azure Communication Services resource, first sign in to the Azure portal. In the upper-left corner of the page, select the Communication Services resource.

Select on the Events tab on the left menu.
Select on Event Subscriptions and Select on the Event subscription you want to delete.
On the Event Subscription page, Select on Delete button at the top.

Next steps

For a list of Communication Services events, see Communication Services Events.
For a list of supported event handlers, see Event handlers.
For information about event delivery and retries, Event Grid message delivery and retry.
For an introduction to Event Grid, see About Event Grid.

Prerequisites

An Azure account with an active subscription. Create an account for free.
Install Azure CLI
An Azure Communication Services resource
Create a Webhook to receive events. Webhook Event Delivery

Register the Event Grid resource provider

This article describes how to register the Event Grid resource provider. If you used Event Grid before in the same subscription, skip to the next section.

Run the following command to register the provider:

az provider register --namespace Microsoft.EventGrid

It might take a moment for the registration to finish. To check the status, run the following command:
```
az provider show --namespace Microsoft.EventGrid --query "registrationState"
```
When registrationState is Registered, you're ready to continue.

Create event subscription

To create event subscriptions for Azure Communication Services resource, sign in to Azure CLI. You can sign in running the az login command from the terminal and providing your credentials. Run the following command to create the event subscription for the resource:

To create an event subscription by using the Azure CLI, use the az eventgrid event-subscription create command.

az eventgrid event-subscription create 
    --name EventsWebhookSubscription
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
    --included-event-types Microsoft.Communication.SMSReceived Microsoft.Communication.SMSDeliveryReportReceived
    --endpoint-type webhook 
    --endpoint https://azureeventgridviewer.azurewebsites.net/api/updates

For a list of Communication Services events, see Communication Services Events.

List event subscriptions

To list all the existing event subscriptions set up for an Azure Communication Services resource, by using the Azure CLI, use the az eventgrid event-subscription list command.

az eventgrid event-subscription list 
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>

Update event subscription

To update an existing event subscription by using the Azure CLI, use the az eventgrid event-subscription update command.

az eventgrid event-subscription update 
    --name EventsWebhookSubscription
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
    --included-event-types Microsoft.Communication.SMSReceived Microsoft.Communication.SMSDeliveryReportReceived Microsoft.Communication.ChatMessageReceived
    --endpoint-type webhook 
    --endpoint https://azureeventgridviewer.azurewebsites.net/api/updates

Delete event subscription

To delete an existing event subscription by using the Azure CLI, use the az eventgrid event-subscription delete command.

az eventgrid event-subscription delete 
    --name EventsWebhookSubscription 
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>

Next steps

For information on other commands, see Azure Event Grid CLI.

Prerequisites

An Azure account with an active subscription. Create an account for free.
The latest version .NET Core SDK for your operating system.
Get the latest version of the .NET Microsoft Azure Event Grid Management SDK.
Get the latest version of the Azure Identity library.
An Azure Communication Services resource.

Register the Event Grid resource provider

This article describes how to register the Event Grid resource provider. If you used Event Grid before in the same subscription, skip to the next section.

In the Azure portal, do the following steps:

On the left menu, select Subscriptions.
Select the Subscription you want to use for Event Grid from the subscription list.
On the Subscription page, select Resource providers under Settings on the left menu.
Search for Microsoft.EventGrid, and confirm that the Status is Not Registered.
Select Microsoft.EventGrid in the provider list.
Select Register on the command bar.
Refresh to make sure the status of Microsoft.EventGrid is changed to Registered.

Installing the SDK

First, install the Microsoft Azure Event Grid Management library for .NET with NuGet:

dotnet add package Azure.ResourceManager.EventGrid;

Include the Event Grid Management SDK in your C# project:

using Microsoft.Azure.Management.EventGrid;
using Microsoft.Azure.Management.EventGrid.Models;

Authenticating with Azure Identity library

Prerequisites:

Create a Microsoft Entra application and Service Principal and set up a client secret or trusted certificate issued by certificate authority by following the instructions here.
Store the secret or the certificate in the Azure Keyvault.
Give contributor or owner access to the subscription to that application following the instructions here.
Read more about authorizing access to Event Grid resources here.

The Azure Identity library provides Microsoft Entra ID (Formerly Azure Active Directory) token authentication support across the Azure SDK. It provides a set of TokenCredential implementations, which can be used to construct Azure SDK clients that support Microsoft Entra token authentication. You can read more about it here.

Include the Azure Identity client library for .NET with NuGet:

dotnet add package Azure.Identity;
dotnet add package Azure.Security.KeyVault.Secrets

Include the Azure Identity library in your C# project

using Microsoft.Azure.Identity;
using Azure.Security.KeyVault.Secrets

You can either pass the secret credentials or certificate credentials to get access token, based on how your Service Principal is configured.

Get access token using secret credential

To get the secret credentials, you need to read it from the Keyvault you created in Prerequisite #2 using SecretClient.

// Authenticate the Keyvault client with DefaultAzureCredential and get the secret.
SecretClient secretClient = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
string clientSecret = await secretClient.GetSecretAsync(secretName).Value;

// Get access token using secret credentials
string[] scopes = { "https://management.azure.com/.default" };
var application = ConfidentialClientApplicationBuilder
                    .Create('your-servicePrincipal-appId')
                    .WithAuthority(authorityUri: new Uri(authority), validateAuthority: true)
                    .WithTenantId('your-tenant_id')
                    .WithClientSecret(clientSecret)
                    .Build();

var token = await application
                .AcquireTokenForClient(scopes)
                .ExecuteAsync();

Get access token using certificate credential

To get the certificate credentials, you need to read it from the Keyvault you created in Prerequisite #2 using CertificateClient.

Read more about the Microsoft Entra application configuration authority here

// Authenticate the certificate client with DefaultAzureCredential and get the certificate.
CertificateClient certificateClient = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
X509Certificat2 cert = await certificateClient.DownloadCertificateAsync(certificateName);

// Get access token using certificate credentials
string[] scopes = { "https://management.azure.com/.default" };
string authority = "https://login.microsoftonline.com/<tenant>/";
var application = ConfidentialClientApplicationBuilder
                    .Create('<servicePrincipal-appId>')
                    .WithAuthority(authorityUri: new Uri(authority), validateAuthority: true)
                    .WithTenantId("<tenantId>")
                    .WithCertificate(cert)
                    .Build();

var token = await application
                .AcquireTokenForClient(scopes)
                .WithSendX5C(true)
                .ExecuteAsync();

Authenticate EventGridManagementClient with access token using secret or certificate credentials

// Authenticate EventGridManagementClient with Microsoft Entra ID access token credential
eventGridClient = new EventGridManagementClient(new Uri("https://management.azure.com/"),
    new TokenCredentials(token.AccessToken));

eventGridClient.SubscriptionId = 'your_subscripiton_id';

Create Event Subscription

This code sample shows how to create the event subscription for the webhook subscriber endpoint.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
string[] includedEventTypes = new string[]{ "Microsoft.Communication.SMSReceived", 
                                            "Microsoft.Communication.SMSDeliveryReportReceived"
                                            };

EventSubscription eventSubscription = new EventSubscription(
    name: "<eventSubscriptionName>",
    eventDeliverySchema: "EventGridSchema",
    filter: new EventSubscriptionFilter(
    includedEventTypes: includedEventTypes),
    destination: new WebHookEventSubscriptionDestination(webhookUri));

await eventGridClient.EventSubscriptions.CreateOrUpdateAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>",
    eventSubscriptionInfo: eventSubscription);

Update event subscription

This code sample shows how to update the event subscription to add more events, you want to receive on the webhook subscriber endpoint.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
string[] additionalEventTypes = new string[]{ 
                                            "Microsoft.Communication.ChatMessageReceived"
                                        };

await eventGridClient.EventSubscriptions.UpdateAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>",
    eventSubscriptionUpdateParameters: new EventSubscriptionUpdateParameters(
            filter: new EventSubscriptionFilter(includedEventTypes: additionalEventTypes)));

Delete event Subscription

This code sample shows how to delete the event subscription for the webhook subscriber endpoint.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";

await eventGridClient.EventSubscriptions.DeleteAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>");

Prerequisites

An Azure account with an active subscription. Create an account for free.
Install the Azure Az PowerShell Module
An Azure Communication Services resource
Create a Webhook to receive events. Webhook Event Delivery

Register the Event Grid resource provider

This article describes how to register the Event Grid Resource Provider. If you used Event Grid before in the same subscription, skip to the next section.

Run the following command:

Register-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

It may take a moment for the registration to finish. To check the status, run:

Get-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

When RegistrationStatus is Registered, you're ready to continue.

Create event subscription

First, make sure to install the Azure Communication Services module Az.EventGrid using the following command.

PS C:\> Install-Module Az.EventGrid

Sign in to your Azure subscription with the Connect-AzAccount command and follow the on-screen directions:
```
Connect-AzAccount
```
If your identity is associated with more than one subscription, then set your active subscription to subscription of the Web PubSub resource that you want to move.
```
$context = Get-AzSubscription -SubscriptionId <subscription-id>
Set-AzContext $context
```

To create an event subscription by using the Azure PowerShell, use the New-AzEventGridSubscription command.

$includedEventTypes = "Microsoft.Communication.SMSReceived", "Microsoft.Communication.SMSDeliveryReportReceived"
New-AzEventGridSubscription 
    -EndpointType webhook
    -Endpoint https://azureeventgridviewer.azurewebsites.net/api/updates
    -EventSubscriptionName EventsWebhookSubscription 
    -IncludedEventType $includedEventTypes
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>"

For a list of Communication Services events, see Communication Services Events.

List event subscriptions

To list all the existing event subscriptions set up for an Azure Communication Services resource, by using the Azure PowerShell, use the Get-AzEventGridSubscription command.

Get-AzEventGridSubscription 
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>"

Update event subscription

To update an existing event subscription by using the Azure PowerShell, use the Update-AzEventGridSubscription command.

$includedEventTypes = "Microsoft.Communication.SMSReceived", "Microsoft.Communication.SMSDeliveryReportReceived", "Microsoft.Communication.ChatMessageReceived"
Update-AzEventGridSubscription 
    -EventSubscriptionName ES2 
    -IncludedEventType $includedEventTypes
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>" 
    -Endpoint https://azureeventgridviewer2.azurewebsites.net/api/updates
    -SubjectEndsWith "phoneNumber"

Delete event subscription

To delete an existing event subscription by using the Azure PowerShell, use the Remove-AzEventGridSubscription command.

Get-AzResource 
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>" | Remove-AzEventGridSubscription -EventSubscriptionName ES2

Next steps

For information on other commands, see Az.EventGrid PowerShell Module.

Share via

Prerequisites

Register the Event Grid resource provider

Create event subscription

Update event subscription

Delete event subscription

Next steps

Prerequisites

Register the Event Grid resource provider

Create event subscription

List event subscriptions

Update event subscription

Delete event subscription

Next steps

Prerequisites

Register the Event Grid resource provider

Installing the SDK

Authenticating with Azure Identity library

Prerequisites:

Create Event Subscription

Update event subscription

Delete event Subscription

Prerequisites

Register the Event Grid resource provider

Create event subscription

List event subscriptions

Update event subscription

Delete event subscription

Next steps

Feedback

Additional resources

Share via

Quickstart: Subscribe to Azure Communication Services events

Prerequisites

Register the Event Grid resource provider

Create event subscription

Update event subscription

Delete event subscription

Next steps

Prerequisites

Register the Event Grid resource provider

Create event subscription

List event subscriptions

Update event subscription

Delete event subscription

Next steps

Prerequisites

Register the Event Grid resource provider

Installing the SDK

Authenticating with Azure Identity library

Prerequisites:

Create Event Subscription

Update event subscription

Delete event Subscription

Prerequisites

Register the Event Grid resource provider

Create event subscription

List event subscriptions

Update event subscription

Delete event subscription

Next steps

Feedback

Additional resources