Microsoft Teams Emergency Notifications - Installation Guide

Feature Overview

The Microsoft Teams emergency notifications integration provides real-time monitoring of emergency call notifications within Microsoft Teams. When users make emergency calls (configured via Teams emergency calling policies), this integration captures and processes the automated chat notifications that Teams generates, enabling Call Telemetry to track and respond to emergency situations.

This integration uses Microsoft Graph API subscriptions delivered through Azure Event Hub to monitor Teams chat messages for emergency call notifications, providing a comprehensive emergency response capability that complements Call Telemetry's existing emergency management features.

Feature Requirements

Integration User Requirements

The Microsoft Teams integration requires a dedicated service user to serve as the authentication principal for accessing Teams chat data. This user monitors Teams chat messages to detect emergency call notifications that are automatically sent when users make emergency calls (configured via Teams emergency calling policies).

Requirement	Description	Configuration
Dedicated Service Account	Create a dedicated user account for the integration	`[email protected]`
Teams License	User must have Microsoft Teams (any tier) license	Assign through Microsoft 365 admin center
Account Permissions	Standard user permissions (no elevated privileges required)	Regular Microsoft 365 user account
Authentication Method	Account must support OAuth 2.0 authentication	Enable modern authentication

Security Benefits of Dedicated Integration User:

Isolated Access: Integration runs under dedicated account, not personal user accounts, with delegated permissions.
Audit Trail: All Teams API access attributed to specific integration user
Access Control: Easy to manage and revoke integration access independently
Compliance: Clear separation between personal and system access
Delegated Permissions: Chat.Read permission grants access to Teams chats the user can access

Teams Admin Policy Requirements

MS Teams Required Configurations

Requirement	Configuration	Teams Admin Center Location
Emergency Calling Policy	Enable emergency call notifications to chat	Voice → Emergency policies → Emergency calling policies
Emergency Call Routing Policy	Configure emergency call routing	Voice → Emergency policies → Emergency call routing policies
Notification Policy	Allow chat notifications for emergency calls	Messaging policies → Chat and channels
Integration User Teams Access	Integration user must have access to emergency notification chats	User management → Assign Teams license and policies

MS Teams Setup Steps:

Emergency Calling Policy: Create/modify policy to enable "Notification mode" = "Notification only" or "Notification and conferencing"
Emergency Call Routing: Ensure emergency calls generate chat notifications
Integration User: Add integration user to emergency notification distribution groups
Chat Policies: Verify integration user can participate in emergency notification chats

Azure Tenant Requirements

These are general permission requirements for setting up the Microsoft Teams integration with Call Telemetry. They do not apply to the operational requirements of the integration once it is set up.

Requirement	Description	Validation Method
Azure Subscription	Active Azure subscription with Event Hub creation permissions	Portal: Subscriptions blade
Global Admin Access	Ability to create App Registrations and grant API permissions	Azure AD → Roles and administrators
Event Hub Namespace	Dedicated Event Hub namespace for Teams events	Event Hubs → Create namespace
Teams License	Microsoft Teams licensing for target users	Microsoft 365 admin center

Network and Firewall Requirements

Outbound Connectivity Requirements

Call Telemetry requires outbound connectivity to Microsoft services for Graph API access and Event Hub processing:

Firewall Rules

Configure your firewall to allow outbound connections:

Destination	Port	Protocol	Purpose
`graph.microsoft.com`	443	HTTPS	Microsoft Graph API direct access
`login.microsoftonline.com`	443	HTTPS	Azure AD device authentication
`*.servicebus.windows.net`	9093	Kafka/SSL	Event Hub Kafka protocol

DNS Requirements

Ensure your DNS can resolve these domains:

*.microsoft.com
*.microsoftonline.com
*.servicebus.windows.net

Microsoft 365 Licensing Requirements

Feature	Required License	Scope
Emergency Call Notification Monitoring	Microsoft Teams (any tier)	For integration user account
Integration User	Dedicated service account with Teams license	One per organization

Azure Setup Process

Step 1: Create App Registration

Navigate to Azure Active Directory:
- Sign in to Azure Portal
- Go to Azure Active Directory → App registrations
- Click + New registration
Configure App Registration:
- Name: Call Telemetry Teams Integration
- Supported account types: Accounts in this organizational directory only (Single tenant)
- Redirect URI: Leave blank (OAuth 2.0 Device Authorization Grant flow only)
- Click Register
Note Application Details:
- Copy Application (client) ID - you'll need this for Call Telemetry
- Copy Directory (tenant) ID from the Overview page
Create Client Secret:
- Go to Certificates & secrets → Client secrets
- Click + New client secret
- Description: Call Telemetry Integration Secret
- Expires: 24 months (recommended)
- Click Add and copy the secret value immediately
Enable Public Client Flow (For Device Authentication mode):
- Go to Authentication → Advanced settings
- Under Allow public client flows, set Enable the following mobile and desktop flows to Yes
- Without this setting, the OAuth 2.0 Device Authorization Grant flow will fail
- Click Save

Step 2: Configure API Permissions

Add Microsoft Graph Permissions:
- Go to API permissions → + Add a permission
- Select Microsoft Graph → Delegated permissions
- Add the following permissions:

Required Microsoft Graph API Permissions

Permission	Type	Description	Justification
`User.Read`	Delegated	Read user profile	Basic user information for authentication
`Chat.Read`	Delegated	Read user chat messages	Access chat messages for emergency monitoring
`Chat.ReadBasic`	Delegated	Read basic chat information	Read names and members of user chat threads
`ChatMessage.Read`	Delegated	Read chat messages	Read individual chat messages and content
`openid`	Delegated	OpenID Connect authentication	Standard authentication flow
`offline_access`	Delegated	Access resources when user not present	Token refresh capability for continuous monitoring
`profile`	Delegated	View user's basic profile	User identification and profile information

No Admin Consent Required:
- All listed permissions are delegated and do not require admin consent
- Service integration users will consent during device authentication flow
- Verify the permissions show Not granted for [tenant] status (normal for delegated permissions)

Step 3: Create Event Hub Infrastructure

Create Resource Group:
- Go to Resource groups → + Create
- Subscription: Select your subscription
- Resource group: RG-Call-Telemetry-Teams
- Region: Choose region closest to your users
- Click Review + create
Create Event Hub Namespace:
- Go to Event Hubs → + Create
- Subscription: Your subscription
- Resource group: RG-Call-Telemetry-Teams
- Namespace name: calltelemetry-teams-events (must be globally unique)
- Location: Same as resource group
- Pricing tier: Basic (sufficient for most deployments)
- Click Review + create
Create Event Hub:
- Navigate to your Event Hub namespace
- Click + Event Hub
- Name: teams-events
- Partition count: 2 (recommended for Teams workloads)
- Message retention: 1 day (Basic tier limit)
- Click Create
Consumer Group Configuration:
- Event Hub includes a default consumer group named $Default
- For most deployments: Use the $Default consumer group
- For production environments with multiple consumers: Create a dedicated consumer group:
  - Navigate to your Event Hub: Event Hubs → teams-events
  - Go to Entities → Consumer groups
  - Click + Consumer group
  - Name: calltelemetry-consumers
  - Description: Call Telemetry Teams Integration Consumer Group
  - Click Create

Step 4: Configure Access Policies and Microsoft Graph Permissions

Microsoft Graph requires special permissions to send subscription events to your Event Hub

Create Custom Access Policy:
- In your Event Hub namespace, go to Settings → Shared access policies
- Click + Add
- Policy name: CallTelemetry-ReadWrite
- Permissions: Check Listen and Send (uncheck Manage)
- Click Create
Create Event Hub-Level Policy (Required for Direct Operations):
- Navigate to your Event Hub: Event Hubs → teams-events
- Go to Settings → Shared access policies
- Click + Add
- Policy name: CallTelemetry-Event-Hub-ReadWrite
- Permissions: Check Listen and Send (uncheck Manage)
- Click Create
Grant Microsoft Graph Change Tracking Service Principal Permissions

Microsoft Graph Change Tracking service needs explicit permissions to send subscription events to your Event Hub. Without this, subscription creation will fail with "UnauthorizedAccessException: Send claim(s) required" errors.

TIP

You must use the "Microsoft Graph Change Tracking" service principal, NOT the generic "Microsoft Graph" service principal.

Applying via Azure CLI:

bash

# Get your subscription and resource details
SUBSCRIPTION_ID=$(az account show --query id -o tsv)
RESOURCE_GROUP="[YOUR_RESOURCE_GROUP]"
NAMESPACE_NAME="[YOUR_EVENT_HUB_NAMESPACE]"

# Find the Microsoft Graph Change Tracking service principal
MS_GRAPH_CT_OBJECT_ID=$(az ad sp list --display-name "Microsoft Graph Change Tracking" --query "[0].id" -o tsv)

# Grant the CRITICAL permission (this fixes the "Send claim required" error)
az role assignment create \
  --assignee-object-id "$MS_GRAPH_CT_OBJECT_ID" \
  --assignee-principal-type "ServicePrincipal" \
  --role "Azure Event Hubs Data Sender" \
  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.EventHub/namespaces/$NAMESPACE_NAME"

Apply via Azure Portal:

Go to your Event Hub namespace → Access control (IAM)
Click + Add → Add role assignment
Select Azure Event Hubs Data Sender role
In Assign access to: Select User, group, or service principal
Search for "Microsoft Graph Change Tracking"
Select the service principal and click Review + assign

Validation: Run the validation script to verify permissions:

bash

./docs/features/ms_teams_events/validate-azure-eventhub-setup.sh

Copy Connection String:
- Go back to Event Hubs → teams-events → Shared access policies
- Click on your CallTelemetry-Event-Hub-ReadWrite policy
- Copy Connection string–primary key
- IMPORTANT: This connection string includes EntityPath which is required for direct Event Hub operations

Call Telemetry Configuration

Microsoft Teams Integration Setup

Configure the Teams integration through the Call Telemetry web interface:

Navigate to Teams Integration:
- Log in to Call Telemetry
- Go to sidebar → MS Teams

OAuth Settings Tab: Fill in the following OAuth configuration:

Setting	Value	Source
Client ID	`[App Registration ID]`	Azure Portal → App registrations
Client Secret	`[Client Secret Value]`	Azure Portal → Certificates & secrets
Tenant ID	`[Directory Tenant ID]`	Azure Portal → App registrations → Overview
Refresh Token Expiration Minutes	`2196`	Default token expiration (leave as default)

Subscription Settings Tab: Configure Microsoft Graph subscription settings:
Setting Value Description
Delivery Mode Event Hub Select Event Hub delivery
Subscription Timeout Minutes 4320 Timeout in minutes (3 days)

Setting	Value	Description
Delivery Mode	`Event Hub`	Select Event Hub delivery
Subscription Timeout Minutes	`4320`	Timeout in minutes (3 days)

Event Hub Tab: Configure Event Hub integration:

Setting	Value	Source
Enable Event Hub Integration	✅ `True`	Enable the Event Hub feature
Event Hub Name	`teams-events`	Your Event Hub name
Consumer Group	`$Default`	Use default consumer group (recommended for most deployments)
Connection String	`[Connection String]`	Azure Portal → Event Hub → Shared access policies
Partition Count	`2`	Number of Event Hub partitions

Event Hub Configuration Notes:

Consumer Groups:

$Default is recommended for most Call Telemetry deployments
Multiple consumer groups allow different applications to process the same event stream independently
Each consumer group maintains its own offset/checkpoint position in the event stream
Create dedicated consumer groups only when multiple applications need to process the same Event Hub

Partition Configuration:

2 partitions is recommended for most Teams deployments
Partitions enable parallel processing and scale the throughput
Call Telemetry's Broadway pipeline automatically distributes processing across partitions
Cannot be changed after Event Hub creation

Permissions Tab: Check all required Microsoft Graph permissions:
- ☑️ User.Read - Read user profile
- ☑️ Chat.Read - Read user chat messages
- ☑️ Chat.ReadBasic - Read basic chat information
- ☑️ ChatMessage.Read - Read chat messages
- ☑️ openid - OpenID Connect authentication
- ☑️ offline_access - Access resources when user not present
- ☑️ profile - View user's basic profile
Save Configuration:
- Review all settings across tabs
- Click Save to apply configuration
- Test the integration to verify setup

Authenticate the Service User

The Teams integration uses OAuth 2.0 Device Authorization Grant flow (also called Device Code Flow) for secure authentication. This method is specifically designed for applications running on devices without a web browser or with limited input capabilities.

How Device Authentication Works

The Device Authorization Grant flow provides a secure way for the integration service user to authenticate without requiring a web browser on the server:

Device Code Request: Call Telemetry requests a device code and user code from Microsoft's authentication servers
User Authentication: The service integration user uses a separate device (phone, laptop) with a web browser to authenticate
Token Exchange: Once authenticated, Call Telemetry receives access and refresh tokens for Microsoft Graph API access
Automatic Token Refresh: Both access tokens and refresh tokens are automatically renewed indefinitely to maintain ongoing access to Teams chat data without manual intervention. You can verify token health on the teams user integration page. There are diagnostic tools to check token health and re-authenticate if needed.

Step-by-Step Authentication Process

Initiate Authentication:
- Go to MS Teams → Teams Integration
- Click Add Monitoring User
- Click Start Authentication
- Call Telemetry requests device and user codes from Microsoft Entra ID
Device Code Display:
- Call Telemetry displays a User Code (e.g., BFCC-GQVT)
- A Verification URL is provided (typically https://microsoft.com/devicelogin)
- Important: You have 15 minutes to complete the authentication
User Authentication (on separate device):
- On your phone, laptop, or another device with a web browser:
- Navigate to the Verification URL (https://microsoft.com/devicelogin)
- Enter the User Code displayed by Call Telemetry
- Sign in using the service integration user credentials
- Grant Permissions: Review and accept the requested permissions
Permission Consent:
- Microsoft will display the permissions requested by Call Telemetry (discussed earlier)
- Click Accept to grant these permissions.
- You do not need to use admin permissions or consent for the entire organization.
Authentication Complete:
- Return to Call Telemetry interface
- Authentication should complete automatically
- Call Telemetry will display "Authentication successful"
- User profile information will be populated

Security Features of Device Flow

Multi-Factor Authentication: Supports MFA and conditional access policies
No Shared Secrets: No passwords or certificates stored on the server
User-Controlled: Service integration user explicitly consents to permissions
Revocable: Admin can revoke access through Azure AD at any time
Auditable: All authentication events logged in Azure AD

Installation Validation

Common Installation Issues

App Registration Issues

Public client flow disabled: Enable in Authentication → Advanced settings
Missing API permissions: Verify all required Graph permissions are added
Client secret expired: Check expiration date and regenerate if needed

Event Hub Issues

Namespace not found: Verify resource group and namespace names
Connection string invalid: Ensure connection string includes EntityPath
Permission denied: Verify Microsoft Graph Change Tracking service principal has correct permissions

Network Issues

Firewall blocking: Verify outbound connections to required domains
DNS resolution: Test domain resolution for Microsoft services
Certificate errors: Ensure TLS 1.2+ support and valid certificates

Post-Installation Steps

Monitor Integration Health:
- Check token expiration status
- Monitor subscription renewal
- Verify event processing
Test Emergency Call Flow:
- Make a test emergency call using Microsost Teams 933 to simulate an emergency call
- Verify chat notifications are generated
- Confirm events are received and processed
Documentation and Training:
- Document your specific configuration
- Train administrators on troubleshooting procedures
- Establish operational procedures for token renewal

The installation is now complete and ready for operational use.

Architecture Overview - Technical architecture and system design
Teams Azure Integration - Azure integration configuration details

Microsoft Teams Emergency Notifications - Installation Guide ​

Feature Overview ​

Feature Requirements ​

Integration User Requirements ​

Teams Admin Policy Requirements ​

Azure Tenant Requirements ​

Network and Firewall Requirements ​

Outbound Connectivity Requirements ​

Firewall Rules ​

DNS Requirements ​

Microsoft 365 Licensing Requirements ​

Azure Setup Process ​

Step 1: Create App Registration ​

Step 2: Configure API Permissions ​

Step 3: Create Event Hub Infrastructure ​

Step 4: Configure Access Policies and Microsoft Graph Permissions ​

Call Telemetry Configuration ​

Microsoft Teams Integration Setup ​

Authenticate the Service User ​

How Device Authentication Works ​

Step-by-Step Authentication Process ​

Security Features of Device Flow ​

Installation Validation ​

Common Installation Issues ​

App Registration Issues ​

Event Hub Issues ​

Network Issues ​

Post-Installation Steps ​

Related Documentation ​