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).
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/|
Find out about the latest new features and updates for this API set.
The service communications API can open up new ways for you to engage with users:
- Overview for accessing service health and communications in Microsoft Graph
- Try the API in the Graph Explorer.
Need more ideas? See how some of our partners are using Microsoft Graph.