Teams tab fails to load in the new Microsoft Teams Desktop client

The new Microsoft Teams Desktop client was made generally available for Windows and Mac recently. The good news is that the new client provides feature parity for 3rd party apps like Focusworks AI giving customers a choice of using their preferred Teams client to access the apps.

However, if you have a custom built Microsoft Teams tab or a task module as part of your solution, and find that it fails to load in the new Microsoft Teams client, there might be a specific reason for it. 

And since there is no way to invoke the Developer tools in the new Teams desktop client yet (November 2023), the experience can get a bit frustrating. 

In my case, I have a custom React/TypeScript based tab which is using the @microsoft/teams-js library to interact with Teams. 

Since teams tabs are just HTML pages, we need to make sure that the page is being loaded inside Teams before continuing to execute the code. To do that we can use the context.app.host.name property and check that the value was "teams" before moving ahead.

However, with the new desktop client my tab was failing to load. After a bit of digging around I realised that the new Teams desktop client has an entirely different host name property and the value is "teamsModern" as mentioned here: https://learn.microsoft.com/en-us/javascript/api/%40microsoft/teams-js/hostname?view=msteams-client-js-latest

So changing my code to include the new value as well worked!

Hope this saves you some debugging time!

Building a Microsoft Teams Bot: Deep linking to a Teams message from an Adaptive Card button

This is the second article in my "Building a Microsoft Teams Bot" series. In this series, I am planning to write down some interesting things I came across while creating a Microsoft Teams Bot app which is now available on AppSource: https://appsource.microsoft.com/en-us/product/office/WA200002297

Click here to see the previous article in the series: Building a Microsoft Teams Bot: Posting an Adaptive Card carousel as a welcome message

Todays article is around how to create deep links to teams messages from Adaptive cards. This can be useful in scenarios when you want to send users to a specific Teams chat message when they click on an Adaptive Card button:

If you are building the deep link manually, it can be grabbed from the "Copy link" button from the ellipsis menu in a Teams message:

Deep links to personal chats are in a different format compared to channel messages.

 

For Teams messages, the deep link format is:

https://teams.microsoft.com/l/message/{ChannelId}/{messageId}

For personal chats, the deep link format is:

https://teams.microsoft.com/l/message/19:{userAadObjectId}_{botId}@unq.gbl.spaces/{messageId}?context=%7B%22contextType%22:%22chat%22%7D

For bots and messaging extensions, this deep link can be built from parts of the payload sent to the Bot from the Teams platform when the bot is invoked:

Once you have the desired deep link, the next step is to assign it as the URI to an Adaptive Card button:

And that's it! Now you can easily add buttons to your adaptive cards which take the user to specific messages in Teams personal chats or channels. 

Hope this was helpful!

Microsoft Teams messaging extensions using SPFx: Getting the message data with Microsoft Graph

With SPFx 1.11, one of the things possible now is that SharePoint Framework web parts can be exposed as Microsoft Teams messaging extensions. So what are messaging extensions exactly? According to the Teams docs:

"Messaging extensions allow users to interact with your web service through buttons and forms in the Microsoft Teams client. They can search, or initiate actions, in an external system from the compose message area, the command box, or directly from a message. You can then send the results of that interaction back to the Microsoft Teams client, typically in the form of a richly formatted card."

https://docs.microsoft.com/en-us/microsoftteams/platform/messaging-extensions/what-are-messaging-extensions

As a Microsoft 365 Developer, messaging extensions are a great way to invoke custom code right in the Teams client. This opens up the possibility of users interacting with your application right in the context of their conversations without having to leave Teams.

The SPFx docs give a nice overview of how to setup web parts so that they are exposed as compose  extensions. This enables the custom SPFx webpart to be invoked from the "Compose new message" box in Teams: https://docs.microsoft.com/en-us/sharepoint/dev/spfx/build-for-teams-expose-webparts-teams#expose-web-part-as-microsoft-teams-messaging-extension 

In this post, we are going to be talking about SPFx webparts being hosted in task modules which show up in "message actions" i.e. invoking custom code on messages which are already posted in Teams. This could be either in channels or in personal or group chats.

(click to zoom)

Now behind the scenes, when a message action is invoked on a message, we want to get the message context passed to our SharePoint Framework web part. By message context, I mean properties like teams id and channel id in which the action was invoked. If the message action was invoked in a personal chat or a group chat, then we need to know the chat id instead. And finally, we need the data about the message itself e.g. message id, message body, who posted the message etc. so that we can then send the information to our application right from the SPFx webpart.

Now if we were using the Bot Framework to power our message action (and task module), then getting these properties is straightforward as every time the message action is invoked, the Bot Framework sends this information to our messaging endpoint: https://docs.microsoft.com/en-us/microsoftteams/platform/messaging-extensions/how-to/action-commands/create-task-module?tabs=json#example-fetchtask-request

When using SharePoint Framework however, we have to take a longer route. When the message action would be invoked on a Teams message: Although we get the context information like team id, channel id and chat id, all we will get about the message itself is just the id. No other data about the message like the body, user etc will be available. Getting all these other details would be up to us. Let's see how we do that:

Teams app manifest

First, to get the SPFx powered message action working, we need to configure it in the Teams manifest.

Notice that the fetchTask property is set to false. This makes the task module defined in the manifest to be displayed. (If fetchTask is set to true, the Teams will go to the Bot messaging endpoint to get the task module dynamically)

Also notice that the url for a SharePoint Framework Task module is slightly different compared to a Teams tab

SPFx and Microsoft Graph:

Although we won't have the message data directly provided to us in SPFx, we would have all the context information necessary to fetch the data. As part of the microsoftTeams context object, we will have the teamId, channelId, chatId and the parentMessage. We can then use these details along with the Microsoft Graph to get the message details:

Before we go through the code, make sure that the SPFx solution has the Chat.Read permissions on the Microsoft Graph configured in the package-solution.json file. This will allow us to read the Teams messages on behalf of the currently logged in user

And finally, here is the SPFx code to get the message details on which the message action was invoked:

Hope you found the post useful! Here is the SPFx webpart code on GitHub: https://github.com/vman/spfx-teams-message-action

Note:

This approach currently works with Teams messages in personal chats, group chats and top level messages in Teams channels. There seems to be a gap right now where this approach does not work for replies posted to top level teams messages. I have opened up a GitHub issue about this and will post a follow up soon. https://github.com/OfficeDev/microsoft-teams-library-js/issues/398 

Microsoft Teams Bot Framework: Mention a user in an Adaptive Card

Microsoft Teams announced support for Adaptive Cards 1.2 recently. With that, a nifty feature to allow mentioning users in Adaptive Cards posted in Teams was also introduced. This allows us the ability to send a notification to the user and can draw their attention towards the card.

User gets a notification of the mention:

(click to zoom)

Other users are able to contact the user directly from the mention in the card:

(click to zoom)

Checkout the announcement if you haven't already: https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format?tabs=adaptive-md%2Cconnector-html#mention-support-within-adaptive-cards-v12

In the docs, there is a great example of the JSON we need to send to Teams to post the card containing the mention. So in this post, lets see how we can do this when using the Bot Framework .NET Core SDK:

For this code to work, we will need the following Nuget packages:

Microsoft.Bot.Builder

AdaptiveCards

Quick note: I noticed that the user mentioned is only notified when the Adaptive card is first created. If you update the same adaptive card later and mention the same user again, they are not notified. This is probably for the best as the Adaptive card might be updated several times and if you got a notification every time, it might be really annoying to the user.

Hope you found this post useful!

Building a Microsoft Teams Bot: Get Team context details including Office 365 Group and SharePoint site url

The Microsoft Bot Framework v4.6 was released this week at Ignite and it's got some really great additions:
https://github.com/microsoft/botframework/blob/master/whats-new.md#november-2019-ignite

One thing which I am very happy about is that building Bots for Microsoft Teams has become way easier now!

This wasn't always the case. Previously, the Bot Framework was separate to the Teams Bot Builder and they both didn't play nice all the time. Throw in more stuff like Bot Framework v3/v4, Messaging extensions, Adaptive Cards and it lead to tweets like this:

Interesting couple of weeks with Bot Framework v4, Teams Bot Builder, Messaging Extensions and user delegated auth! Not everything wants to play nice with each other but finally getting somewhere!

— Vardhaman Deshpande (@vrdmn) August 30, 2019

But now, the Teams Bot Builder is part of the the Bot Framework SDK itself which is very good news. If you are just getting started building Bots for Microsoft Teams, you only need to install the Bot Framework package. Apart from that, the code to work with Microsoft Teams has been simplified as well.

Imagine you are building a Teams Bot and it needs to interact with the Office 365 Group which underpins the Team. Or maybe the Bot needs to store or retrieve some data from the SharePoint site associated with the Team. Let's see how easy it is now to achieve this:

Before we look at the code, make sure you are using the Microsoft.Bot.Builder 4.6+ version of packages in your Bot:

https://github.com/Microsoft/botbuilder-dotnet/#packages
https://www.nuget.org/packages/Microsoft.Bot.Builder/

We will also need the Microsoft Graph .NET SDK:
https://docs.microsoft.com/en-us/graph/sdks/sdk-installation

And here is the code:


We are using the new TeamsInfo class available in the Bot Framework to get the current team details. This class also has a few other helper methods which you might find useful:
https://github.com/microsoft/botbuilder-dotnet/blob/master/libraries/Microsoft.Bot.Builder/Teams/TeamsInfo.cs

Internally the TeamsInfo.GetTeamDetailsAsync method calls the `/v3/teams/{team-id}` API endpoint to get the Office 365 Group id (a.k.a AADGroupId in the API). We can then use the Microsoft Graph API to get the other details including the SharePoint site url.

Hope this helps! For more details on building bots for Microsoft Teams, have a look at the official docs: https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-for-teams

Microsoft Teams messaging extensions: User authentication, OAuth and Microsoft Graph

Microsoft Teams messaging extensions allow us to enhance teams messages with business data. We are able to fetch information (e.g. from Microsoft Graph or 3rd party APIs) based on various factors like the current user, current team or current channel and post it as part of a message using rich Adaptive cards.

This gives us a great way of creating Teams based integrations with other Line of Business (LOB) applications.

I won't go much deeper into the different possibilities with messaging extensions in this post. Instead, we will focus more on how they are built and how to authenticate the current user.

To know more about messaging extensions, have a look at the Microsoft docs:
https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/messaging-extensions/messaging-extensions-overview

Teams messaging extension architecture:

The way in which the messaging extensions work is by leveraging the Microsoft Bot Framework and utilising the following moving pieces:

1) A Bot Channel Registration which is essentially the identity of the Bot/Messaging extension. We need this to get the Bot Id and also to set "Microsoft Teams" as one of the channels served by the bot.

2) An endpoint which will receive (and respond to) HTTP POST messages from teams when the messaging extension commands are invoked.

3) A Teams App Manifest which contains the JSON specifying the messaging extension properties, the Bot  Id, and the messaging endpoint.

Those are the primary building blocks of a Teams messaging extension (or even a Teams Chat Bot for that matter, but that's out of scope for this post)

To see a walk-through of building a messaging extension from scratch, check out Cameron Dwyer's post: https://camerondwyer.com/2019/09/09/how-to-create-a-microsoft-teams-messaging-extension-pop-up-dialog-with-a-custom-ui/

Fetching data from Microsoft Graph as the current user (delegated authentication)

This is how the sign in flow will look. The user will have to sign in only once into the app. After that, the token flow (including the access tokens and refresh tokens) will be handled by the Bot Framework.

The user is prompted to sign in the first time they launch the compose messaging extension. After the sign in is completed, the messaging extension is able to show "security trimmed" data from the Graph. In this case, it's the groups the current user has joined:

Now let's see how we can leverage the Microsoft Graph in our messaging extensions. Before fetching data from the Graph, we will need an Azure AD OAuth token for the current user in Teams. To get the token flow working, first we need to create and Azure AD App Registration and give it necessary permissions:

Next, we need to create and configure the Bot Channel Registration:

Next, create and configure an OAuth Connection Setting in the Bot Channel Registration. The Client Id, Client Secret and Tenant Id should come from the AAD App Registration created in the previous step.

And here is the code to include in the Bot which handles the AAD sign in flow of the user. I am using the Bot Framework v4 for this Bot:


This code will fetch you the access token needed for calling the Graph. After that you can use the Graph SDK to get the required data:


Hope this was helpful. Given the complexity of Microsoft Teams development at this time, this post wasn't as comprehensive as I wanted it to be. There are challenges to getting everything to work together including Bot Framework v4, Teams Bot Builder (preview), Adaptive Cards and Messaging extensions. Hope the story becomes much simpler in the future.

Debugging a Microsoft Teams Tab built with SharePoint Framework

With SPFx 1.7, the ability to build Microsoft Teams tabs with SharePoint Framework was released in preview. It's not just a SharePoint page hosted in a teams tab, it's aware of the context information around the current user, team, channel, tab etc. and is also able to interact with the team.

Here is the Microsoft docs article about it, have a read if you haven't already:
https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/using-web-part-as-ms-teams-tab

The article walks us through the process of building and publishing a production package of an SPFx solution so that it can be used as a SPFx webpart as well as a tab in Microsoft Teams.

In this post, we will go through the process of actually debugging the solution when it is being built. During development, when we make changes to the TypeScript code, we don't want to publish a production package to the App Catalog every time to test our changes.

The ideal development flow for me is to upload the SPFx package once to the App Catalog on the dev tenant, run gulp serve and when changes are made to the code, they should immediately be available to test as a Microsoft Teams tab.

To achieve this, first you will need to create an SPFx 1.7 solution as described in the docs, then update the webpart code to make sure that the microsoftTeams.Context is available to consume.

(Note: Make sure to use the SPFx v1.7.0 and not SPFx v1.7.1 which is the latest version at the time of writing this article. There is a bug in the latest version which does not create the teams folder automatically through the generator. More details here)

Now here is where the process deviates. Instead of creating the production package with the --ship flag, we will create a development package with:

gulp bundle

and then

gulp package-solution

After which you should see the console screen similar to this:

Getting the warning which says that the scripts (Client Site Assets) will not be packaged with the solution is important as we want them to be referenced from the local dev machine.

Next, we will upload and deploy the package to the tenant app catalog as usual:

Notice that the scripts will be loaded from localhost.

Next we need to make the scripts available from localhost. For that, we will run:

gulp serve

Now we need to upload the teams package which will make the SPFx webpart available in teams as a Tab.

This process is exactly similar to how it's done in the Microsoft docs article:
https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/using-web-part-as-ms-teams-tab#packaging-and-deploying-your-web-part-as-a-microsoft-teams-tab

We make sure that side loading of apps is enabled on Teams, then go to any Team > Ellipsis > Manage Team >  Apps > Upload a custom app > Upload the Zip file.

Then go to a channel in the Team > The plus button (+) > Add a tab > Select your app > Save

That's it! You Teams tab is now loading the scripts from localhost:

Make sure gulp serve is still running and then you can test by changing something in the code and press the reload tab button. The tab should be updated with the new code.

You can also test in the Teams Desktop client. Just make sure that the "Developer Preview" option is enabled:

Thanks to petkir for this tip!

After this, your SPFx tab should load in on the Teams Desktop client as well:

Hope this helps!