Web Chat now supports Adaptive Cards, which you can use to achieve a greater level of rich display and interactivity in your bot's UX. Adaptive Cards are a general-purpose technology, which may be used in a wide variety of applications. In the Bot Framework, Adaptive Cards have certain limitations on each channel; this document outlines the constraints when using them within the Web Chat environment.
Please see the Bot Framework documentation site for examples of how to create and send an Adaptive Card from either Node.js, .NET, or REST.
An Adaptive Card may provide actions that define buttons that the user may tap. There are four types of Adaptive Card actions:
| Action Type | Implementation details |
|---|---|
| Action.OpenUrl | Supported. Opens the URL in a new browser tab. |
| Action.ShowCard | Supported. May change the size of your card. |
| Action.Submit | Supported. The data property of the action may be a string or it may be an object. A string is passed back to your bot as a Bot Builder SDK imBack activity, and an object is passed as a postBack activity. Activities with imBack appear in the chat stream as a user-entered reply. The postBack activities are not displayed. |
| Action.Http | Not supported in Web Chat. Web Chat filters out any actions that have the Action.Http type, and they are not be displayed. This filtering applies to actions on the root card and subcards. The recommendation is to use Action.Submit instead, then execute any HTTP requests on the server side within your bot code. |
The existing Bot Builder SDK card types (Hero, Thumbnail, Audio, Video, Animation, SignIn, Receipt) are now implemented as Adaptive Cards. You may see some slight rendering differences from previous versions of Web Chat. However, as the card is adapted to the fields you've populated, the displayed card should be more natural for the user.
Bot Builder SDK cards may specify a tap action on the entire card (Example: HeroCard .NET | Node.js | Rest ). Since Adaptive Cards have introduced interactive elements such as checkboxes, textboxes, and drop-down menus, the tap action is invoked only if the tap event occurs on a non-interactive element.
Audio and Video are not yet part of the Adaptive Cards schema. So, Bot Builder SDK Audio and Video cards are implemented as a Media element followed by an Adaptive Card.
-
Action buttons are displayed at full card width by default. Each button occupies its own vertical space. In previous versions of Web Chat, buttons followed a word-wrap layout. To ensure the entire card displays on the screen, we recommend not using more than five buttons.
-
Adaptive Cards may define columns of data. It is common for a Web Chat control to be a sidebar or an otherwise narrow window. Having many columns may force a layout wider than the typical chat window.
-
Unlike CSS media queries, Adaptive Cards do not currently have a layout model that is constrained by device size. We recommend limiting the number of columns in a card.
Your Adaptive Card is in JSON format and should adhere to the Card schema. If your JSON does not validate to the schema, then an error card is shown, and the error details outputted to the JavaScript console.
It is important to understand how Adaptive Cards separate the concerns of card content from presentation style. The cards produced by your bot are purely semantic content, and the presentation style is driven by a Host Configuration JSON structure. Style aspects such as font, color, and margin sizes are specified in the Host Configuration.
Note: Web Chat is unique in that it is the only Bot Framework channel where the bot developer can customize the look and feel of the channel. In other channels, the Adaptive Cards Host Configuration is not under the bot developer's control.
The Adaptive Cards Host Configuration is stored in the /adaptivecards-hostconfig.json file in the root of this repo. This file's content is embedded into /botchat.js when you run the npm run webpack command. If you have created a Host Configuration file elsewhere, replace the contents of /adaptivecards-hostconfig.json, then run npm run webpack.
You may wish to create your Host Configuration using SCSS in this repo. This method allows you to share variables (which may contain font, color, and margins) between CSS and the Adaptive Cards Host Configuration. Follow these steps to create your Host Configuration from SCSS:
-
Find the file
/src/scss/includes/adaptive-card-config.scssand modify its contents. -
Run the command
npm run build-ac-config, which creates the/adaptivecards-hostconfig.jsonfile for you from the SCSS source.- If you change an SCSS resource that is shared by both your CSS and the Adaptive Cards Host Configuration, such as
/src/scss/includes/colors.scssor/src/scss/includes/settings.scss, you may wish to build both/botchat.cssand/adaptivecards-hostconfig.jsonby running the commandnpm run build-all-styleinstead.
- If you change an SCSS resource that is shared by both your CSS and the Adaptive Cards Host Configuration, such as
-
Embed the JSON file as previously described, by running
npm run webpack.
It is also possible to supply an Adaptive Cards Host Configuration without the need to webpack. Start with the basic example from the readme, then add some script prior to instantiating BotChat.App:
<!DOCTYPE html>
<html>
<head>
<link href="https://cdn.botframework.com/botframework-webchat/latest/botchat.css" rel="stylesheet" />
</head>
<body>
<div id="bot"/>
<script src="https://cdn.botframework.com/botframework-webchat/latest/botchat.js"></script>
<script>
//set Adaptive Cards Host Configuration
AdaptiveCards.setHostConfig( {YOUR JSON HERE} );
BotChat.App({
directLine: { secret: direct_line_secret },
user: { id: 'userid' },
bot: { id: 'botid' },
resize: 'detect'
}, document.getElementById("bot"));
</script>
</body>
</html>