tessl/pypi-botbuilder-schema

BotBuilder-schema contains the serialized data sent across the wire between user and bot when using Bot Framework

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Attachment and Media Handling

Name: tessl/pypi-botbuilder-schema
Author: tessl

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

Core Attachment Models

Attachment

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

class Attachment(Model):
    def __init__(self, *, content_type: str = None, content_url: str = None,
                 content = None, name: str = None, thumbnail_url: str = None, **kwargs): ...

Properties:

content_type - MIME type of the content (e.g., "image/jpeg", "application/pdf")
content_url - URL where the content can be downloaded
content - Inline content object (for cards and structured data)
name - Display name for the attachment
thumbnail_url - URL for thumbnail/preview image

from botbuilder.schema import Attachment, Activity, ActivityTypes

# File attachment with URL
file_attachment = Attachment(
    content_type="application/pdf",
    content_url="https://example.com/document.pdf",
    name="User Manual.pdf"
)

# Image attachment with thumbnail
image_attachment = Attachment(
    content_type="image/jpeg", 
    content_url="https://example.com/photo.jpg",
    name="Photo.jpg",
    thumbnail_url="https://example.com/photo-thumb.jpg"
)

# Send attachments in message
message = Activity(
    type=ActivityTypes.message,
    text="Here are the files you requested:",
    attachments=[file_attachment, image_attachment]
)

Attachment Data

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

class AttachmentData(Model):
    def __init__(self, *, type: str = None, name: str = None,
                 original_base64: str = None, thumbnail_base64: str = None, **kwargs): ...

import base64
from botbuilder.schema import AttachmentData

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

attachment_data = AttachmentData(
    type="application/pdf",
    name="document.pdf", 
    original_base64=file_data
)

Attachment Info

Information about an attachment, including available views and formats.

class AttachmentInfo(Model):
    def __init__(self, *, name: str = None, type: str = None,
                 views: List[AttachmentView] = None, **kwargs): ...

class AttachmentView(Model):
    def __init__(self, *, view_id: str = None, size: int = None, **kwargs): ...

from botbuilder.schema import AttachmentInfo, AttachmentView

attachment_info = AttachmentInfo(
    name="presentation.pptx",
    type="application/vnd.openxmlformats-officedocument.presentationml.presentation",
    views=[
        AttachmentView(view_id="original", size=2048576),
        AttachmentView(view_id="thumbnail", size=15324)
    ]
)

Media Models

Media URL

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

class MediaUrl(Model):
    def __init__(self, *, url: str = None, profile: str = None, **kwargs): ...

from botbuilder.schema import MediaUrl

# Multiple quality options for video
media_urls = [
    MediaUrl(url="https://example.com/video-hd.mp4", profile="high"),
    MediaUrl(url="https://example.com/video-sd.mp4", profile="standard"),
    MediaUrl(url="https://example.com/video-low.mp4", profile="low")
]

Thumbnail URL

Thumbnail image references with alt text for accessibility.

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

from botbuilder.schema import ThumbnailUrl

thumbnail = ThumbnailUrl(
    url="https://example.com/video-thumb.jpg",
    alt="Video thumbnail showing the main topic"
)

Content Types and MIME Types

Common Content Types

Images:

image/jpeg - JPEG images
image/png - PNG images
image/gif - GIF images
image/svg+xml - SVG vector graphics

Documents:

application/pdf - PDF documents
application/msword - Word documents (.doc)
application/vnd.openxmlformats-officedocument.wordprocessingml.document - Word documents (.docx)
application/vnd.ms-excel - Excel spreadsheets (.xls)
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - Excel spreadsheets (.xlsx)

Media:

audio/mpeg - MP3 audio
audio/wav - WAV audio
video/mp4 - MP4 video
video/quicktime - QuickTime video

Archives:

application/zip - ZIP archives
application/x-rar-compressed - RAR archives

from botbuilder.schema import Attachment

# Different content type examples
attachments = [
    Attachment(
        content_type="image/png",
        content_url="https://example.com/chart.png",
        name="Sales Chart.png"
    ),
    Attachment(
        content_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        content_url="https://example.com/report.docx", 
        name="Monthly Report.docx"
    ),
    Attachment(
        content_type="audio/mpeg",
        content_url="https://example.com/recording.mp3",
        name="Meeting Recording.mp3"
    )
]

File Upload and Download Patterns

Basic File Sharing

from botbuilder.schema import Activity, ActivityTypes, Attachment

async def share_file(file_url: str, file_name: str, content_type: str):
    attachment = Attachment(
        content_type=content_type,
        content_url=file_url,
        name=file_name
    )
    
    return Activity(
        type=ActivityTypes.message,
        text=f"Here's the file: {file_name}",
        attachments=[attachment]
    )

Multiple File Attachments

from botbuilder.schema import Activity, ActivityTypes, AttachmentLayoutTypes

def create_file_gallery(file_list):
    attachments = []
    for file_info in file_list:
        attachment = Attachment(
            content_type=file_info['content_type'],
            content_url=file_info['url'],
            name=file_info['name'],
            thumbnail_url=file_info.get('thumbnail_url')
        )
        attachments.append(attachment)
    
    return Activity(
        type=ActivityTypes.message,
        text="Here are your files:",
        attachments=attachments,
        attachment_layout=AttachmentLayoutTypes.list
    )

Channel-Specific Considerations

Attachment Support by Channel

Different Bot Framework channels have varying levels of attachment support:

Full Support: Direct Line, Web Chat, Emulator

All attachment types supported
File upload/download workflows
Rich media content

Partial Support: Teams, Slack

Common file types supported
Some restrictions on file sizes
Channel-specific rendering

Limited Support: SMS, Email

Usually converted to links
Text fallbacks required

Best Practices

Always provide fallback text when sending attachments
Check file size limits for target channels
Use appropriate content types for better rendering
Provide thumbnail URLs for better user experience
Include descriptive names for accessibility

from botbuilder.schema import Activity, ActivityTypes, Attachment

def create_accessible_attachment(url: str, name: str, content_type: str, description: str):
    attachment = Attachment(
        content_type=content_type,
        content_url=url,
        name=name
    )
    
    return Activity(
        type=ActivityTypes.message,
        text=f"{description}\n\nFile: {name}",  # Fallback text
        attachments=[attachment]
    )

Error Handling

from botbuilder.schema import Activity, ActivityTypes

def handle_attachment_error(error_message: str):
    return Activity(
        type=ActivityTypes.message,
        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."
    )

Integration with Cards

Attachments can be combined with rich cards for enhanced presentation:

from botbuilder.schema import (
    Activity, ActivityTypes, Attachment, HeroCard, 
    CardImage, CardAction, AttachmentLayoutTypes
)

def create_file_card(file_url: str, file_name: str, description: str, thumbnail_url: str = None):
    # Create hero card for file presentation
    hero_card = HeroCard(
        title=file_name,
        text=description,
        images=[CardImage(url=thumbnail_url)] if thumbnail_url else None,
        buttons=[
            CardAction(type="openUrl", title="Download", value=file_url),
            CardAction(type="openUrl", title="Preview", value=f"{file_url}?preview=true")
        ]
    )
    
    card_attachment = Attachment(
        content_type="application/vnd.microsoft.card.hero",
        content=hero_card
    )
    
    return Activity(
        type=ActivityTypes.message,
        attachments=[card_attachment]
    )

Install with Tessl CLI

npx tessl i tessl/pypi-botbuilder-schema

docs

activity-types-enums.md

attachments-media.md

authentication-oauth.md

channel-conversation.md

tessl/pypi-botbuilder-schema

attachments-media.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Attachment and Media Handling

Core Attachment Models

Attachment

Attachment Data

Attachment Info

Media Models

Media URL

Thumbnail URL

Content Types and MIME Types

Common Content Types

File Upload and Download Patterns

Basic File Sharing

Multiple File Attachments

Channel-Specific Considerations

Attachment Support by Channel

Best Practices

Error Handling

Integration with Cards

attachments-media.mddocs/