A bot communicates with users through message activities which are multi-modal. There are messages which simply consist of plain text and there are also richer message content such as cards. Bot Framework Composer supports structured response template with which you can add rich cards to your bot and enhance your bot's design. If you are looking for examples about sending text messages to users please read the sending messages to users article.
In this article, we will cover different types of cards you can define in Composer using structured response template. We use the examples provided in the RespondingWithCardsSample throughout this article.
Composer currently supports the following types of rich cards. The definition and use of each type of the cards is provided in the RespondingWithCardsSample.
| Card type | Description |
|---|---|
| Hero Card | A card that typically contains a single large image, one or more buttons, and simple text. |
| Thumbnail Card | A card that typically contains a single thumbnail image, one or more buttons, and simple text. |
| Signin Card | A card that enables a bot to request that a user sign-in. It typically contains text and one or more buttons that the user can click to initiate the sign-in process. |
| Animation Card | A card that can play animated GIFs or short videos. |
| Video Card | A card that can play a video file. |
| Audio Card | A card that can play an audio file. |
| Adaptive Card | A customizable card that can contain any combination of text, speech, images, buttons, and input fields. |
| All Card | To display all cards. |
In Composer we use structured response template to define the cards you want to send back to users. To get yourself familiar with the structured LG template, it is recommended that you read the Language Generation concept article and the structured response template article.
A typical structured response template for cards consists of the following parts:
# CardTemplateName
[CardStructure-name
title = title of the card
subtitle = subtitle of the card
text = description of the card
image = url of your image
buttons = name of the button you want to show in the card]
| Template Component | Description |
|---|---|
| # CardTemplateName | Name of the structured card template starting with "#". |
| [ ] | A pair of square brackets to wrap the content of the structure. |
| CardStructure-name | Name of the structure. |
| title | A title of the defined template such as "BotFramework Hero Card". |
| subtitle | A subtitle of the defined template such as "Microsoft Bot Framework". |
| text | A brief description of the template. |
| image | The url of your image. |
| buttons | Name of the button you want to show in the card. |
Now, let's walk through the card examples in the RespondingWithCardsSample and learn how each type of the cards are defined and used.
A Hero card is a basic card type that allows you to combine images, text and interactive elements such as buttons in one object and present a mixture of them to the user. A HeroCard is defined using structured template as follows:
# HeroCard
[HeroCard
title = BotFramework Hero Card
subtitle = Microsoft Bot Framework
text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
image = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
buttons = @{cardActionTemplate('imBack', 'Show more cards', 'Show more cards')}
]
# HeroCardWithMemory(name)
[Herocard
title=@{TitleText(name)}
subtitle=@{SubText()}
text=@{DescriptionText()}
images=@{CardImages()}
buttons=@{cardActionTemplate('imBack', 'Show more cards', 'Show more cards')}
]
This example of hero card will enable your bot to send an image from a designated url back to users when an event to send a hero card is triggered. The hero card will include a button to show more cards when pressed.
A Thumbnail card is another type of basic card type that combines a mixture of images, text and buttons. Unlike Hero cards which present designated images in a large banner, Thumbnail cards present images as thumbnail. It is card that typically contains a single thumbnail image, one or more buttons, and simple text. A ThumbnailCard is defined using structured template as follows:
# ThumbnailCard
[ThumbnailCard
title = BotFramework Thumbnail Card
subtitle = Microsoft Bot Framework
text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
image = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
buttons = Get Started]
A Signin card is a card that enables a bot to request that a user sign in. A SinginCard is defined using structured template as follows:
# SigninCard
[SigninCard
text = BotFramework Sign-in Card
buttons = @{cardActionTemplate('signin', 'Sign-in', 'https://login.microsoftonline.com/')}
]
Animation cards contain animated image content (such as .gif). Typically this content does not contain sound, and is typically presented with minimal transport controls (e.g, pause/play) or no transport controls at all. Animation cards follow all shared rules defined for ort controls (e.g. rewind/restart/pause/play). Video cards follow all shared rules defined for Media cards. An AnimationCard is defined using structured template as follows:
# AnimationCard
[AnimationCard
title = Microsoft Bot Framework
subtitle = Animation Card
image = https://docs.microsoft.com/en-us/bot-framework/media/how-it-works/architecture-resize.png
media = http://i.giphy.com/Ki55RUbOV5njy.gif]
Video cards contain video content in video format such as .mp4. Typically this content is presented to the user with advanced transport controls (e.g. rewind/restart/pause/play). Video cards follow all shared rules defined for Media cards. A VideoCard is defined using structured template as follows:
# VideoCard
[VideoCard
title = Big Buck Bunny
subtitle = by the Blender Institute
text = Big Buck Bunny (code-named Peach) is a short computer-animated comedy film by the Blender Institute
image = https://upload.wikimedia.org/wikipedia/commons/thumb/c/c5/Big_buck_bunny_poster_big.jpg/220px-Big_buck_bunny_poster_big.jpg
media = http://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4
buttons = Learn More]
Audio cards contain audio content in audio format such as .mp3 and .wav. Audio cards follow all shared rules defined for Media cards. An AudioCard is defined using structured template as follows:
# AudioCard
[AudioCard
title = I am your father
subtitle = Star Wars: Episode V - The Empire Strikes Back
text = The Empire Strikes Back (also known as Star Wars: Episode V – The Empire Strikes Back)
image = https://upload.wikimedia.org/wikipedia/en/3/3c/SW_-_Empire_Strikes_Back.jpg
media = http://www.wavlist.com/movies/004/father.wav
buttons = Read More]
Adaptive cards is an open source toolset of Microsoft that helps apps and services exchange rich snippets of native UI. Card authors describe their content as a simple JSON object. That content can then be rendered natively inside a host application, automatically adapting to the look and feel of the host. To get an overview of adaptive cards please visit here. An AdaptiveCard is defined using structured template as follows:
# AdaptiveCard
[Activity
Attachments = @{json(adaptivecardjson())}
]
This template "#AllCards" is defined to display all cards when the template is called.
# AllCards
[Activity
Attachments = @{HeroCard()} | @{ThumbnailCard()} | @{SigninCard()} | @{AnimationCard()} | @{VideoCard()} | @{AudioCard()} | @{AdaptiveCard()}
AttachmentLayout = @{AttachmentLayoutType()}
]