Work with Universal Actions for Adaptive Cards
Universal Actions for Adaptive Cards provide a way to implement Adaptive Card based scenarios for both, Teams and Outlook. This document covers the following topics:
- Schema used for Universal Actions for Adaptive Cards
- Refresh model
- Backward compatibility
Quick start guide to use Universal Actions for Adaptive Cards in Teams
Replace all instances of
Action.Executeto update an existing scenario on Teams.
refreshclause to your Adaptive Card, if you want to use the automatic refresh model or if your scenario requires User Specific Views.
userIdsproperty to identify which users get automatic updates.
adaptiveCard/actioninvoke requests in your bot.
Use the invoke request's context to respond back with cards that are created for a user.
Whenever your bot returns a new card as a result of processing an
Action.Execute, the response must conform to the response format.
Schema for Universal Actions for Adaptive Cards
Universal Actions for Adaptive Cards are introduced in the Adaptive Cards schema version 1.5. To use Adaptive Card effectively, the
version property of your Adaptive Card must be set to 1.5.
version property to 1.5 makes your Adaptive Card incompatible with older clients of the platforms or applications, such as Outlook and Teams, as they do not support the Universal Actions for Adaptive Cards.
If you set the card version to less than 1.5 and use either or both,
refresh property and
Action.Execute, the following happens:
|Your card stops working. Card isn't refreshed and
Action.Execute doesn't render depending on the version of the Teams client. To ensure maximum compatibility in Teams, define
Action.Execute with an
Action.Submit in the fallback property.
For more information on how to support older clients, see backward compatibility.
When authoring Adaptive Cards, replace
Action.Execute. The schema for
Action.Execute is similar to that of
For more information, see Action.Execute schema and properties.
Now, you can use the refresh model to allow Adaptive Cards to update automatically.
To automatically refresh your Adaptive Card, define its
refresh property, which embeds an action of type
Action.Execute and an
For more information, see refresh schema and properties.
User IDs in refresh
The following are the features of UserIds in refresh:
UserIds is an array of user MRIs, which is part of the
refreshproperty in Adaptive Cards.
userIdslist property is specified as
userIds: in the refresh section of the card, the card isn't automatically refreshed. Instead, a Refresh Card option is displayed to the user in the triple dot menu in Teams web client or desktop and in the long press context menu in Teams mobile, that is, Android or iOS to manually refresh the card. Alternatively, you may choose to skip
userIdsin the refresh property altogether in case the scenario involves <=60 members in Teams group chats or channels. The Teams client automatically invokes refresh calls for all the users if the group or channel has <=60 users.
UserIds property is added because channels in Teams can include a large number of members. If all members are viewing the channel at the same time, an unconditional automatic refresh results in many concurrent calls to the bot. The
userIdsproperty must always be included to identify which users must get an automatic refresh with a maximum of 60 (sixty) user MRIs.
You can fetch Teams conversation member's user MRIs. For more information on how to add in userIds list in refresh section of Adaptive Card, see fetch roster or user profile.
You can get the user MRI for channel, Group Chat or 1:1 chat using the following example:
Using GetMemberAsync method
var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);var userMRI = member.Id;
- Sample Teams user MRI is
userIds property is ignored in Outlook, and the
refresh property is always automatically activated. There is no scale issue in Outlook because users view the card at different times.
Next step is to use the
adaptiveCard/action invoke activity to understand what request must be made after
Action.Execute is executed.
adaptiveCard/action invoke activity
Action.Execute is executed in the client, a new type of Invoke activity
adaptiveCard/action is made to your bot.
For more information, see request format and properties for a typical
adaptiveCard/action invoke activity.
Next, you can apply backward compatibility to older clients across different platforms and make your Adaptive Card compatible.
Universal Actions for Adaptive Cards allow you to set properties that enable backward compatibility with older versions of Outlook and Teams.
To ensure backward compatibility of your Adaptive Cards with older versions of Teams, you must include the
fallback property and set its value to
Action.Submit. Also, your bot code must process both
For more information, see backward compatibility on Teams.
|Teams catering bot
|This sample shows a bot that accepts food order using Adaptive Cards.
|Sequential Workflows Adaptive Cards
|This sample demonstrates the implementation of Sequential Workflows, User Specific Views, and current Adaptive Cards in bots.