Working with service communications API in Microsoft Graph

The service communications API provides service health and message center posts pertaining to the Microsoft cloud services subscribed by your tenant. You can get current and historical health data of a Microsoft service (for example, the Exchange Online service is down). You can check the service health to determine if an issue is tracked and a resolution is in progress before calling support or spending time troubleshooting. Message center posts let you keep track of upcoming changes, including new features, updates, and other important announcements (for example, Exchange Online is getting a new feature).

Authorization

Microsoft Graph lets applications get authorized access to health and change communications about a Microsoft cloud service subscribed by a tenant. With the appropriate delegated or application permissions, your app can access the communications data on behalf of a signed-in user, or without any signed-in user in the tenant. Both delegated and application types of these permissions are granted by only an administrator.

For more information on access tokens, app registration, and delegated and application permissions, see Authentication and authorization basics.

Access service communications API on behalf of signed-in user

Delegated permissions are needed to access the service communications API on behalf of a signed-in user. Customer-facing canvas applications, such as the Microsoft 365 admin center (accessible only to admin roles), can call the service communications API to get the service health and service announcements data for the signed-in user's tenant, on behalf of the signed-in user. Users can find out whether their subscribed servies are healthy or have issues. They can also learn about any current service issues affecting their tenants.

Access service communications API without user

Application permissions are needed to access the service communications API without a signed-in user. Applications that run as backend services, such as monitoring or alert services, can call the service communications API with their own identity and not on behalf of a user. These backend services can build custom monitoring/alert pipelines and call the service communications API to get service health and service announcements data.

Common use cases and required permissions

Use cases API requests Required permissions Supported permission types
List health overviews for tenant List healthOverviews ServiceHealth.Read.All Delegated and application
Get specific service health information for tenant Get serviceHealth ServiceHealth.Read.All Delegated and application
List all service issues for tenant List issues ServiceHealth.Read.All Delegated and application
Get a specific service issue for tenant Get issue ServiceHealth.Read.All Delegated and application
Get a post-incident review report for tenant Get incident report ServiceHealth.Read.All Delegated and application
List all service messages for tenant List messages ServiceMessage.Read.All Delegated and application
Get a specific service message for tenant Get message ServiceMessage.Read.All Delegated and application
Update service message status for signed in user For a list of status operations, see serviceUpdateMessage. ServiceMessageViewpoint.Write Delegated

API on Microsoft Graph national clouds

Service communications API is available on Microsoft Graph national clouds as well. You could get service health and communications data for your national clouds tenants. More information about Microsoft Graph national clouds.

National clouds API url (partial)
Microsoft Graph global service https://graph.microsoft.com/v1.0/admin/serviceAnnouncement/|
Microsoft Graph for US Government L4 (GccHigh) https://graph.microsoft.us/v1.0/admin/serviceAnnouncement/
Microsoft Graph for US Government L5 (DoD) https://dod-graph.microsoft.us/v1.0/admin/serviceAnnouncement/
Microsoft Graph Germany https://graph.microsoft.de/v1.0/admin/serviceAnnouncement/
Microsoft Graph China operated by 21Vianet https://microsoftgraph.chinacloudapi.cn/v1.0/admin/serviceAnnouncement/

What's new

Find out about the latest new features and updates for this API set.

Next steps

The service communications API can open up new ways for you to engage with users:

Need more ideas? See how some of our partners are using Microsoft Graph.