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

Rich Card Components

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

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

Card Types

Hero Card

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

class HeroCard(Model):
    def __init__(self, *, title: str = None, subtitle: str = None,
                 text: str = None, images: List[CardImage] = None, 
                 buttons: List[CardAction] = None, tap: CardAction = None, **kwargs): ...

from botbuilder.schema import HeroCard, CardImage, CardAction

hero_card = HeroCard(
    title="Welcome Card",
    subtitle="Getting Started Guide", 
    text="This card helps you get started with the bot.",
    images=[CardImage(url="https://example.com/image.jpg")],
    buttons=[
        CardAction(type="openUrl", title="Learn More", value="https://docs.microsoft.com"),
        CardAction(type="imBack", title="Get Help", value="help")
    ]
)

Thumbnail Card

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

class ThumbnailCard(Model):
    def __init__(self, *, title: str = None, subtitle: str = None,
                 text: str = None, images: List[CardImage] = None,
                 buttons: List[CardAction] = None, tap: CardAction = None, **kwargs): ...

Basic Card

A simple card with basic content and optional interactive elements.

class BasicCard(Model):
    def __init__(self, *, title: str = None, subtitle: str = None,
                 text: str = None, images: List[CardImage] = None,
                 buttons: List[CardAction] = None, tap: CardAction = None, **kwargs):
        """
        A basic card.
        
        Parameters:
        - title: Title of the card
        - subtitle: Subtitle of the card
        - text: Text for the card
        - images: Array of images for the card
        - buttons: Set of actions applicable to the current card
        - tap: This action will be activated when user taps on the card itself
        """

from botbuilder.schema import BasicCard, CardAction, CardImage

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

Media Cards

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

class AudioCard(Model):
    def __init__(self, *, title: str = None, subtitle: str = None,
                 text: str = None, image: ThumbnailUrl = None,
                 media: List[MediaUrl] = None, buttons: List[CardAction] = None,
                 shareable: bool = None, autoloop: bool = None,
                 autostart: bool = None, aspect: str = None, **kwargs): ...

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

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

class MediaCard(Model):
    def __init__(self, *, title: str = None, subtitle: str = None,
                 text: str = None, image: ThumbnailUrl = None,
                 media: List[MediaUrl] = None, buttons: List[CardAction] = None,
                 shareable: bool = None, autoloop: bool = None, **kwargs):
        """
        Media card for general media content.
        
        Parameters:
        - title: Title of this card
        - subtitle: Subtitle of this card  
        - text: Text of this card
        - image: Thumbnail placeholder
        - media: Media URLs for this card. When this field contains more than
          one URL, each URL is an alternative format of the same content.
        - buttons: Actions on this card
        - shareable: This content may be shared with others (default:true)
        - autoloop: Should the client loop playback at end of content (default:true)
        """

from botbuilder.schema import VideoCard, MediaUrl, ThumbnailUrl

video_card = VideoCard(
    title="Demo Video",
    subtitle="Bot Framework Tutorial",
    media=[MediaUrl(url="https://example.com/video.mp4")],
    image=ThumbnailUrl(url="https://example.com/thumbnail.jpg"),
    autostart=False,
    autoloop=False
)

Receipt Card

Specialized card for displaying purchase receipts with itemized information.

class ReceiptCard(Model):
    def __init__(self, *, title: str = None, facts: List[Fact] = None,
                 items: List[ReceiptItem] = None, tap: CardAction = None,
                 total: str = None, tax: str = None, vat: str = None,
                 buttons: List[CardAction] = None, **kwargs): ...

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

class Fact(Model):
    def __init__(self, *, key: str = None, value: str = None, **kwargs): ...

from botbuilder.schema import ReceiptCard, ReceiptItem, Fact, CardImage

receipt = ReceiptCard(
    title="Purchase Receipt",
    facts=[
        Fact(key="Order Number", value="12345"),
        Fact(key="Payment Method", value="Credit Card")
    ],
    items=[
        ReceiptItem(
            title="Product A",
            price="$19.99",
            quantity="2",
            image=CardImage(url="https://example.com/product-a.jpg")
        )
    ],
    tax="$3.20",
    total="$43.18"
)

Authentication Cards

Cards for OAuth and signin flows.

class SigninCard(Model):
    def __init__(self, *, text: str = None, buttons: List[CardAction] = None, **kwargs): ...

class OAuthCard(Model):
    def __init__(self, *, text: str = None, connection_name: str = None,
                 buttons: List[CardAction] = None, **kwargs): ...

from botbuilder.schema import OAuthCard, CardAction

oauth_card = OAuthCard(
    text="Please sign in to continue",
    connection_name="MyOAuthConnection",
    buttons=[CardAction(type="signin", title="Sign In", value="signin")]
)

Card Components

Card Actions

Interactive buttons and actions that users can perform on cards.

class CardAction(Model):
    def __init__(self, *, type: str = None, title: str = None,
                 image: str = None, text: str = None, display_text: str = None,
                 value = None, channel_data = None, **kwargs): ...

Action Types (from ActionTypes enum):

openUrl - Opens a URL in browser
imBack - Sends message back to bot
postBack - Posts data to bot without showing user message
playAudio - Plays audio file
playVideo - Plays video file
showImage - Displays image
downloadFile - Downloads file
signin - Initiates signin flow
call - Makes phone call
messageBack - Advanced postback with text and display text

from botbuilder.schema import CardAction

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

Card Images

Images displayed on cards with optional tap actions.

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

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

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

from botbuilder.schema import CardImage, CardAction

image = CardImage(
    url="https://example.com/image.jpg",
    alt="Description of image",
    tap=CardAction(type="openUrl", value="https://example.com/details")
)

Suggested Actions

Quick reply buttons that appear below messages.

class SuggestedActions(Model):
    def __init__(self, *, to: List[str] = None, from_property: List[str] = None,
                 actions: List[CardAction] = None, **kwargs): ...

from botbuilder.schema import SuggestedActions, CardAction

suggested_actions = SuggestedActions(
    actions=[
        CardAction(type="imBack", title="Yes", value="yes"),
        CardAction(type="imBack", title="No", value="no"),
        CardAction(type="imBack", title="Maybe", value="maybe")
    ]
)

Usage Patterns

Adding Cards to Activities

from botbuilder.schema import Activity, ActivityTypes, Attachment, HeroCard

# Create card
hero_card = HeroCard(
    title="Sample Card",
    text="This is a sample hero card"
)

# Create attachment from card
attachment = Attachment(
    content_type="application/vnd.microsoft.card.hero",
    content=hero_card
)

# Add to activity
activity = Activity(
    type=ActivityTypes.message,
    attachments=[attachment]
)

Card Collections and Carousels

from botbuilder.schema import AttachmentLayoutTypes

# Multiple cards in carousel layout
activity = Activity(
    type=ActivityTypes.message,
    attachment_layout=AttachmentLayoutTypes.carousel,
    attachments=[attachment1, attachment2, attachment3]
)

# Multiple cards in list layout  
activity = Activity(
    type=ActivityTypes.message,
    attachment_layout=AttachmentLayoutTypes.list,
    attachments=[attachment1, attachment2, attachment3]
)

Adaptive Cards Integration

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

# Adaptive Cards use a different content type
adaptive_attachment = Attachment(
    content_type="application/vnd.microsoft.card.adaptive",
    content=adaptive_card_json
)

Content Types

Standard content types for card attachments:

application/vnd.microsoft.card.hero - Hero cards
application/vnd.microsoft.card.thumbnail - Thumbnail cards
application/vnd.microsoft.card.receipt - Receipt cards
application/vnd.microsoft.card.signin - Signin cards
application/vnd.microsoft.card.oauth - OAuth cards
application/vnd.microsoft.card.audio - Audio cards
application/vnd.microsoft.card.video - Video cards
application/vnd.microsoft.card.animation - Animation cards
application/vnd.microsoft.card.adaptive - Adaptive cards (external)

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

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

Rich Card Components

Card Types

Hero Card

Thumbnail Card

Basic Card

Media Cards

Receipt Card

Authentication Cards

Card Components

Card Actions

Card Images

Suggested Actions

Usage Patterns

Adding Cards to Activities

Card Collections and Carousels

Adaptive Cards Integration

Content Types

rich-cards.mddocs/