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
core-activity.mddocs/
Core Activity Management
The foundational Activity model and supporting types that enable communication between bots and users across all Bot Framework channels. The Activity class serves as the central communication primitive containing all message types, events, and conversation updates.
Capabilities
Activity Class
The Activity class is the basic communication type for the Bot Framework 3.0 protocol, handling all types of messages, events, and conversation updates with comprehensive properties and methods.
class Activity(Model):
def __init__(self, *,
type: str = None,
id: str = None,
timestamp: datetime = None,
local_timestamp: datetime = None,
local_timezone: str = None,
service_url: str = None,
channel_id: str = None,
from_property = None, # ChannelAccount
conversation = None, # ConversationAccount
recipient = None, # ChannelAccount
text_format: str = None,
attachment_layout: str = None,
members_added: List = None,
members_removed: List = None,
reactions_added: List = None,
reactions_removed: List = None,
topic_name: str = None,
history_disclosed: bool = None,
locale: str = None,
text: str = None,
speak: str = None,
input_hint: str = None,
summary: str = None,
suggested_actions = None, # SuggestedActions
attachments: List = None,
entities: List = None,
channel_data = None,
action: str = None,
reply_to_id: str = None,
label: str = None,
value_type: str = None,
value = None,
name: str = None,
relates_to = None, # ConversationReference
code: str = None,
expiration: datetime = None,
importance: str = None,
delivery_mode: str = None,
listen_for: List[str] = None,
text_highlights: List = None,
semantic_action = None, # SemanticAction
caller_id: str = None,
**kwargs):
"""
An Activity is the basic communication type for the Bot Framework 3.0 protocol.
Parameters:
- type: Activity type (message, conversationUpdate, typing, etc.)
- id: Unique identifier for the activity on the channel
- timestamp: UTC timestamp when message was sent (ISO-8601)
- local_timestamp: Local timestamp (ISO-8601)
- local_timezone: IANA timezone name
- service_url: Channel's service endpoint URL
- channel_id: Unique channel identifier
- from_property: Sender of the message (ChannelAccount)
- conversation: Conversation this activity belongs to (ConversationAccount)
- recipient: Recipient of the message (ChannelAccount)
- text_format: Format of text fields (markdown, plain, xml)
- attachment_layout: Layout hint for multiple attachments (list, carousel)
- members_added: Members added to conversation (List[ChannelAccount])
- members_removed: Members removed from conversation (List[ChannelAccount])
- reactions_added: Reactions added (List[MessageReaction])
- reactions_removed: Reactions removed (List[MessageReaction])
- topic_name: Updated topic name of conversation
- history_disclosed: Whether prior history is disclosed
- locale: Locale name for text field contents (BCP-47)
- text: Text content of the message
- speak: Text to speak (SSML)
- input_hint: Bot's input expectation (accepting, ignoring, expecting)
- summary: Text to display if channel cannot render cards
- suggested_actions: Suggested actions for the activity
- attachments: File attachments (List[Attachment])
- entities: Entities mentioned in message (List[Entity])
- channel_data: Channel-specific content
- action: Contact relation update action (add/remove)
- reply_to_id: ID of message this is replying to
- label: Descriptive label for activity
- value_type: Type of activity's value object
- value: Value associated with activity
- name: Operation name for invoke/event activities
- relates_to: Reference to another conversation/activity
- code: End of conversation code
- expiration: When activity should expire
- importance: Activity importance (low, normal, high)
- delivery_mode: Delivery hint (normal, notification, expectReplies, ephemeral)
- listen_for: Phrases for speech/language priming
- text_highlights: Text fragments to highlight
- semantic_action: Programmatic action accompanying request
- caller_id: IRI identifying the caller of a bot
"""Activity Reply and Reference Methods
Methods for creating replies and managing conversation references.
def create_reply(self, text: str = None) -> 'Activity':
"""
Create a reply message activity to this activity.
Parameters:
- text: Reply text content
Returns:
New Activity configured as a reply with swapped from/recipient
"""
def apply_conversation_reference(self, reference: 'ConversationReference',
is_incoming: bool = False) -> 'Activity':
"""
Updates this activity with delivery information from conversation reference.
Parameters:
- reference: Conversation reference with delivery info
- is_incoming: Whether this is an incoming activity
Returns:
Updated activity with conversation reference applied
"""
def get_conversation_reference(self) -> 'ConversationReference':
"""
Create a ConversationReference based on this Activity.
Returns:
ConversationReference with activity's conversation info
"""
def get_reply_conversation_reference(self) -> 'ConversationReference':
"""
Create a ConversationReference for replies with swapped bot/user.
Returns:
ConversationReference configured for creating replies
"""Activity Content and Validation Methods
Methods for checking activity content and validation.
def has_content(self) -> bool:
"""
Check if activity has any content to send.
Returns:
True if activity has text, attachments, or suggested actions
"""
def is_from_streaming_connection(self) -> bool:
"""
Determine if activity is from a streaming connection.
Returns:
True if from streaming connection, False otherwise
"""
def get_mentions(self) -> List['Mention']:
"""
Get all Mention entities from this activity.
Returns:
List of Mention entities found in activity.entities
"""Activity Type Conversion Methods
Methods that return typed activity objects or None if the activity is not of the specified type.
def as_message_activity(self) -> 'Activity':
"""Returns this activity if type is 'message', None otherwise."""
def as_conversation_update_activity(self) -> 'Activity':
"""Returns this activity if type is 'conversationUpdate', None otherwise."""
def as_event_activity(self) -> 'Activity':
"""Returns this activity if type is 'event', None otherwise."""
def as_invoke_activity(self) -> 'Activity':
"""Returns this activity if type is 'invoke', None otherwise."""
def as_typing_activity(self) -> 'Activity':
"""Returns this activity if type is 'typing', None otherwise."""
def as_end_of_conversation_activity(self) -> 'Activity':
"""Returns this activity if type is 'endOfConversation', None otherwise."""
def as_installation_update_activity(self) -> 'Activity':
"""Returns this activity if type is 'installationUpdate', None otherwise."""
def as_message_update_activity(self) -> 'Activity':
"""Returns this activity if type is 'messageUpdate', None otherwise."""
def as_message_delete_activity(self) -> 'Activity':
"""Returns this activity if type is 'messageDelete', None otherwise."""
def as_message_reaction_activity(self) -> 'Activity':
"""Returns this activity if type is 'messageReaction', None otherwise."""
def as_suggestion_activity(self) -> 'Activity':
"""Returns this activity if type is 'suggestion', None otherwise."""
def as_trace_activity(self) -> 'Activity':
"""Returns this activity if type is 'trace', None otherwise."""
def as_handoff_activity(self) -> 'Activity':
"""Returns this activity if type is 'handoff', None otherwise."""
def as_command_activity(self) -> 'Activity':
"""Returns this activity if type is 'command', None otherwise."""
def as_command_result_activity(self) -> 'Activity':
"""Returns this activity if type is 'commandResult', None otherwise."""
def as_contact_relation_update_activity(self) -> 'Activity':
"""Returns this activity if type is 'contactRelationUpdate', None otherwise."""Static Factory Methods
Static methods for creating specific types of activities.
@staticmethod
def create_message_activity() -> 'Activity':
"""
Create a message activity.
Returns:
New Activity with type set to 'message'
"""
@staticmethod
def create_conversation_update_activity() -> 'Activity':
"""
Create a conversation update activity.
Returns:
New Activity with type set to 'conversationUpdate'
"""
@staticmethod
def create_event_activity() -> 'Activity':
"""
Create an event activity.
Returns:
New Activity with type set to 'event'
"""
@staticmethod
def create_trace_activity(name: str, value = None, value_type: str = None,
label: str = None) -> 'Activity':
"""
Create a trace activity for debugging and monitoring.
Parameters:
- name: Name of the trace
- value: Value to trace
- value_type: Type of the value
- label: Optional label
Returns:
New Activity with type set to 'trace'
"""Conversation Reference Model
Model for referencing a specific point in a conversation.
class ConversationReference(Model):
def __init__(self, *,
activity_id: str = None,
user = None, # ChannelAccount
bot = None, # ChannelAccount
conversation = None, # ConversationAccount
channel_id: str = None,
locale: str = None,
service_url: str = None,
**kwargs):
"""
An object relating to a particular point in a conversation.
Parameters:
- activity_id: ID of the activity to refer to
- user: User participating in this conversation
- bot: Bot participating in this conversation
- conversation: Conversation reference
- channel_id: Channel ID
- locale: Locale name for contents (BCP-47)
- service_url: Service endpoint for conversation operations
"""Activity Event Names
Enumeration of predefined activity event names.
class ActivityEventNames(str, Enum):
continue_conversation = "ContinueConversation"
create_conversation = "CreateConversation"Usage Examples
Creating and Sending a Message
from botbuilder.schema import Activity, ActivityTypes, ChannelAccount, ConversationAccount
# Create a message activity
activity = Activity(
type=ActivityTypes.message,
text="Hello! How can I help you today?",
from_property=ChannelAccount(id="bot", name="HelpBot"),
recipient=ChannelAccount(id="user123", name="User"),
conversation=ConversationAccount(id="conv456"),
channel_id="webchat"
)
# Check if activity has content before sending
if activity.has_content():
# Activity is ready to send
passCreating a Reply
# Create a reply to an existing message
original_message = Activity(
type=ActivityTypes.message,
text="What's the weather like?",
from_property=ChannelAccount(id="user123"),
recipient=ChannelAccount(id="bot"),
conversation=ConversationAccount(id="conv456"),
id="msg789"
)
# Create reply
reply = original_message.create_reply("The weather is sunny with 75°F!")
# Reply automatically has from/recipient swapped and reply_to_id setWorking with Conversation References
# Get conversation reference from activity
conv_ref = activity.get_conversation_reference()
# Apply conversation reference to a new activity
new_activity = Activity(type=ActivityTypes.typing)
new_activity = new_activity.apply_conversation_reference(conv_ref)
# Create a proactive message using conversation reference
proactive_message = Activity(
type=ActivityTypes.message,
text="This is a proactive message"
)
proactive_message = proactive_message.apply_conversation_reference(conv_ref, is_incoming=False)Type-Safe Activity Handling
def handle_activity(activity: Activity):
# Check activity type using conversion methods
if activity.as_message_activity():
print(f"Received message: {activity.text}")
elif activity.as_conversation_update_activity():
if activity.members_added:
print(f"Members added: {[m.name for m in activity.members_added]}")
elif activity.as_typing_activity():
print("User is typing...")Additional Activity Models
Adaptive Card Models
Models for handling Adaptive Card invoke operations.
class AdaptiveCardInvokeAction(Model):
def __init__(self, *, type: str = None, title: str = None,
id: str = None, data = None, **kwargs): ...
class AdaptiveCardInvokeValue(Model):
def __init__(self, *, action = None, authentication = None, **kwargs): ...
class AdaptiveCardInvokeResponse(Model):
def __init__(self, *, status_code: int = None, type: str = None,
value = None, **kwargs): ...Media Event Models
Models for media-related activity events.
class MediaEventValue(Model):
def __init__(self, *, card_value = None, **kwargs): ...Conversation Management Models
Models for managing conversation data and member information.
class PagedMembersResult(Model):
def __init__(self, *, continuation_token: str = None,
members: List = None, **kwargs): ...
class Transcript(Model):
def __init__(self, *, activities: List = None, **kwargs): ...Install with Tessl CLI
npx tessl i tessl/pypi-botbuilder-schema