Adaptive Cards

See Also: QnA Ability

What are Adaptive Cards?  

Adaptive Cards add a greater level of rich display and interactivity to a bot's User Interface (UI). Watch this video for an overview. 

What are the capabilities?  

• Rich text formatting. 
• Displaying images.
• Linking to external resources. 
• Buttons to link to content, or to direct a conversation.

 

Which ability can I use them with?  

Adaptive Cards work best with the QnA Ability.

 

What do I need?  

• An understanding of Adaptive Cards.
• An understanding of how to use JSON (Javascript) and rich text formatting (Markdown) code.
• The LiveTiles QnA Editor is the recommended tool for smoothly adding Adaptive Cards into a QnA Ability's Knowledge base (KB). You can otherwise use a code editor (IDE), such as Visual Studio Code or JSONLint to edit your JSON code.

 

Visual Examples:

Here are some example LiveTiles Bots we created to help widen your view of what Adaptive Cards are capable of. Instead of having strictly text-driven responses, Adaptive Cards allow for more flexibility and advanced features in terms of user-bot interaction. 

 

 

How do I format my JSON code for my bot?

Whether you are putting your JSON code into a bot response (such as in an answer to a QnA pair), or into the Welcome Message field within your bot settings, you will need to use the right format for your JSON code.

Webchat

For Bots deployed to a webchat URL, the format of a JSON object is comprised of 3 main sections:

• The JSON adaptive card wrapper- This is the content type and contact declarations that allow the Bot platform to identify the resulting message as an adaptive card. The main adaptive vard JSON code that comes out of Microsoft's Adaptive Card builder needs to be wrapped in this header in order for the card to render and function properly

{

               "contentType": "application/vnd.microsoft.card.adaptive",

               "content":[Insert Adaptive Card Content Here]

}

Example:

• The Body -  This is the area of the JSON that defines the header images and text of the Adaptive Card according to the Microsoft Adaptive Card Elements and Container Schemas

Example:

• The Actions - This is the area of the JSON that defines the buttons, button text and resulting actions of the Adaptive Card according to the Microsoft Adaptive Card Actions Schemas. Only the "Submit", "OpenURL" and "ShowCard" actions are currently supported in accordance with version 1.1 of Adaptive Cards. The "Submit" action will result in a bot message response to be sent back to the Bot Framework, "OpenURL" will open the embedded URL in a separate tab or application and "ShowCard" will show a nested Adaptive Card

Example:

Teams

• Adaptive Card JSON objects for use in Teams Bots have the exact same setup as Webchat Bots, with one exception and this is the "Submit" action. 
• Due to differences in the Teams framework, a variation of the JSON code needed to submit a message back to the Bot Framework is required as shown below. Notice the difference in the "Data" property:

Webchat Deployment

Teams Deployment

How do I add Adaptive Cards to QnA Maker?

Follow these steps once you have an understanding of JSON code and Markdown rich text formatting:

With the LiveTiles QnA Editor:

1. Create your Knowledge base (KB) in Microsoft's QnA Maker.
2. Open your Knowledge base in the LiveTiles QnA Editor. 
3. Enter your Adaptive Card JSON code:
   · Drag and drop a pre-made Adaptive Card template from the Adaptive Card Templates panel into the New Answer field.
   · Copy your Adaptive Card code from an IDE into the New Answer field of the QnA Editor. 

Without the LiveTiles QnA Editor:

1. Create your Knowledge base (KB) in Microsoft's QnA Maker.
2. Remove any extra spaces and special characters from your JSON code. This is called minification. You can use this online tool to minify your JSON. 
3. Validate your JSON using this online tool.
4. Copy and Paste your minified JSON into your QnA Maker KB. 

5. Click Save and train. Once that's finished, click Publish.
6. After linking your updated KB to LiveTiles Bots, you should now be able to see and test your Adaptive Cards. Click here to see how you can link your KB to LiveTiles Bots.

You are ready to try out the Adaptive Cards!

________________________________________________________________________________________________________________

If you have used Microsoft's Adaptive Card documentation to design an Adaptive Card, you must wrap the code with the following contentType statement:

{    "contentType": "application/vnd.microsoft.card.adaptive",
    "content":
}

So, for example, if your Adaptive Card code reads as such:

{
        "type": "AdaptiveCard",
        "body": [
            {
                "type": "TextBlock",
                "weight": "Bolder",
                "text": "Hi there!",
                "wrap": true
            }
        ],
        "actions": [],
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "version": "1.0"
    }

...then you must wrap the code to look like this:

{    "contentType": "application/vnd.microsoft.card.adaptive",
    "content": {
        "type": "AdaptiveCard",
        "body": [
            {
                "type": "TextBlock",
                "weight": "Bolder",
                "text": "Hi there!",
                "wrap": true
            }
        ],
        "actions": [],
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "version": "1.0"
    }
}

__________________________________________________________________________

Best Practices: 

• Keep the number of Actions to a minimum (around 3 or 4). Consider using the ShowCard action for nesting Cards with further Actions.
• Keep the 'title' string under 30 characters long. Longer titles may be cut off on smaller devices.
• When linking to a mailto (email) or tel (phone call) URL, try to put the address in the 'title' field rather than obscuring the end point of that action. (e.g. '1800 123 456' rather than 'Call Us'.) Note: Ignore this rule if the address is too long.
• For ShowCard or OpenUrl buttons/actions, write the 'title' in concise 'Title-like' strings. (e.g. 'Open Website' rather than 'Open the website.')
• For Submit buttons/actions, write the both the 'title' and 'data' in concise natural language. (e.g. 'Show more options.' rather than 'Show More Options'.) While it's possible to use separate strings between what is displayed on the button (the 'title') rather than what is submitted (the 'data'), keep these identical whenever possible to maintain consistency and user expectations.
• Use apostrophes (‘ ‘) for in-text quotes rather than full quotation marks (“ “). Full quotation marks will break Adaptive Card JSON code.