How to create an Adaptive Card

Digital Assistant supports Cards built to Microsoft's Adaptive Card specification. You can use the Adaptive Card design tool in Digital Assistant to design and deploy new custom Cards to your Assistant.

To access the Adaptive Card design tool, navigate to Your Card Hub in the Digital Assistant administration view, then select Add Adaptive Card from the Add New dropdown.

Configuration

You will now be prompted configure your new Adaptive Card. In this example, we will create a Card which uses the Microsoft 365 connector to display information about the currently logged in user.

To configure your card, follow the steps in the configuration wizard:

1. Utterances

   Utterances are phrases that you can use to train your Assistant to learn when to trigger your Card. You can read more about how utterances work in this article.

   The first utterance you add will be the title of your card. This will be displayed at the top of the Card as well as in the Cards catalog.

   To add more utterances, select Add another phrase and enter an utterance into the text box. You can add as many utterances as you like by clicking Add another phrase. You will need to add at least one utterance to use your Card with the chatbot, but we recommend at least five for best results.

   Once you've added at least one utterance to your Card, click Next to continue.

2. Connector

   To display dynamic data in your Adaptive Card, you can use any connector which has been added to your Digital Assistant as a source. To do so, first select a connector from the Connector dropdown. Then in the URL field, enter the URL of the specific connector API endpoint you wish to display data from in your Card.

   Once you've selected a connector and entered it's API endpoint URL, click Next to continue.

3. Catalog

   Your new Card will be available in the Cards section of the Digital Assistant administration view. You can add an icon and a description to your Card to make it easy for users to know what the Card does.

   Image Url

   URL to an image which is displayed as the Card icon. Should be publically accessible.

   Description

   A short text describing the function of the Card which is displayed in the Cards catalog.

   Include card in briefing

   Defines if the Card should be included in briefings.

   Show card on board

   Defines if the Card should be displayed on a user's board.

Finally, click Save to save the configuration of your new Card. You can now begin designing the Card and integrating dynamic data from your connector.

Using the Card Design tool

The Card Design tool features an easy-to-use drag-and-drop interface for adding layout and content elements to your Card. The bottom-left pane displays the JSON structure of the Card. The bottom-right pane displays the data fetched from the API endpoint specified earlier.

Detailled documentation about the Adaptive Cards standard, developing Adaptive Cards, available Card elements and data templating is available on the Microsoft website.

In this example, we will use a text block to display text on a Card. Drag and drop the TextBlock element from the Card Elements pane onto the Empty Container to add it to the Card.

To add text to the TextBlock, select the element from the right pane and enter text into the Text field. Markdown is supported. You can access data from the connector by clicking the three dots next to the Text field. Alternatively, you can click the Bind button next to the TextBlock and select a variable to insert it.

You can also access variables from the Sample Data Editor by encapsulating the key name in ${...}. Data can be accessed using dot notation. For more information about the templating features available in Adaptive Cards, refer to Microsoft's documentation.

To see a preview of your Card with data from the connector, select Preview mode. When you're happy with the design of your Card, click Save to finalize all changes.

Your new Card will now be available on the Cards page, and can be displayed as a chatbot response, on your Board, or as part of a briefing.