How to add an existing or new Whiteboard to a team channel using Graph API

When you use out of the box feature to add a Whiteboard app to team channel it always creates a new Whiteboard. Using Graph API it is possible to add an existing or a new Whiteboard to team channel. This enables to re-use Whiteboards or recovering an accidentally removed Whiteboard tab.

In my earlier blog post I explained how you can add a Whiteboard to a team channel as a tab (app). It is something anyone can do since you just click around the UI. I recently got a question (could a whiteboard be added using Graph API) I went and checked out would it be possible.

Some key things you need to have there are:

TeamsApp@odata.bind is https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/95de633a-083e-42f5-b444-a4295d8e9314
This means that Whiteboard App ID is 95de633a-083e-42f5-b444-a4295d8e9314
- While this information is not needed in this procedure, it allows you to add Whiteboard app to a team during provisioning if you want to. Or if you want to check which tabs are Whiteboards.

Adding an existing Whiteboard to a team using Graph API

In addition to info above you need

Whiteboard ID is identifying your whiteboard. You can retrieve it in the easiest way by opening the whiteboard in web version and looking at URL. The whiteboard ID is following /whiteboards/
displayName: name of your tab.
Content URL is a link to the whiteboard + instructions how to open the Whiteboard inside a tab embed=1&isOpenInTab=1
Website URL is needed when the user clicks on the globe to open the tab app in a browser

This is the JSON you need to put to Graph API POST request payload:

{
             ”displayName”: ”Whiteboard via Graph API”,
             ”teamsApp@odata.bind”: ”https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/95de633a-083e-42f5-b444-a4295d8e9314”,
             ”configuration”: {
                          ”entityId”: ”whiteboard.microsoft.com”,
                          ”contentUrl”: ”https://app.whiteboard.microsoft.com/me/whiteboards/[yourwhiteboardid]?embed=1&isOpenInTab=1”,
                          ”removeUrl”: null,
                          ”websiteUrl”: ”https://app.whiteboard.microsoft.com/me/whiteboards/[yourwhiteboardid]”
             }
}

To add the tab you need to use the good old Add a tab to a channel. You need to know the team and channel ID before calling POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/tabs
This call requires several permissions, check up to date ones from the Add a tab documentation. Of course if you are adding tabs to team channels then you have these set up already.

I used delegated permissions during testing this out – using Graph Explorer.

There are still some more permissions to add..

Of course the board will work very well.. for you. But concerning other members of the team they see the following if you don’t do anything else..

You need to open Whiteboard Desktop application and add all team members as participants to the Whiteboard separately.

You can alternatively create a sharing link to the board and guide members to click it in the web to activate their permissions to the board. The link can be easily created via Web Whiteboard.

Are there real use cases for this?

Yes, there are! Using this little trick you can insert an existing Whiteboard to a team. I see three good use cases for this one:

This can be useful in case you want to continue using the meeting Whiteboard but in a team. It might be safe to think that most of people will have access to the board and the rest can be managed via the sharing link or adding explicit permissions
Somebody removed the Whiteboard tab from team channel and you want it back. Currently this is an issue when you add a Whiteboard app to a team channel: it only creates a new Whiteboard
You have started to work on a Whiteboard without a connection to a team. This is similar to the first use case

What about custom provisioning a Whiteboard?

Of course there is a way to add a Whiteboard to a team when provisioning it! You can use Team templates or .. you can add it via Graph API. Keep reading and skip Team template part if you want Graph API instead of mouse clicks!

When adding a Whiteboard app via provisioning (or adding that to a team later with a script) it also takes care of any permissions out of the box as opposed when adding an existing Whiteboard to a team via Graph API.

Using Team Template

If you want a Whiteboard to a team channel when a new team is provisioned then you could consider using Team templates for that. You can add apps to channels in there – they are just placeholders but it can create a new Whiteboard when team is provisioned.

And when the Team is provisioned with this template team owner (usually that person is the first one to go through channels and tabs) can add the new Whiteboard to the team channel.

Using Graph API to add Whiteboard app during provisioning (or adding via script)

It is actually fairly simple to add Whiteboard (or any other application channel tab) during provisioning with a little Graph API. After all – we only need to know the Team App ID for the application.

Add that application to the team using Add app to team. POST /teams/{team-id}/installedApps
Add application app tab without content details

POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/tabs

{
             ”displayName”: ”Whiteboard”,
             ”teamsApp@odata.bind”: ”https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/95de633a-083e-42f5-b444-a4295d8e9314”,
             ”configuration”: {
                          ”entityId”: null,
                          ”contentUrl”: null,
                          ”removeUrl”: null,
                          ”websiteUrl”: null
             }
}

The secret is in the TeamsApp@odata.bind section that defines “Whiteboard application goes here”.