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
channel-conversation.mddocs/
Channel and Conversation Models
Account and conversation representations that identify participants and conversation contexts across different chat platforms and channels. These models provide the foundational identity and context structures for Bot Framework communications.
Capabilities
Channel Account
Represents a channel participant including users, bots, and skills with identity and role information.
class ChannelAccount(Model):
def __init__(self, *,
id: str = None,
name: str = None,
aad_object_id: str = None,
role: str = None,
**kwargs):
"""
Channel account information.
Parameters:
- id: Channel-specific identifier for the account
- name: Display name of the account
- aad_object_id: Azure Active Directory object ID
- role: Role of the account (user, bot, skill)
"""Conversation Account
Represents a conversation including group/individual context and properties.
class ConversationAccount(Model):
def __init__(self, *,
is_group: bool = None,
conversation_type: str = None,
id: str = None,
name: str = None,
aad_object_id: str = None,
role: str = None,
tenant_id: str = None,
properties: dict = None,
**kwargs):
"""
Conversation account information.
Parameters:
- is_group: Whether conversation is a group conversation
- conversation_type: Type of conversation (personal, group, channel)
- id: Unique identifier for the conversation
- name: Display name of the conversation
- aad_object_id: Azure Active Directory object ID
- role: Role in the conversation
- tenant_id: Tenant identifier
- properties: Additional conversation properties
"""Conversation Management Models
Models for creating, managing, and tracking conversations.
class ConversationParameters(Model):
def __init__(self, *,
is_group: bool = None,
bot = None, # ChannelAccount
members: List = None, # List[ChannelAccount]
topic_name: str = None,
activity = None, # Activity
channel_data = None,
tenant_id: str = None,
**kwargs):
"""
Parameters for creating a new conversation.
Parameters:
- is_group: Whether to create a group conversation
- bot: Bot account creating the conversation
- members: Initial members of the conversation
- topic_name: Topic name for the conversation
- activity: Initial activity to send
- channel_data: Channel-specific data
- tenant_id: Tenant identifier
"""
class ConversationResourceResponse(Model):
def __init__(self, *,
activity_id: str = None,
service_url: str = None,
id: str = None,
**kwargs):
"""
Response from conversation operations.
Parameters:
- activity_id: ID of the created activity
- service_url: Service URL for the conversation
- id: Unique identifier for the resource
"""
class ConversationsResult(Model):
def __init__(self, *,
continuation_token: str = None,
conversations: List = None, # List[ConversationAccount]
**kwargs):
"""
Results from batch conversation operations.
Parameters:
- continuation_token: Token for fetching next batch
- conversations: Array of conversation accounts
"""
class ConversationMembers(Model):
def __init__(self, *,
members: List = None, # List[ChannelAccount]
**kwargs):
"""
Members of a conversation.
Parameters:
- members: List of conversation members
"""Response Models
Models for handling API responses and resource references.
class ResourceResponse(Model):
def __init__(self, *,
id: str = None,
**kwargs):
"""
Generic resource response.
Parameters:
- id: Unique identifier of the resource
"""
class InvokeResponse(Model):
def __init__(self, *,
status: int = None,
body = None,
**kwargs):
"""
Response to an invoke activity.
Parameters:
- status: HTTP status code
- body: Response body content
"""Error Handling Models
Models for representing errors and exceptions in Bot Framework operations.
class Error(Model):
def __init__(self, *,
code: str = None,
message: str = None,
**kwargs):
"""
Error information.
Parameters:
- code: Error code
- message: Error message
"""
class ErrorResponse(Model):
def __init__(self, *,
error = None, # Error
**kwargs):
"""
Error response wrapper.
Parameters:
- error: Error object with details
"""
class ErrorResponseException(HttpOperationError):
def __init__(self, error_response: ErrorResponse):
"""
Exception for error responses.
Parameters:
- error_response: ErrorResponse object with error details
"""
class InnerHttpError(Model):
def __init__(self, *,
status_code: int = None,
body = None,
**kwargs):
"""
Inner HTTP error details.
Parameters:
- status_code: HTTP status code
- body: Error response body
"""Expected Replies Model
Model for handling expected replies in conversation flows.
class ExpectedReplies(Model):
def __init__(self, *,
activities: List = None, # List[Activity]
**kwargs):
"""
Expected replies structure.
Parameters:
- activities: Array of expected activity replies
"""Usage Examples
Creating Channel Accounts
from botbuilder.schema import ChannelAccount, RoleTypes
# Create user account
user = ChannelAccount(
id="user123",
name="John Doe",
role=RoleTypes.user
)
# Create bot account
bot = ChannelAccount(
id="bot456",
name="HelpBot",
role=RoleTypes.bot
)
# Create skill account
skill = ChannelAccount(
id="skill789",
name="WeatherSkill",
role=RoleTypes.skill
)Creating Conversation Accounts
from botbuilder.schema import ConversationAccount
# Create individual conversation
personal_conv = ConversationAccount(
id="conv_personal_123",
name="Personal Chat",
is_group=False,
conversation_type="personal"
)
# Create group conversation
group_conv = ConversationAccount(
id="conv_group_456",
name="Team Discussion",
is_group=True,
conversation_type="group",
tenant_id="tenant789"
)Starting a New Conversation
from botbuilder.schema import ConversationParameters, ChannelAccount, Activity, ActivityTypes
# Define conversation participants
bot = ChannelAccount(id="bot", name="MyBot")
user1 = ChannelAccount(id="user1", name="Alice")
user2 = ChannelAccount(id="user2", name="Bob")
# Create conversation parameters
conv_params = ConversationParameters(
is_group=True,
bot=bot,
members=[user1, user2],
topic_name="Project Planning",
activity=Activity(
type=ActivityTypes.message,
text="Welcome to the project planning discussion!"
)
)
# Use with Bot Framework Connector API to create conversation
# connector.create_conversation(conv_params)Handling Conversation Updates
from botbuilder.schema import Activity, ActivityTypes
def handle_conversation_update(activity: Activity):
"""Handle members joining or leaving conversations."""
if activity.members_added:
for member in activity.members_added:
if member.id != activity.recipient.id: # Not the bot itself
print(f"Welcome {member.name}!")
if activity.members_removed:
for member in activity.members_removed:
print(f"Goodbye {member.name}!")Working with Conversation References
from botbuilder.schema import ConversationReference, Activity, ActivityTypes
# Create conversation reference for proactive messaging
conv_ref = ConversationReference(
activity_id="msg123",
user=ChannelAccount(id="user456", name="User"),
bot=ChannelAccount(id="bot789", name="Bot"),
conversation=ConversationAccount(id="conv123"),
channel_id="webchat",
service_url="https://webchat.botframework.com"
)
# Use reference to send proactive message
proactive_activity = Activity(
type=ActivityTypes.message,
text="This is a proactive message"
)
proactive_activity = proactive_activity.apply_conversation_reference(conv_ref)Error Handling
from botbuilder.schema import ErrorResponse, ErrorResponseException
try:
# Bot Framework operation that might fail
pass
except ErrorResponseException as e:
error_response = e.error_response
if error_response and error_response.error:
print(f"Error {error_response.error.code}: {error_response.error.message}")Install with Tessl CLI
npx tessl i tessl/pypi-botbuilder-schema