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 services are healthy or have issues. They can also learn about any current service issues affecting their tenants.
Role-based access control for delegation access
The service communications API applies role-based access control (RBAC) to identify whether the signed-in user who is on-behalf of has a required Microsoft Entra role. The signed-in user who is on-behalf of must have at least one of the admin roles.
For more information about the Microsoft Entra administrator roles, see:
- About admin roles in the Microsoft 365 admin center
- Microsoft Entra built-in roles
- Roles in Microsoft 365, including Microsoft Entra ID, service-specific and cross-service roles
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 |
Availability in national clouds
That service communications API is available in all Microsoft national cloud deployments. You can get service health and communications data for any tenants in Microsoft national clouds. For details, see national cloud deployments.
| National clouds | API URL (partial) |
|---|---|
| Microsoft Graph global service | https://graph.microsoft.com/beta/admin/serviceAnnouncement/| |
| Microsoft Graph for US Government L4 (GccHigh) | https://graph.microsoft.us/beta/admin/serviceAnnouncement/ |
| Microsoft Graph for US Government L5 (DoD) | https://dod-graph.microsoft.us/beta/admin/serviceAnnouncement/ |
| Microsoft Graph China operated by 21Vianet | https://microsoftgraph.chinacloudapi.cn/beta/admin/serviceAnnouncement/ |
Service communications limits
To guarantee the service performance, the service communications API has throttling limits for the requests per tenant per application. For details about the limits, see throttling limits for the service communications service.
Next steps
The service communications API can open up new ways for you to engage with users: