tessl/pypi-botbuilder-core
Microsoft Bot Framework Bot Builder core functionality for building conversational AI bots and chatbots in Python.
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
message-factories.mddocs/
Message & Card Factories
Factory classes for creating rich message activities and card attachments. Simplifies the creation of formatted responses, cards, and other rich content types supported by the Bot Framework.
Capabilities
MessageFactory
Static factory class that provides convenient methods for creating various types of message activities, including text messages, attachments, suggested actions, and rich content.
class MessageFactory:
@staticmethod
def text(text: str, speak: str = None, input_hint=None):
"""
Create a text message activity.
Args:
text (str): Message text to display
speak (str, optional): Text to speak for voice channels
input_hint (optional): Input hint for the client
Returns:
Activity: Message activity with text
"""
@staticmethod
def suggested_actions(actions, text: str = None, speak: str = None, input_hint=None):
"""
Create a message with suggested actions.
Args:
actions (list): List of CardAction objects or strings
text (str, optional): Message text
speak (str, optional): Text to speak
input_hint (optional): Input hint
Returns:
Activity: Message activity with suggested actions
"""
@staticmethod
def attachment(attachment, text: str = None, speak: str = None, input_hint=None):
"""
Create a message with a single attachment.
Args:
attachment (Attachment): Attachment to include
text (str, optional): Message text
speak (str, optional): Text to speak
input_hint (optional): Input hint
Returns:
Activity: Message activity with attachment
"""
@staticmethod
def list(attachments, text: str = None, speak: str = None, input_hint=None):
"""
Create a message with multiple attachments displayed as a list.
Args:
attachments (list): List of Attachment objects
text (str, optional): Message text
speak (str, optional): Text to speak
input_hint (optional): Input hint
Returns:
Activity: Message activity with attachment list
"""
@staticmethod
def carousel(attachments, text: str = None, speak: str = None, input_hint=None):
"""
Create a message with multiple attachments displayed as a carousel.
Args:
attachments (list): List of Attachment objects
text (str, optional): Message text
speak (str, optional): Text to speak
input_hint (optional): Input hint
Returns:
Activity: Message activity with carousel layout
"""
@staticmethod
def content_url(url: str, content_type: str, name: str = None, text: str = None,
speak: str = None):
"""
Create a message with a content URL attachment.
Args:
url (str): URL to the content
content_type (str): MIME type of the content
name (str, optional): Name of the attachment
text (str, optional): Message text
speak (str, optional): Text to speak
Returns:
Activity: Message activity with content URL
"""CardFactory
Static factory class that provides methods for creating various types of card attachments supported by the Bot Framework, including Hero Cards, Adaptive Cards, and other rich card types.
class CardFactory:
@staticmethod
def adaptive_card(card):
"""
Create an Adaptive Card attachment.
Args:
card (dict or AdaptiveCard): Adaptive Card JSON or object
Returns:
Attachment: Adaptive Card attachment
"""
@staticmethod
def hero_card(title: str, subtitle: str = None, text: str = None, images=None,
buttons=None, tap=None):
"""
Create a Hero Card attachment.
Args:
title (str): Card title
subtitle (str, optional): Card subtitle
text (str, optional): Card text
images (list, optional): List of CardImage objects
buttons (list, optional): List of CardAction objects
tap (CardAction, optional): Tap action
Returns:
Attachment: Hero Card attachment
"""
@staticmethod
def thumbnail_card(title: str, subtitle: str = None, text: str = None, images=None,
buttons=None, tap=None):
"""
Create a Thumbnail Card attachment.
Args:
title (str): Card title
subtitle (str, optional): Card subtitle
text (str, optional): Card text
images (list, optional): List of CardImage objects
buttons (list, optional): List of CardAction objects
tap (CardAction, optional): Tap action
Returns:
Attachment: Thumbnail Card attachment
"""
@staticmethod
def receipt_card(title: str, facts=None, items=None, tap=None, total: str = None,
tax: str = None, vat: str = None, buttons=None):
"""
Create a Receipt Card attachment.
Args:
title (str): Card title
facts (list, optional): List of Fact objects
items (list, optional): List of ReceiptItem objects
tap (CardAction, optional): Tap action
total (str, optional): Total amount
tax (str, optional): Tax amount
vat (str, optional): VAT amount
buttons (list, optional): List of CardAction objects
Returns:
Attachment: Receipt Card attachment
"""
@staticmethod
def signin_card(text: str, url: str):
"""
Create a Sign-in Card attachment.
Args:
text (str): Sign-in prompt text
url (str): Sign-in URL
Returns:
Attachment: Sign-in Card attachment
"""
@staticmethod
def oauth_card(connection_name: str, title: str, text: str = None, url: str = None):
"""
Create an OAuth Card attachment.
Args:
connection_name (str): OAuth connection name
title (str): Card title
text (str, optional): Card text
url (str, optional): Sign-in URL
Returns:
Attachment: OAuth Card attachment
"""
@staticmethod
def animation_card(title: str, subtitle: str = None, text: str = None, image=None,
media=None, buttons=None, shareable: bool = None,
autoloop: bool = None, autostart: bool = None, aspect: str = None):
"""
Create an Animation Card attachment.
Args:
title (str): Card title
subtitle (str, optional): Card subtitle
text (str, optional): Card text
image (CardImage, optional): Thumbnail image
media (list, optional): List of MediaUrl objects
buttons (list, optional): List of CardAction objects
shareable (bool, optional): Whether card is shareable
autoloop (bool, optional): Whether to autoloop
autostart (bool, optional): Whether to autostart
aspect (str, optional): Aspect ratio
Returns:
Attachment: Animation Card attachment
"""
@staticmethod
def audio_card(title: str, subtitle: str = None, text: str = None, image=None,
media=None, buttons=None, shareable: bool = None,
autoloop: bool = None, autostart: bool = None):
"""
Create an Audio Card attachment.
Args:
title (str): Card title
subtitle (str, optional): Card subtitle
text (str, optional): Card text
image (CardImage, optional): Thumbnail image
media (list, optional): List of MediaUrl objects
buttons (list, optional): List of CardAction objects
shareable (bool, optional): Whether card is shareable
autoloop (bool, optional): Whether to autoloop
autostart (bool, optional): Whether to autostart
Returns:
Attachment: Audio Card attachment
"""
@staticmethod
def video_card(title: str, subtitle: str = None, text: str = None, image=None,
media=None, buttons=None, shareable: bool = None,
autoloop: bool = None, autostart: bool = None, aspect: str = None):
"""
Create a Video Card attachment.
Args:
title (str): Card title
subtitle (str, optional): Card subtitle
text (str, optional): Card text
image (CardImage, optional): Thumbnail image
media (list, optional): List of MediaUrl objects
buttons (list, optional): List of CardAction objects
shareable (bool, optional): Whether card is shareable
autoloop (bool, optional): Whether to autoloop
autostart (bool, optional): Whether to autostart
aspect (str, optional): Aspect ratio
Returns:
Attachment: Video Card attachment
"""
@staticmethod
def actions(actions):
"""
Create card actions from a list.
Args:
actions (list): List of action dictionaries or CardAction objects
Returns:
list: List of CardAction objects
"""
@staticmethod
def images(images):
"""
Create card images from a list.
Args:
images (list): List of image URLs or CardImage objects
Returns:
list: List of CardImage objects
"""
@staticmethod
def media(media):
"""
Create media URLs from a list.
Args:
media (list): List of media URLs or profile objects
Returns:
list: List of MediaUrl objects
"""Usage Examples
Basic Text Messages
from botbuilder.core import MessageFactory, TurnContext
async def on_message_activity(self, turn_context: TurnContext):
# Simple text message
reply = MessageFactory.text("Hello! How can I help you today?")
await turn_context.send_activity(reply)
# Text with speech for voice channels
reply_with_speech = MessageFactory.text(
text="Welcome to our service!",
speak="Welcome to our service! How may I assist you today?"
)
await turn_context.send_activity(reply_with_speech)Suggested Actions
async def show_options(self, turn_context: TurnContext):
# Create suggested actions
suggested_actions = [
"View Menu",
"Place Order",
"Contact Support",
"About Us"
]
reply = MessageFactory.suggested_actions(
actions=suggested_actions,
text="What would you like to do?"
)
await turn_context.send_activity(reply)Hero Card Example
from botbuilder.core import CardFactory, MessageFactory
async def show_product_card(self, turn_context: TurnContext):
# Create hero card
card = CardFactory.hero_card(
title="Premium Coffee Blend",
subtitle="Artisan roasted beans",
text="A perfect blend of Colombian and Ethiopian beans, carefully roasted to perfection.",
images=[CardFactory.images(["https://example.com/coffee.jpg"])],
buttons=[
{"type": "imBack", "title": "Buy Now", "value": "buy premium coffee"},
{"type": "openUrl", "title": "Learn More", "value": "https://example.com/coffee"},
{"type": "postBack", "title": "Add to Cart", "value": "add_to_cart:premium_coffee"}
]
)
reply = MessageFactory.attachment(card)
await turn_context.send_activity(reply)Adaptive Card Example
async def show_adaptive_card(self, turn_context: TurnContext):
# Define Adaptive Card JSON
card_json = {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.2",
"body": [
{
"type": "TextBlock",
"text": "Feedback Form",
"weight": "Bolder",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Please rate your experience:"
},
{
"type": "Input.ChoiceSet",
"id": "rating",
"style": "compact",
"choices": [
{"title": "Excellent", "value": "5"},
{"title": "Good", "value": "4"},
{"title": "Average", "value": "3"},
{"title": "Poor", "value": "2"},
{"title": "Very Poor", "value": "1"}
]
},
{
"type": "Input.Text",
"id": "comments",
"placeholder": "Additional comments",
"isMultiline": True
}
],
"actions": [
{
"type": "Action.Submit",
"title": "Submit Feedback",
"data": {"action": "submit_feedback"}
}
]
}
# Create adaptive card attachment
card = CardFactory.adaptive_card(card_json)
reply = MessageFactory.attachment(card)
await turn_context.send_activity(reply)Carousel of Cards
async def show_product_carousel(self, turn_context: TurnContext):
products = [
{
"title": "Espresso Blend",
"subtitle": "Bold and rich",
"image": "https://example.com/espresso.jpg",
"price": "$12.99"
},
{
"title": "Medium Roast",
"subtitle": "Smooth and balanced",
"image": "https://example.com/medium.jpg",
"price": "$10.99"
},
{
"title": "Dark Roast",
"subtitle": "Strong and intense",
"image": "https://example.com/dark.jpg",
"price": "$11.99"
}
]
# Create cards for each product
attachments = []
for product in products:
card = CardFactory.hero_card(
title=product["title"],
subtitle=product["subtitle"],
text=f"Price: {product['price']}",
images=[product["image"]],
buttons=[
{"type": "imBack", "title": "Buy", "value": f"buy {product['title']}"},
{"type": "imBack", "title": "Details", "value": f"details {product['title']}"}
]
)
attachments.append(card)
# Create carousel message
reply = MessageFactory.carousel(attachments, "Choose your favorite coffee:")
await turn_context.send_activity(reply)Receipt Card Example
async def show_receipt(self, turn_context: TurnContext, order_details):
# Create receipt card
card = CardFactory.receipt_card(
title="Order Confirmation",
facts=[
{"key": "Order Number", "value": order_details["order_id"]},
{"key": "Payment Method", "value": "Credit Card"},
{"key": "Delivery", "value": "Standard (3-5 days)"}
],
items=[
{
"title": "Premium Coffee Blend",
"subtitle": "1 lb bag",
"text": "Quantity: 2",
"image": {"url": "https://example.com/coffee.jpg"},
"price": "$25.98",
"quantity": "2"
}
],
tax="$2.08",
total="$28.06",
buttons=[
{"type": "openUrl", "title": "Track Order", "value": f"https://example.com/track/{order_details['order_id']}"}
]
)
reply = MessageFactory.attachment(card)
await turn_context.send_activity(reply)File Attachment Example
async def send_file_attachment(self, turn_context: TurnContext):
# Create file attachment
file_attachment = {
"name": "menu.pdf",
"contentType": "application/pdf",
"contentUrl": "https://example.com/files/menu.pdf"
}
reply = MessageFactory.attachment(
attachment=file_attachment,
text="Here's our current menu:"
)
await turn_context.send_activity(reply)OAuth Sign-in Card
async def show_signin_card(self, turn_context: TurnContext):
# Create OAuth card
card = CardFactory.oauth_card(
connection_name="MyOAuthConnection",
title="Please sign in",
text="You need to sign in to access this feature."
)
reply = MessageFactory.attachment(card)
await turn_context.send_activity(reply)Media Cards
async def show_video_card(self, turn_context: TurnContext):
# Create video card
card = CardFactory.video_card(
title="Coffee Brewing Tutorial",
subtitle="Learn the perfect brewing technique",
text="Watch this 5-minute tutorial to master coffee brewing.",
image={"url": "https://example.com/video-thumbnail.jpg"},
media=[{"url": "https://example.com/brewing-tutorial.mp4"}],
buttons=[
{"type": "openUrl", "title": "Full Tutorial", "value": "https://example.com/full-tutorial"}
],
autostart=False,
shareable=True
)
reply = MessageFactory.attachment(card)
await turn_context.send_activity(reply)
async def show_audio_card(self, turn_context: TurnContext):
# Create audio card
card = CardFactory.audio_card(
title="Coffee Shop Ambiance",
subtitle="Relaxing cafe sounds",
text="Enjoy the soothing sounds of a busy coffee shop.",
image={"url": "https://example.com/cafe.jpg"},
media=[{"url": "https://example.com/cafe-sounds.mp3"}],
autoloop=True,
shareable=True
)
reply = MessageFactory.attachment(card)
await turn_context.send_activity(reply)Types
class Attachment:
"""File or card attachment."""
name: str
content_type: str
content: object
content_url: str
thumbnail_url: str
class CardAction:
"""Action button on a card."""
type: str # "imBack", "postBack", "openUrl", "signin", "playAudio", etc.
title: str
value: str
text: str
display_text: str
image: str
class CardImage:
"""Image on a card."""
url: str
alt: str
tap: CardAction
class SuggestedActions:
"""Suggested actions for user input."""
to: list
actions: list
class Fact:
"""Name-value pair for receipt cards."""
key: str
value: str
class ReceiptItem:
"""Item on a receipt card."""
title: str
subtitle: str
text: str
image: CardImage
price: str
quantity: str
tap: CardAction
class MediaUrl:
"""Media URL for media cards."""
url: str
profile: strInstall with Tessl CLI
npx tessl i tessl/pypi-botbuilder-core