0
# Rich Card Components
1

2
Rich interactive card models for creating enhanced user experiences including hero cards, thumbnails, receipts, OAuth flows, and media content with buttons and actions.
3

4
## Card Types
5

6
### Hero Card
7

8
The primary rich card type for displaying structured content with title, subtitle, text, images, and action buttons.
9

10
```python { .api }
11
class HeroCard(Model):
12
    def __init__(self, *, title: str = None, subtitle: str = None,
13
                 text: str = None, images: List[CardImage] = None, 
14
                 buttons: List[CardAction] = None, tap: CardAction = None, **kwargs): ...
15
```
16

17
```python
18
from botbuilder.schema import HeroCard, CardImage, CardAction
19

20
hero_card = HeroCard(
21
    title="Welcome Card",
22
    subtitle="Getting Started Guide", 
23
    text="This card helps you get started with the bot.",
24
    images=[CardImage(url="https://example.com/image.jpg")],
25
    buttons=[
26
        CardAction(type="openUrl", title="Learn More", value="https://docs.microsoft.com"),
27
        CardAction(type="imBack", title="Get Help", value="help")
28
    ]
29
)
30
```
31

32
### Thumbnail Card
33

34
A variant of hero card optimized for smaller display with thumbnail-sized images.
35

36
```python { .api }
37
class ThumbnailCard(Model):
38
    def __init__(self, *, title: str = None, subtitle: str = None,
39
                 text: str = None, images: List[CardImage] = None,
40
                 buttons: List[CardAction] = None, tap: CardAction = None, **kwargs): ...
41
```
42

43
### Basic Card
44

45
A simple card with basic content and optional interactive elements.
46

47
```python { .api }
48
class BasicCard(Model):
49
    def __init__(self, *, title: str = None, subtitle: str = None,
50
                 text: str = None, images: List[CardImage] = None,
51
                 buttons: List[CardAction] = None, tap: CardAction = None, **kwargs):
52
        """
53
        A basic card.
54
        
55
        Parameters:
56
        - title: Title of the card
57
        - subtitle: Subtitle of the card
58
        - text: Text for the card
59
        - images: Array of images for the card
60
        - buttons: Set of actions applicable to the current card
61
        - tap: This action will be activated when user taps on the card itself
62
        """
63
```
64

65
```python
66
from botbuilder.schema import BasicCard, CardAction, CardImage
67

68
basic_card = BasicCard(
69
    title="Basic Information",
70
    subtitle="Simple Card Example",
71
    text="This is a basic card with minimal styling.",
72
    images=[CardImage(url="https://example.com/basic.jpg")],
73
    buttons=[CardAction(type="imBack", title="OK", value="acknowledged")]
74
)
75
```
76

77
### Media Cards
78

79
Cards for audio, video, and animation content with playback controls.
80

81
```python { .api }
82
class AudioCard(Model):
83
    def __init__(self, *, title: str = None, subtitle: str = None,
84
                 text: str = None, image: ThumbnailUrl = None,
85
                 media: List[MediaUrl] = None, buttons: List[CardAction] = None,
86
                 shareable: bool = None, autoloop: bool = None,
87
                 autostart: bool = None, aspect: str = None, **kwargs): ...
88

89
class VideoCard(Model):
90
    def __init__(self, *, title: str = None, subtitle: str = None,
91
                 text: str = None, image: ThumbnailUrl = None,
92
                 media: List[MediaUrl] = None, buttons: List[CardAction] = None,
93
                 shareable: bool = None, autoloop: bool = None,
94
                 autostart: bool = None, aspect: str = None, **kwargs): ...
95

96
class AnimationCard(Model):
97
    def __init__(self, *, title: str = None, subtitle: str = None,
98
                 text: str = None, image: ThumbnailUrl = None,
99
                 media: List[MediaUrl] = None, buttons: List[CardAction] = None,
100
                 shareable: bool = None, autoloop: bool = None,
101
                 autostart: bool = None, **kwargs): ...
102

103
class MediaCard(Model):
104
    def __init__(self, *, title: str = None, subtitle: str = None,
105
                 text: str = None, image: ThumbnailUrl = None,
106
                 media: List[MediaUrl] = None, buttons: List[CardAction] = None,
107
                 shareable: bool = None, autoloop: bool = None, **kwargs):
108
        """
109
        Media card for general media content.
110
        
111
        Parameters:
112
        - title: Title of this card
113
        - subtitle: Subtitle of this card  
114
        - text: Text of this card
115
        - image: Thumbnail placeholder
116
        - media: Media URLs for this card. When this field contains more than
117
          one URL, each URL is an alternative format of the same content.
118
        - buttons: Actions on this card
119
        - shareable: This content may be shared with others (default:true)
120
        - autoloop: Should the client loop playback at end of content (default:true)
121
        """
122
```
123

124
```python
125
from botbuilder.schema import VideoCard, MediaUrl, ThumbnailUrl
126

127
video_card = VideoCard(
128
    title="Demo Video",
129
    subtitle="Bot Framework Tutorial",
130
    media=[MediaUrl(url="https://example.com/video.mp4")],
131
    image=ThumbnailUrl(url="https://example.com/thumbnail.jpg"),
132
    autostart=False,
133
    autoloop=False
134
)
135
```
136

137
### Receipt Card
138

139
Specialized card for displaying purchase receipts with itemized information.
140

141
```python { .api }
142
class ReceiptCard(Model):
143
    def __init__(self, *, title: str = None, facts: List[Fact] = None,
144
                 items: List[ReceiptItem] = None, tap: CardAction = None,
145
                 total: str = None, tax: str = None, vat: str = None,
146
                 buttons: List[CardAction] = None, **kwargs): ...
147

148
class ReceiptItem(Model):
149
    def __init__(self, *, title: str = None, subtitle: str = None,
150
                 text: str = None, image: CardImage = None,
151
                 price: str = None, quantity: str = None,
152
                 tap: CardAction = None, **kwargs): ...
153

154
class Fact(Model):
155
    def __init__(self, *, key: str = None, value: str = None, **kwargs): ...
156
```
157

158
```python
159
from botbuilder.schema import ReceiptCard, ReceiptItem, Fact, CardImage
160

161
receipt = ReceiptCard(
162
    title="Purchase Receipt",
163
    facts=[
164
        Fact(key="Order Number", value="12345"),
165
        Fact(key="Payment Method", value="Credit Card")
166
    ],
167
    items=[
168
        ReceiptItem(
169
            title="Product A",
170
            price="$19.99",
171
            quantity="2",
172
            image=CardImage(url="https://example.com/product-a.jpg")
173
        )
174
    ],
175
    tax="$3.20",
176
    total="$43.18"
177
)
178
```
179

180
### Authentication Cards
181

182
Cards for OAuth and signin flows.
183

184
```python { .api }
185
class SigninCard(Model):
186
    def __init__(self, *, text: str = None, buttons: List[CardAction] = None, **kwargs): ...
187

188
class OAuthCard(Model):
189
    def __init__(self, *, text: str = None, connection_name: str = None,
190
                 buttons: List[CardAction] = None, **kwargs): ...
191
```
192

193
```python
194
from botbuilder.schema import OAuthCard, CardAction
195

196
oauth_card = OAuthCard(
197
    text="Please sign in to continue",
198
    connection_name="MyOAuthConnection",
199
    buttons=[CardAction(type="signin", title="Sign In", value="signin")]
200
)
201
```
202

203
## Card Components
204

205
### Card Actions
206

207
Interactive buttons and actions that users can perform on cards.
208

209
```python { .api }
210
class CardAction(Model):
211
    def __init__(self, *, type: str = None, title: str = None,
212
                 image: str = None, text: str = None, display_text: str = None,
213
                 value = None, channel_data = None, **kwargs): ...
214
```
215

216
**Action Types** (from ActionTypes enum):
217
- `openUrl` - Opens a URL in browser
218
- `imBack` - Sends message back to bot  
219
- `postBack` - Posts data to bot without showing user message
220
- `playAudio` - Plays audio file
221
- `playVideo` - Plays video file
222
- `showImage` - Displays image
223
- `downloadFile` - Downloads file
224
- `signin` - Initiates signin flow
225
- `call` - Makes phone call
226
- `messageBack` - Advanced postback with text and display text
227

228
```python
229
from botbuilder.schema import CardAction
230

231
actions = [
232
    CardAction(type="openUrl", title="Visit Website", value="https://example.com"),
233
    CardAction(type="imBack", title="Say Hello", value="hello"),
234
    CardAction(type="postBack", title="Submit", value={"action": "submit", "data": "form_data"})
235
]
236
```
237

238
### Card Images
239

240
Images displayed on cards with optional tap actions.
241

242
```python { .api }
243
class CardImage(Model):
244
    def __init__(self, *, url: str = None, alt: str = None,
245
                 tap: CardAction = None, **kwargs): ...
246

247
class ThumbnailUrl(Model):
248
    def __init__(self, *, url: str = None, alt: str = None, **kwargs): ...
249

250
class MediaUrl(Model):
251
    def __init__(self, *, url: str = None, profile: str = None, **kwargs): ...
252
```
253

254
```python
255
from botbuilder.schema import CardImage, CardAction
256

257
image = CardImage(
258
    url="https://example.com/image.jpg",
259
    alt="Description of image",
260
    tap=CardAction(type="openUrl", value="https://example.com/details")
261
)
262
```
263

264
### Suggested Actions
265

266
Quick reply buttons that appear below messages.
267

268
```python { .api }
269
class SuggestedActions(Model):
270
    def __init__(self, *, to: List[str] = None, from_property: List[str] = None,
271
                 actions: List[CardAction] = None, **kwargs): ...
272
```
273

274
```python
275
from botbuilder.schema import SuggestedActions, CardAction
276

277
suggested_actions = SuggestedActions(
278
    actions=[
279
        CardAction(type="imBack", title="Yes", value="yes"),
280
        CardAction(type="imBack", title="No", value="no"),
281
        CardAction(type="imBack", title="Maybe", value="maybe")
282
    ]
283
)
284
```
285

286
## Usage Patterns
287

288
### Adding Cards to Activities
289

290
```python
291
from botbuilder.schema import Activity, ActivityTypes, Attachment, HeroCard
292

293
# Create card
294
hero_card = HeroCard(
295
    title="Sample Card",
296
    text="This is a sample hero card"
297
)
298

299
# Create attachment from card
300
attachment = Attachment(
301
    content_type="application/vnd.microsoft.card.hero",
302
    content=hero_card
303
)
304

305
# Add to activity
306
activity = Activity(
307
    type=ActivityTypes.message,
308
    attachments=[attachment]
309
)
310
```
311

312
### Card Collections and Carousels
313

314
```python
315
from botbuilder.schema import AttachmentLayoutTypes
316

317
# Multiple cards in carousel layout
318
activity = Activity(
319
    type=ActivityTypes.message,
320
    attachment_layout=AttachmentLayoutTypes.carousel,
321
    attachments=[attachment1, attachment2, attachment3]
322
)
323

324
# Multiple cards in list layout  
325
activity = Activity(
326
    type=ActivityTypes.message,
327
    attachment_layout=AttachmentLayoutTypes.list,
328
    attachments=[attachment1, attachment2, attachment3]
329
)
330
```
331

332
### Adaptive Cards Integration
333

334
While not part of this schema package, Adaptive Cards can be used with the attachment system:
335

336
```python
337
# Adaptive Cards use a different content type
338
adaptive_attachment = Attachment(
339
    content_type="application/vnd.microsoft.card.adaptive",
340
    content=adaptive_card_json
341
)
342
```
343

344
## Content Types
345

346
Standard content types for card attachments:
347

348
- `application/vnd.microsoft.card.hero` - Hero cards
349
- `application/vnd.microsoft.card.thumbnail` - Thumbnail cards  
350
- `application/vnd.microsoft.card.receipt` - Receipt cards
351
- `application/vnd.microsoft.card.signin` - Signin cards
352
- `application/vnd.microsoft.card.oauth` - OAuth cards
353
- `application/vnd.microsoft.card.audio` - Audio cards
354
- `application/vnd.microsoft.card.video` - Video cards
355
- `application/vnd.microsoft.card.animation` - Animation cards
356
- `application/vnd.microsoft.card.adaptive` - Adaptive cards (external)