Building a Microsoft Teams bot: Sending custom data from an adaptive card button to the bot

This is the third article in my "Building a Microsoft Teams Bot" series. In this series, I have written 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 articles in the series: 

Building a Microsoft Teams Bot: Posting an Adaptive Card carousel as a welcome message

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

Todays article is around how to pass custom data from Adaptive Cards back to the Teams bot. This can be useful in scenarios when we want to show multiple options to the user in an Adaptive card and when the user selects an option, we want to send that option back to the bot and perform a relevant operation.

To achieve this, we will use the data property of the Adaptive Card Submit action: https://adaptivecards.io/explorer/Action.Submit.html 

This property contains a key value pair of custom data which can be sent back to the bot. 

Here is a sample of how the card json will look when posting it to Teams:

To build this type of card in our bot code, we will iterate over the options and create Adaptive card Submit buttons with the relevant values in the data property:

And finally, when the user clicks on a button, Teams platform will send the corresponding data property back to the bot. This can then be used in the Submit action of the bot to perform a relevant operation.

Hope this was helpful!

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!

Working with Adaptive Card Universal Actions in a Microsoft Teams Bot

Universal Actions for Adaptive cards are a mechanism to handle user interactions uniformly no matter where the user is accessing the Adaptive Card from. It allows Bot developers to send the same Adaptive Cards to Microsoft Teams, Outlook etc. without having to write redundant client specific code. As the Microsoft docs state:

Universal Actions for Adaptive Cards evolved from developer feedback that even though layout and rendering for Adaptive Cards was universal, action handling was not. Even if a developer wanted to send the same card to different places, they have to handle actions differently. Universal Actions for Adaptive Cards brings the bot as the common backend for handling actions. 

https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/universal-actions-for-adaptive-cards/overview?tabs=mobile

In addition to these user interactions, there are couple of really useful features delivered as part of Universal Actions. They are "User Specific Views" and "Up to date cards"

User specific views:

By using user specific views, different users see different views on the card depending on their identity and the actions they have taken. This was not the case earlier when all users who viewed an Adaptive Card posted in a Teams channel saw the same exact card. Lets see a quick example:

First lets talk about the refresh property. The property contains two important values: action and userIds. When an adaptive card containing a refresh property will load, first the Teams platform will check if the current user viewing the Adaptive Card is present in the userIds property. If they are, then an action will be sent to the bot containing the verb mentioned in the verb property. We will have to write Bot Framework code which handles this call from the Teams platform. As a response to this call, we can return a new adaptive card which will only be visible to the current user. 

All other users viewing the Adaptive card who are not part of the userIds property will keep seeing a shared common view of the base card. 

Up to date cards:

With up to date cards, we can use the Bot Framework message update functionality to update the user specific views in adaptive cards on the fly. This is so that the cards are updated to their latest state without the user having to reload the card.   

Now that we have covered the different moving parts, let's see how we can put all of this together in a code sample for a approving an asset in a Teams channel:

1) A user starts the approval process by sending a command to the bot:

The user starting the approval request is the "Owner" of this asset. When the owner sends an approval request, an adaptive card with a "Approve" button will be shown to everyone in the Team who is not the owner. Where as, the owner will see a view on the card which contains a list of users who have approved the request.

2) Approving the asset and refreshing the Adaptive Card with latest state: 

Any user in the team can click on the approve button to approve the asset. Once they approve, they will be shown a different card.

Owner will always see who approved the card. This will be kept up to date using the message edit mechanism without the need to manually reload the card.

Now we come to the crux of the blog post. Whenever a user will click on the "Approve" button, or and Adaptive Card will load which contains a refresh property with the current user's userId, an adaptiveCard/action request will be sent to our bot. The request will contain information on the action such as the verb and the context in which the action occurred. 

Out bot framework code will have to respond with the correct card depending on the action. 

In the above code, when the approveClicked action occurs, we add the user approving the asset to our persistent storage and return a card to them thanking them for the approval.

When the refreshCard action occurs, it means that a user listed in the userIds property of a card is trying to view the card. So based on the identity of the user, we will return the correct card. This is used to show the owner of the card a list of users who have approved it.

Hope you found the post useful!

Full code sample of this blog post available on GitHub: https://github.com/vman/Universal.Actions

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!