0
# Attachment and Media Handling
1

2
File attachment and media management models supporting upload, download, and display of documents, images, audio, and video content across Bot Framework channels.
3

4
## Core Attachment Models
5

6
### Attachment
7

8
The primary model for file attachments that can be sent with activities.
9

10
```python { .api }
11
class Attachment(Model):
12
    def __init__(self, *, content_type: str = None, content_url: str = None,
13
                 content = None, name: str = None, thumbnail_url: str = None, **kwargs): ...
14
```
15

16
**Properties:**
17
- `content_type` - MIME type of the content (e.g., "image/jpeg", "application/pdf")
18
- `content_url` - URL where the content can be downloaded
19
- `content` - Inline content object (for cards and structured data)
20
- `name` - Display name for the attachment
21
- `thumbnail_url` - URL for thumbnail/preview image
22

23
```python
24
from botbuilder.schema import Attachment, Activity, ActivityTypes
25

26
# File attachment with URL
27
file_attachment = Attachment(
28
    content_type="application/pdf",
29
    content_url="https://example.com/document.pdf",
30
    name="User Manual.pdf"
31
)
32

33
# Image attachment with thumbnail
34
image_attachment = Attachment(
35
    content_type="image/jpeg", 
36
    content_url="https://example.com/photo.jpg",
37
    name="Photo.jpg",
38
    thumbnail_url="https://example.com/photo-thumb.jpg"
39
)
40

41
# Send attachments in message
42
message = Activity(
43
    type=ActivityTypes.message,
44
    text="Here are the files you requested:",
45
    attachments=[file_attachment, image_attachment]
46
)
47
```
48

49
### Attachment Data
50

51
Model for uploading attachment content, typically used with file upload APIs.
52

53
```python { .api }
54
class AttachmentData(Model):
55
    def __init__(self, *, type: str = None, name: str = None,
56
                 original_base64: str = None, thumbnail_base64: str = None, **kwargs): ...
57
```
58

59
```python
60
import base64
61
from botbuilder.schema import AttachmentData
62

63
# Prepare file for upload
64
with open("document.pdf", "rb") as file:
65
    file_data = base64.b64encode(file.read()).decode('utf-8')
66

67
attachment_data = AttachmentData(
68
    type="application/pdf",
69
    name="document.pdf", 
70
    original_base64=file_data
71
)
72
```
73

74
### Attachment Info
75

76
Information about an attachment, including available views and formats.
77

78
```python { .api }
79
class AttachmentInfo(Model):
80
    def __init__(self, *, name: str = None, type: str = None,
81
                 views: List[AttachmentView] = None, **kwargs): ...
82

83
class AttachmentView(Model):
84
    def __init__(self, *, view_id: str = None, size: int = None, **kwargs): ...
85
```
86

87
```python
88
from botbuilder.schema import AttachmentInfo, AttachmentView
89

90
attachment_info = AttachmentInfo(
91
    name="presentation.pptx",
92
    type="application/vnd.openxmlformats-officedocument.presentationml.presentation",
93
    views=[
94
        AttachmentView(view_id="original", size=2048576),
95
        AttachmentView(view_id="thumbnail", size=15324)
96
    ]
97
)
98
```
99

100
## Media Models
101

102
### Media URL
103

104
URL references for media content with optional profiles for different quality/formats.
105

106
```python { .api }
107
class MediaUrl(Model):
108
    def __init__(self, *, url: str = None, profile: str = None, **kwargs): ...
109
```
110

111
```python
112
from botbuilder.schema import MediaUrl
113

114
# Multiple quality options for video
115
media_urls = [
116
    MediaUrl(url="https://example.com/video-hd.mp4", profile="high"),
117
    MediaUrl(url="https://example.com/video-sd.mp4", profile="standard"),
118
    MediaUrl(url="https://example.com/video-low.mp4", profile="low")
119
]
120
```
121

122
### Thumbnail URL
123

124
Thumbnail image references with alt text for accessibility.
125

126
```python { .api }
127
class ThumbnailUrl(Model):
128
    def __init__(self, *, url: str = None, alt: str = None, **kwargs): ...
129
```
130

131
```python
132
from botbuilder.schema import ThumbnailUrl
133

134
thumbnail = ThumbnailUrl(
135
    url="https://example.com/video-thumb.jpg",
136
    alt="Video thumbnail showing the main topic"
137
)
138
```
139

140
## Content Types and MIME Types
141

142
### Common Content Types
143

144
**Images:**
145
- `image/jpeg` - JPEG images
146
- `image/png` - PNG images  
147
- `image/gif` - GIF images
148
- `image/svg+xml` - SVG vector graphics
149

150
**Documents:**
151
- `application/pdf` - PDF documents
152
- `application/msword` - Word documents (.doc)
153
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document` - Word documents (.docx)
154
- `application/vnd.ms-excel` - Excel spreadsheets (.xls)
155
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - Excel spreadsheets (.xlsx)
156

157
**Media:**
158
- `audio/mpeg` - MP3 audio
159
- `audio/wav` - WAV audio
160
- `video/mp4` - MP4 video
161
- `video/quicktime` - QuickTime video
162

163
**Archives:**
164
- `application/zip` - ZIP archives
165
- `application/x-rar-compressed` - RAR archives
166

167
```python
168
from botbuilder.schema import Attachment
169

170
# Different content type examples
171
attachments = [
172
    Attachment(
173
        content_type="image/png",
174
        content_url="https://example.com/chart.png",
175
        name="Sales Chart.png"
176
    ),
177
    Attachment(
178
        content_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
179
        content_url="https://example.com/report.docx", 
180
        name="Monthly Report.docx"
181
    ),
182
    Attachment(
183
        content_type="audio/mpeg",
184
        content_url="https://example.com/recording.mp3",
185
        name="Meeting Recording.mp3"
186
    )
187
]
188
```
189

190
## File Upload and Download Patterns
191

192
### Basic File Sharing
193

194
```python
195
from botbuilder.schema import Activity, ActivityTypes, Attachment
196

197
async def share_file(file_url: str, file_name: str, content_type: str):
198
    attachment = Attachment(
199
        content_type=content_type,
200
        content_url=file_url,
201
        name=file_name
202
    )
203
    
204
    return Activity(
205
        type=ActivityTypes.message,
206
        text=f"Here's the file: {file_name}",
207
        attachments=[attachment]
208
    )
209
```
210

211
### Multiple File Attachments
212

213
```python
214
from botbuilder.schema import Activity, ActivityTypes, AttachmentLayoutTypes
215

216
def create_file_gallery(file_list):
217
    attachments = []
218
    for file_info in file_list:
219
        attachment = Attachment(
220
            content_type=file_info['content_type'],
221
            content_url=file_info['url'],
222
            name=file_info['name'],
223
            thumbnail_url=file_info.get('thumbnail_url')
224
        )
225
        attachments.append(attachment)
226
    
227
    return Activity(
228
        type=ActivityTypes.message,
229
        text="Here are your files:",
230
        attachments=attachments,
231
        attachment_layout=AttachmentLayoutTypes.list
232
    )
233
```
234

235
## Channel-Specific Considerations
236

237
### Attachment Support by Channel
238

239
Different Bot Framework channels have varying levels of attachment support:
240

241
**Full Support:** Direct Line, Web Chat, Emulator
242
- All attachment types supported
243
- File upload/download workflows
244
- Rich media content
245

246
**Partial Support:** Teams, Slack
247
- Common file types supported
248
- Some restrictions on file sizes
249
- Channel-specific rendering
250

251
**Limited Support:** SMS, Email
252
- Usually converted to links
253
- Text fallbacks required
254

255
### Best Practices
256

257
1. **Always provide fallback text** when sending attachments
258
2. **Check file size limits** for target channels
259
3. **Use appropriate content types** for better rendering
260
4. **Provide thumbnail URLs** for better user experience
261
5. **Include descriptive names** for accessibility
262

263
```python
264
from botbuilder.schema import Activity, ActivityTypes, Attachment
265

266
def create_accessible_attachment(url: str, name: str, content_type: str, description: str):
267
    attachment = Attachment(
268
        content_type=content_type,
269
        content_url=url,
270
        name=name
271
    )
272
    
273
    return Activity(
274
        type=ActivityTypes.message,
275
        text=f"{description}\n\nFile: {name}",  # Fallback text
276
        attachments=[attachment]
277
    )
278
```
279

280
## Error Handling
281

282
```python
283
from botbuilder.schema import Activity, ActivityTypes
284

285
def handle_attachment_error(error_message: str):
286
    return Activity(
287
        type=ActivityTypes.message,
288
        text=f"Sorry, there was an issue with the file attachment: {error_message}. Please try uploading the file again or contact support if the problem persists."
289
    )
290
```
291

292
## Integration with Cards
293

294
Attachments can be combined with rich cards for enhanced presentation:
295

296
```python
297
from botbuilder.schema import (
298
    Activity, ActivityTypes, Attachment, HeroCard, 
299
    CardImage, CardAction, AttachmentLayoutTypes
300
)
301

302
def create_file_card(file_url: str, file_name: str, description: str, thumbnail_url: str = None):
303
    # Create hero card for file presentation
304
    hero_card = HeroCard(
305
        title=file_name,
306
        text=description,
307
        images=[CardImage(url=thumbnail_url)] if thumbnail_url else None,
308
        buttons=[
309
            CardAction(type="openUrl", title="Download", value=file_url),
310
            CardAction(type="openUrl", title="Preview", value=f"{file_url}?preview=true")
311
        ]
312
    )
313
    
314
    card_attachment = Attachment(
315
        content_type="application/vnd.microsoft.card.hero",
316
        content=hero_card
317
    )
318
    
319
    return Activity(
320
        type=ActivityTypes.message,
321
        attachments=[card_attachment]
322
    )
323
```