Quickstart: Handle SMS and delivery report events
Get started with Azure Communication Services by using Azure Event Grid to handle Communication Services SMS events. After subscribing to SMS events such as inbound messages and delivery reports, you generate and receive these events. Completing this quickstart incurs a small cost of a few USD cents or less in your Azure account.
SMS capabilities depend on the phone number you use and the country that you're operating within as determined by your Azure billing address. For more information, visit the Subscription eligibility documentation.
- An Azure account with an active subscription. Create an account for free.
- A Communication Services resource. For detailed information, see Create an Azure Communication Services resource.
- An SMS-enabled telephone number. Get a phone number.
About Event Grid
Event Grid is a cloud-based eventing service. In this article, you'll learn how to subscribe to 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.
Set up the environment
To set up the environment that we'll use to generate and receive events, take the steps in the following sections.
Register an Event Grid resource provider
If you haven't previously used Event Grid in your Azure subscription, you might need to register your Event Grid resource provider. To register the provider, follow these steps:
- Go to the Azure portal.
- On the left menu, select Subscriptions.
- Select the subscription that you use for Event Grid.
- On the left menu, under Settings, select Resource providers.
- Find Microsoft.EventGrid.
- If your resource provider isn't registered, select Register.
It might take a moment for the registration to finish. Select Refresh to update the status. When Registered appears under Status, you're ready to continue.
Deploy the Event Grid viewer
For this quickstart, we'll use an Event Grid viewer to view events in near-real time. The viewer provides the user with the experience of a real-time feed. Also, the payload of each event should be available for inspection.
To set up the viewer, follow the steps in Azure Event Grid Viewer.
Subscribe to SMS events by using web hooks
You can subscribe to specific events to provide Event Grid with information about where to send the events that you want to track.
In the portal, go to the Communication Services resource that you created.
Inside the Communication Services resource, on the left menu of the Communication Services page, select Events.
Select Add Event Subscription.
On the Create Event Subscription page, enter a name for the event subscription.
Under Event Types, select the events that you'd like to subscribe to. For SMS, you can choose
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.
For Endpoint type, select Web Hook.
For Endpoint, select Select an endpoint, and then enter the URL of your web app.
In this case, we'll use the URL from the Event Grid viewer that we set up earlier in the quickstart. The URL for the sample has this format:
Select Confirm Selection.
View SMS events
To generate and receive SMS events, take the steps in the following sections.
Trigger SMS events
To view event triggers, we need to generate some events.
SMS Receivedevents are generated when the Communication Services phone number receives a text message. To trigger an event, send a message from your phone to the phone number that's attached to your Communication Services resource.
SMS Delivery Report Receivedevents are generated when you send an SMS to a user by using a Communication Services phone number. To trigger an event, you need to turn on the
Delivery Reportoption of the SMS that you send. Try sending a message to your phone with
Delivery Reportturned on. 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 that Communication Services supports.
Receive SMS events
After you generate an event, you'll notice that
SMS Received and
SMS Delivery Report Received events are sent to your endpoint. These events show up in the Event Grid viewer that we set up at the beginning of this quickstart. Select the eye icon next to the event to see the entire payload. Events should look similar to the following data:
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.
In this quickstart, you learned how to consume SMS events. You can receive SMS messages by creating an Event Grid subscription.
You might also want to: