Skip to main content

Phone Call Callbacks

The PhoneCallbackFunction handles phone call lifecycle events from Azure Communication Services. When a notification is delivered via phone call, the callback endpoints manage the call flow from connection through to hangup.

How It Works​

  1. SendNotificationMessage initiates a phone call via IPhoneCallService.CallTargetAsync, providing the callback URL for the appropriate alert type
  2. Azure Communication Services establishes the call and sends a CallConnected event to the callback endpoint
  3. The callback function plays a text-to-speech message 3 times using the call media API
  4. On PlayCompleted or PlayFailed, the function hangs up the call

Callback Endpoints​

Each alert type has a dedicated callback endpoint. The alert type is mapped to the callback URI by NotificationExtensions.MapAlertMessageTypeToCallbackUri().

Alert TypeEndpointMessage
AnomalyPOST /api/AnomalyCallback"Anomaly has been reported."
Point of InterestPOST /api/PointOfInterestCallback"Point of interest has been reported."
Report of FirePOST /api/ReportOfFireCallback"Report of a fire has been reported."
Confirmed FirePOST /api/ConfirmedFireCallback"Confirmed fire has been reported."
Burn JobPOST /api/BurnJobCallback"Burn job has been reported."
CustomPOST /api/CustomCallback"Custom Alert has been reported."

All messages are prefixed with: "You've received a new Alert from Alert California."

Message Format​

The notification message is built by BuildNotificationMessage and repeated 3 times to ensure the recipient hears the full message:

"You've received a new Alert from Alert California. [Alert Type] has been reported. "
× 3 repetitions

The message is delivered as text-to-speech using a female en-US voice via Azure Communication Services Call Media.

Security​

These callback endpoints use AuthorizationLevel.Anonymous because the calls originate from Azure Communication Services, not from user-facing clients. The endpoints accept CloudEvent[] payloads as defined by the Azure Communication Services callback contract.

Local Development​

To test phone callbacks locally, an Azure dev tunnel is required to expose your local development environment to Azure Communication Services.

Setting Up Dev Tunnel​

  1. Install Azure Dev Tunnels following the official documentation: https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started?tabs=windows

  2. Configure the dev tunnel with the following commands:

devtunnel user login
devtunnel create --allow-anonymous
devtunnel port create -p 7149 --protocol https
devtunnel host -p 7149 --protocol https --allow-anonymous

This creates an HTTPS tunnel on port 7149 that Azure Communication Services can reach to deliver callback events.

Testing Phone Calls​

A test-call endpoint is available in DEBUG builds for testing phone call flows:

POST /api/test-call
Body: ["<phone-number>", ...]

Use the dev tunnel URL in place of the callback URI when testing locally.