CtrlK
BlogDocsLog inGet started
Tessl Logo

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

activity-types-enums.mddocs/

Activity Types and Enums

Comprehensive enumeration types defining activity types, role types, input hints, action types, and other standardized values used throughout the Bot Framework for consistent communication and behavior.

Core Activity Types

ActivityTypes Enum

Defines the type of activity being sent or received in Bot Framework conversations.

class ActivityTypes(str, Enum):
    message = "message"
    conversation_update = "conversationUpdate"
    typing = "typing"
    end_of_conversation = "endOfConversation"
    event = "event"
    invoke = "invoke"
    invoke_response = "invokeResponse"
    delete_user_data = "deleteUserData"
    message_update = "messageUpdate"
    message_delete = "messageDelete"
    installation_update = "installationUpdate"
    message_reaction = "messageReaction"
    suggestion = "suggestion"
    trace = "trace"
    handoff = "handoff"
    command = "command"
    command_result = "commandResult"
    contact_relation_update = "contactRelationUpdate"

Common Activity Types:

from botbuilder.schema import ActivityTypes, Activity

# Text message from user to bot
message_activity = Activity(
    type=ActivityTypes.message,
    text="Hello bot!"
)

# Bot typing indicator
typing_activity = Activity(
    type=ActivityTypes.typing
)

# User joined conversation
conversation_update = Activity(
    type=ActivityTypes.conversation_update,
    members_added=[channel_account]
)

# End conversation
end_conversation = Activity(
    type=ActivityTypes.end_of_conversation,
    code="userCancelled"
)

Role Types

Identifies the role of the participant in the conversation.

class RoleTypes(str, Enum):
    user = "user"
    bot = "bot"
    skill = "skill"
from botbuilder.schema import RoleTypes, ChannelAccount

user_account = ChannelAccount(
    id="user123",
    name="John Doe",
    role=RoleTypes.user
)

bot_account = ChannelAccount(
    id="bot456", 
    name="My Bot",
    role=RoleTypes.bot
)

Message and Text Formatting

Text Format Types

Specifies the format of text content in messages.

class TextFormatTypes(str, Enum):
    markdown = "markdown"
    plain = "plain"
    xml = "xml"
from botbuilder.schema import Activity, ActivityTypes, TextFormatTypes

# Plain text message
plain_message = Activity(
    type=ActivityTypes.message,
    text="This is plain text",
    text_format=TextFormatTypes.plain
)

# Markdown formatted message
markdown_message = Activity(
    type=ActivityTypes.message,
    text="**Bold text** and *italic text*",
    text_format=TextFormatTypes.markdown
)

# SSML for speech
speech_message = Activity(
    type=ActivityTypes.message,
    text="Hello there!",
    speak="<speak>Hello <emphasis level='strong'>there</emphasis>!</speak>",
    text_format=TextFormatTypes.xml
)

Input Hints

Provides hints about whether the bot is expecting input from the user.

class InputHints(str, Enum):
    accepting_input = "acceptingInput"
    ignoring_input = "ignoringInput"
    expecting_input = "expectingInput"
from botbuilder.schema import Activity, ActivityTypes, InputHints

# Bot is expecting a response
question = Activity(
    type=ActivityTypes.message,
    text="What's your name?",
    input_hint=InputHints.expecting_input
)

# Bot is not expecting input (informational message)
info = Activity(
    type=ActivityTypes.message,
    text="Processing your request...",
    input_hint=InputHints.ignoring_input
)

# Bot can accept input but doesn't require it
optional = Activity(
    type=ActivityTypes.message,
    text="I'm here if you need help!",
    input_hint=InputHints.accepting_input
)

Action and Interaction Types

Action Types

Defines types of actions that can be performed with buttons and cards.

class ActionTypes(str, Enum):
    open_url = "openUrl"
    im_back = "imBack"
    post_back = "postBack"
    play_audio = "playAudio"
    play_video = "playVideo"
    show_image = "showImage"
    download_file = "downloadFile"
    signin = "signin"
    call = "call"
    message_back = "messageBack"
from botbuilder.schema import CardAction, ActionTypes

actions = [
    CardAction(type=ActionTypes.open_url, title="Visit Website", value="https://example.com"),
    CardAction(type=ActionTypes.im_back, title="Say Hello", value="hello"),
    CardAction(type=ActionTypes.post_back, title="Submit", value="submit_data"),
    CardAction(type=ActionTypes.signin, title="Sign In", value="signin_url"),
    CardAction(type=ActionTypes.call, title="Call Support", value="tel:+1234567890")
]

Message Reaction Types

Types of reactions that can be applied to messages.

class MessageReactionTypes(str, Enum):
    like = "like"
    plus_one = "+1"
from botbuilder.schema import MessageReaction, MessageReactionTypes

reactions = [
    MessageReaction(type=MessageReactionTypes.like),
    MessageReaction(type=MessageReactionTypes.plus_one)
]

Layout and Presentation

Attachment Layout Types

Specifies how multiple attachments should be displayed.

class AttachmentLayoutTypes(str, Enum):
    list = "list"
    carousel = "carousel"
from botbuilder.schema import Activity, ActivityTypes, AttachmentLayoutTypes

# Cards displayed in a carousel
carousel_activity = Activity(
    type=ActivityTypes.message,
    attachment_layout=AttachmentLayoutTypes.carousel,
    attachments=[card1, card2, card3]
)

# Cards displayed in a vertical list
list_activity = Activity(
    type=ActivityTypes.message,
    attachment_layout=AttachmentLayoutTypes.list,
    attachments=[card1, card2, card3]
)

Activity Importance

Indicates the importance level of an activity.

class ActivityImportance(str, Enum):
    low = "low"
    normal = "normal"
    high = "high"
from botbuilder.schema import Activity, ActivityTypes, ActivityImportance

# High priority alert
alert = Activity(
    type=ActivityTypes.message,
    text="URGENT: System maintenance in 5 minutes",
    importance=ActivityImportance.high
)

# Low priority informational message
info = Activity(
    type=ActivityTypes.message,
    text="Tip: You can ask me for help anytime",
    importance=ActivityImportance.low
)

Conversation Control

End of Conversation Codes

Codes indicating why a conversation ended.

class EndOfConversationCodes(str, Enum):
    unknown = "unknown"
    completed_successfully = "completedSuccessfully"
    user_cancelled = "userCancelled"
    bot_timed_out = "botTimedOut"
    bot_issued_invalid_message = "botIssuedInvalidMessage"
    channel_failed = "channelFailed"
from botbuilder.schema import Activity, ActivityTypes, EndOfConversationCodes

# Successful completion
success_end = Activity(
    type=ActivityTypes.end_of_conversation,
    code=EndOfConversationCodes.completed_successfully,
    text="Task completed successfully!"
)

# User cancelled
cancelled_end = Activity(
    type=ActivityTypes.end_of_conversation,
    code=EndOfConversationCodes.user_cancelled,
    text="Operation cancelled by user"
)

Delivery Modes

Specifies how activities should be delivered.

class DeliveryModes(str, Enum):
    normal = "normal"
    notification = "notification"
    expect_replies = "expectReplies"
    ephemeral = "ephemeral"
from botbuilder.schema import Activity, ActivityTypes, DeliveryModes

# Push notification
notification = Activity(
    type=ActivityTypes.message,
    text="You have a new message",
    delivery_mode=DeliveryModes.notification
)

# Ephemeral message (not stored in history)
temp_message = Activity(
    type=ActivityTypes.message,
    text="This message will disappear",
    delivery_mode=DeliveryModes.ephemeral
)

Update and Installation Events

Contact Relation Update Action Types

Actions for contact relationship changes.

class ContactRelationUpdateActionTypes(str, Enum):
    add = "add"
    remove = "remove"
from botbuilder.schema import Activity, ActivityTypes, ContactRelationUpdateActionTypes

contact_added = Activity(
    type=ActivityTypes.contact_relation_update,
    action=ContactRelationUpdateActionTypes.add,
    from_property=channel_account
)

Installation Update Action Types

Actions for bot installation changes.

class InstallationUpdateActionTypes(str, Enum):
    add = "add"
    remove = "remove"
from botbuilder.schema import Activity, ActivityTypes, InstallationUpdateActionTypes

bot_installed = Activity(
    type=ActivityTypes.installation_update,
    action=InstallationUpdateActionTypes.add
)

bot_removed = Activity(
    type=ActivityTypes.installation_update,
    action=InstallationUpdateActionTypes.remove
)

Semantic Actions

Semantic Action States

States for programmatic actions.

class SemanticActionStates(str, Enum):
    start = "start"
    continue = "continue"
    done = "done"
from botbuilder.schema import SemanticAction, SemanticActionStates

action = SemanticAction(
    id="booking_action",
    state=SemanticActionStates.start,
    entities={"date": "2023-12-25", "guests": 4}
)

Activity Event Names

Standard Event Names

Predefined event names for system activities.

class ActivityEventNames(str, Enum):
    continue_conversation = "ContinueConversation"
    create_conversation = "CreateConversation"
from botbuilder.schema import Activity, ActivityTypes, ActivityEventNames

continue_event = Activity(
    type=ActivityTypes.event,
    name=ActivityEventNames.continue_conversation
)

Usage Patterns

Activity Type Detection

from botbuilder.schema import ActivityTypes

def handle_activity(activity):
    """Route activity based on type"""
    if activity.type == ActivityTypes.message:
        return handle_message(activity)
    elif activity.type == ActivityTypes.conversation_update:
        return handle_members_added(activity)
    elif activity.type == ActivityTypes.typing:
        return handle_typing(activity)
    elif activity.type == ActivityTypes.end_of_conversation:
        return handle_conversation_end(activity)
    else:
        return handle_unknown_activity(activity)

Enum Validation

from botbuilder.schema import ActivityTypes, RoleTypes

def validate_activity(activity):
    """Validate activity has proper enum values"""
    valid_types = [t.value for t in ActivityTypes]
    if activity.type not in valid_types:
        raise ValueError(f"Invalid activity type: {activity.type}")
    
    if activity.from_property and activity.from_property.role:
        valid_roles = [r.value for r in RoleTypes]
        if activity.from_property.role not in valid_roles:
            raise ValueError(f"Invalid role type: {activity.from_property.role}")

Conditional Responses

from botbuilder.schema import InputHints, TextFormatTypes

def create_response(text: str, expects_input: bool = False, use_markdown: bool = False):
    """Create activity with appropriate hints and formatting"""
    return Activity(
        type=ActivityTypes.message,
        text=text,
        text_format=TextFormatTypes.markdown if use_markdown else TextFormatTypes.plain,
        input_hint=InputHints.expecting_input if expects_input else InputHints.accepting_input
    )

Constants Integration

The enums work together with constants classes for complete Bot Framework integration:

from botbuilder.schema import (
    ActivityTypes, SignInConstants, CallerIdConstants,
    SpeechConstants
)

# Event handling with constants
if activity.type == ActivityTypes.event:
    if activity.name == SignInConstants.token_response_event_name:
        # Handle token response
        pass
    elif activity.name == SignInConstants.verify_state_operation_name:
        # Handle state verification
        pass

# Channel identification
if caller_id == CallerIdConstants.public_azure_channel:
    # Handle Azure channel specific logic
    pass

# Speech handling
if not activity.speak:
    activity.speak = SpeechConstants.EMPTY_SPEAK_TAG

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

core-activity.md

entities-semantic.md

index.md

rich-cards.md

teams-integration.md

tile.json