Quickstart: Handle SMS events for Delivery Reports and Inbound Messages


Phone number availability is currently restricted to Azure subscriptions that have a billing address in the United States (including Puerto Rico), United Kingdom or Ireland. For more information, visit the Phone number types documentation.

Get started with Azure Communication Services by using Azure Event Grid to handle Communication Services SMS events.

About Azure Event Grid

Azure Event Grid is a cloud-based eventing service. In this article, you'll learn how to subscribe to events for communication service events, and trigger an event to view the result. Typically, you send events to an endpoint that processes the event data and takes actions. In this article, we'll send the events to a web app that collects and displays the messages.


Setting up

Enable Event Grid resource provider

If you haven't previously used Event Grid in your Azure subscription, you may need to register the Event Grid resource provider following the steps below:

In the Azure portal:

  1. Select Subscriptions on the left menu.
  2. Select the subscription you're using for Event Grid.
  3. On the left menu, under Settings, select Resource providers.
  4. Find Microsoft.EventGrid.
  5. If not registered, select Register.

It may take a moment for the registration to finish. Select Refresh to update the status. When Status is Registered, you're ready to continue.

Event Grid Viewer deployment

For this quickstart, we will use the Azure Event Grid Viewer Sample to view events in near-real time. This will provide the user with the experience of a real-time feed. In addition, the payload of each event should be available for inspection as well.

Subscribe to the SMS events using web hooks

In the portal, navigate to your Azure Communication Services Resource that you created. Inside the Communication Service resource, select Events from the left menu of the Communication Services page.

Screenshot showing selecting the event subscription button within a resource's events page.

Press Add Event Subscription to enter the creation wizard.

On the Create Event Subscription page, Enter a name for the event subscription.

You can subscribe to specific events to tell Event Grid which of the SMS events you want to track, and where to send the events. Select the events you'd like to subscribe to from the dropdown menu. For SMS you'll have the option to choose SMS Received and SMS Delivery Report Received.

If you're prompted to provide a System Topic Name, feel free to provide a unique string. This field has no impact on your experience and is used for internal telemetry purposes.

Check out the full list of events supported by Azure Communication Services.

Screenshot showing the SMS Received and SMS Delivery Report Received event types being selected.

Select Web Hook for Endpoint type.

Screenshot showing the Endpoint Type field being set to Web Hook.

For Endpoint, click Select an endpoint, and enter the URL of your web app.

In this case, we will use the URL from the Azure Event Grid Viewer Sample we set up earlier in the quickstart. The URL for the sample will be in the format: https://{{site-name}}.azurewebsites.net/api/updates

Then select Confirm Selection.

Screenshot showing confirming a Web Hook Endpoint.

Viewing SMS events

Triggering SMS events

To view event triggers, we must generate events in the first place.

  • SMS Received events are generated when the Communication Services phone number receives a text message. To trigger an event, just send a message from your phone to the phone number attached to your Communication Services resource.
  • SMS Delivery Report Received events are generated when you send an SMS to a user using a Communication Services phone number. To trigger an event, you are required to enable Delivery Report in the options of the sent SMS. Try sending a message to your phone with Delivery Report. Completing this action incurs a small cost of a few USD cents or less in your Azure account.

Check out the full list of events supported by Azure Communication Services.

Receiving SMS events

Once you complete either action above you will notice that SMS Received and SMS Delivery Report Received events are sent to your endpoint. These events will show up in the Azure Event Grid Viewer Sample we set up at the beginning. You can press the eye icon next to the event to see the entire payload. Events will look like this:

Screenshot showing the Event Grid Schema for an SMS Received Event.

Screenshot showing the Event Grid Schema for an SMS Delivery Report Event.

Learn more about the event schemas and other eventing concepts.

Clean up resources

If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about cleaning up resources.

Next steps

In this quickstart, you learned how to consume SMS events. You can receive SMS messages by creating an Event Grid subscription.

You may also want to: