Microsoft Graph Service Health And Communications API is now GA, legacy Service Communications API being retired December 2021

Check your code, Flows and PowerShell for manage.office.com ServiceComms references…

Disclaimer: I’m piecing some of the information in this article together from multiple places, such as Microsoft Docs but also dates on GitHub history etc. If there’s an official Tech Community blog post about this that I’ve missed (or that subsequently gets posted) I’ll come back and update this information. Let me know if you spot anything that needs changing.

Naming is hard. Especially when things get replaced and the best name is being used by the thing that’s being replaced. This news is kinda hard to follow, because the names of everything are very similar, but also not used consistently in the documentation. Hopefully, I can help bring some clarity.

What is this about?

This is about the API call used to get service health status and update messages in Office 365. This is widely used in PowerShell examples on the web: a quick search for “office 365 service status powershell” returns many people with solutions that use this API call.

If you’re using a URL that starts like this: https://manage.office.com/api/v1.0/{tenant_identifier}/ServiceComms then this blog post is for you!

What’s new?

There’s an API in Microsoft Graph which has just (in the last 2 months anyway) graduated from Beta to GA. This is the “Service Health and Communications API” – often referred to in the documentation as the “service communications API”. This API provides service health and message centre information specific to your tenant. It covers both service issues (letting you list/get issues as well as post-incident reports) and service messages (similar to Message Center messages) with a broad set of operations to list and get messages as well as marking them as read and archiving them.

All the operations require specific permission: either ServiceHealth.Read.All, ServiceMessage.Read.All or ServiceMessageViewpoint.Write. Both delegated and application permissions models are supported for many of the read-only operations, but to update or mark a message as read you can only use delegated permissions.

There are also specific endpoints if you use one of the Microsoft Graph national clouds: GccHigh, DoD, Graph Germany, or Graph China (via 21Vianet):

What’s being retired?

There is an Office 365 Management API called the “Office 365 Service Communications API“. If you have code that calls “https://manage.office.com/api/v1.0…” then you are using this API. Now that the Graph-based “Service Health and Communications API” is GA, this legacy API is being retired “beginning December 17, 2021”:

Although I haven’t tested every API call and validated the results side by side, looking through the two APIs it looks like the new API covers all the functionality of the old API. Be aware though the shape of the result data will be different and you may need to construct requests differently. Check the documentation of the new API for more details.

The legacy API covers issues and messages pertaining to Office 365, Yammer, Dynamics CRM and Microsoft Intune. I’m not 100% sure on this, but I would expect the new API to cover all these, plus anything else that’s in Message Center.

I’m using the old API, what should I do?

The old API will continue working until at least December 17th 2021. However, you should start work on moving over to the new API now so that you’re completely off by then. It’s unclear whether everything will stop working on the 18th day of December or whether retiring the API will be a phased approach.

I don’t think the (old) Service Communications API was ever promoted from preview mode to GA, although there was/is a previous version of the Service Communications API which was GA. Either way, I wouldn’t stick around on this API past 17th December to find out!

Written by Tom Morgan

Tom is a Microsoft Teams Platform developer and Microsoft MVP who has been blogging for over a decade. Find out more.

---

Buy the book: Building and Developing Apps & Bots for Microsoft Teams. Now available to purchase online with free updates.

Related posts:

Are you still using Microsoft Bot Framework State Service? You need to read this and act today! New Guidance on Microsoft Teams Throttling Service Limits The Calls & Meetings API is now the Microsoft Graph Communications API, SDK package names updated New in Microsoft Graph: API calls to get EVERYTHING a user sent in Chat, All Chats in Channels, and support for Apps in Chat Using Microsoft Graph Change Notifications? Don’t miss out on broken subscriptions with NEW lifecycle notifications