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

teams-integration.mddocs/

Microsoft Teams Integration

Teams-specific models for meetings, task modules, messaging extensions, O365 connector cards, and file handling within Microsoft Teams environments. This module extends the core Bot Framework schema with Teams-specific functionality.

Core Teams Models

Teams Channel Account

Extended channel account with Teams-specific properties.

class TeamsChannelAccount(Model):
    def __init__(self, *, id: str = None, name: str = None, 
                 aad_object_id: str = None, role: str = None,
                 user_principal_name: str = None, teams_user_id: str = None, **kwargs): ...
from botbuilder.schema.teams import TeamsChannelAccount

teams_user = TeamsChannelAccount(
    id="29:1234567890",
    name="John Doe",
    aad_object_id="12345678-1234-1234-1234-123456789012",
    user_principal_name="john.doe@company.com",
    teams_user_id="teams-user-123"
)

Teams Channel Data

Contains Teams-specific channel information including team, channel, and meeting details.

class TeamsChannelData(Model):
    def __init__(self, *, team = None, channel = None, meeting = None,
                 settings = None, tenant = None, source_event_time: str = None, **kwargs): ...

class TeamInfo(Model):
    def __init__(self, *, id: str = None, name: str = None, **kwargs): ...

class ChannelInfo(Model):
    def __init__(self, *, id: str = None, name: str = None, **kwargs): ...

class TenantInfo(Model):
    def __init__(self, *, id: str = None, **kwargs): ...

class TeamsPagedMembersResult(Model):
    def __init__(self, *, continuation_token: str = None,
                 members: List = None, **kwargs): ...
from botbuilder.schema.teams import TeamsChannelData, TeamInfo, ChannelInfo, TenantInfo

teams_data = TeamsChannelData(
    team=TeamInfo(id="19:team-id", name="Development Team"),
    channel=ChannelInfo(id="19:channel-id", name="General"),
    tenant=TenantInfo(id="tenant-id-12345")
)

Meeting Models

Teams Meeting Info

Core meeting information for Teams meetings.

class TeamsMeetingInfo(Model):
    def __init__(self, *, id: str = None, organized: str = None,
                 join_url: str = None, **kwargs): ...

class TeamsMeetingParticipant(Model):
    def __init__(self, *, user = None, meeting = None, conversation = None, **kwargs): ...

class MeetingDetails(Model):
    def __init__(self, *, id: str = None, ms_graph_resource_id: str = None,
                 scheduled_start_time: str = None, scheduled_end_time: str = None,
                 title: str = None, join_url: str = None, **kwargs): ...
from botbuilder.schema.teams import TeamsMeetingInfo, MeetingDetails

meeting_info = TeamsMeetingInfo(
    id="meeting-id-12345",
    organized="2023-10-15T14:00:00Z",
    join_url="https://teams.microsoft.com/l/meetup-join/..."
)

meeting_details = MeetingDetails(
    id="meeting-id-12345",
    title="Sprint Planning Meeting",
    scheduled_start_time="2023-10-15T14:00:00Z",
    scheduled_end_time="2023-10-15T15:00:00Z",
    join_url="https://teams.microsoft.com/l/meetup-join/..."
)

Meeting Events

Models for meeting lifecycle events.

class MeetingStartEventDetails(Model):
    def __init__(self, *, start_time: str = None, title: str = None,
                 type: str = None, id: str = None, **kwargs): ...

class MeetingEndEventDetails(Model):
    def __init__(self, *, end_time: str = None, title: str = None,
                 type: str = None, id: str = None, **kwargs): ...

class MeetingParticipantsEventDetails(Model):
    def __init__(self, *, members: List = None, **kwargs): ...
from botbuilder.schema.teams import MeetingStartEventDetails, MeetingEndEventDetails

meeting_start = MeetingStartEventDetails(
    start_time="2023-10-15T14:00:00Z",
    title="Sprint Planning Meeting",
    type="meetingStart",
    id="meeting-id-12345"
)

meeting_end = MeetingEndEventDetails(
    end_time="2023-10-15T15:00:00Z", 
    title="Sprint Planning Meeting",
    type="meetingEnd",
    id="meeting-id-12345"
)

Task Modules

Task Module Request and Response

Models for Teams task modules (dialogs).

class TaskModuleRequest(Model):
    def __init__(self, *, data = None, context = None, **kwargs): ...

class TaskModuleResponse(Model):
    def __init__(self, *, task = None, **kwargs): ...

class TaskModuleTaskInfo(Model):
    def __init__(self, *, title: str = None, height = None, width = None,
                 url: str = None, card = None, fallback_url: str = None,
                 completion_bot_id: str = None, **kwargs): ...
from botbuilder.schema.teams import (
    TaskModuleRequest, TaskModuleResponse, TaskModuleTaskInfo
)

# Task module request
task_request = TaskModuleRequest(
    data={"custom_data": "value"},
    context={"theme": "default"}
)

# Task module response with URL
task_info = TaskModuleTaskInfo(
    title="Configuration Dialog",
    height=400,
    width=600,
    url="https://myapp.com/config"
)

task_response = TaskModuleResponse(task=task_info)

Task Module Response Types

Different response types for task modules.

class TaskModuleContinueResponse(Model):
    def __init__(self, *, type: str = None, task = None, **kwargs): ...

class TaskModuleMessageResponse(Model):
    def __init__(self, *, type: str = None, task = None, **kwargs): ...
from botbuilder.schema.teams import TaskModuleContinueResponse

continue_response = TaskModuleContinueResponse(
    type="continue",
    task=task_info
)

Messaging Extensions

Messaging Extension Query

Models for messaging extension queries and responses.

class MessagingExtensionQuery(Model):
    def __init__(self, *, command_id: str = None, parameters: List = None,
                 query_options = None, **kwargs): ...

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

class MessagingExtensionResponse(Model):
    def __init__(self, *, compose_extension = None, **kwargs): ...

class MessagingExtensionResult(Model):
    def __init__(self, *, attachment_type: str = None, attachments: List = None,
                 activity_preview = None, type: str = None, **kwargs): ...
from botbuilder.schema.teams import (
    MessagingExtensionQuery, MessagingExtensionParameter,
    MessagingExtensionResponse, MessagingExtensionResult,
    MessagingExtensionAttachment
)

# Query from messaging extension
me_query = MessagingExtensionQuery(
    command_id="searchCommand",
    parameters=[
        MessagingExtensionParameter(name="searchText", value="bot framework")
    ]
)

# Response with results
me_result = MessagingExtensionResult(
    type="result",
    attachment_type="list",
    attachments=[
        MessagingExtensionAttachment(
            content_type="application/vnd.microsoft.card.hero",
            content=hero_card
        )
    ]
)

me_response = MessagingExtensionResponse(compose_extension=me_result)

Messaging Extension Actions

Models for messaging extension actions.

class MessagingExtensionAction(Model):
    def __init__(self, *, command_id: str = None, command_context: str = None,
                 bot_id: str = None, bot_message_preview_action: str = None,
                 message_payload = None, **kwargs): ...

class MessagingExtensionActionResponse(Model):
    def __init__(self, *, task = None, compose_extension = None, **kwargs): ...
from botbuilder.schema.teams import MessagingExtensionAction, MessagingExtensionActionResponse

# Action request
me_action = MessagingExtensionAction(
    command_id="createCard",
    command_context="compose",
    bot_id="bot-id-12345"
)

# Action response with task module
action_response = MessagingExtensionActionResponse(
    task=task_info
)

File Handling

File Consent and Upload

Models for Teams file handling workflows.

class FileConsentCard(Model):
    def __init__(self, *, description: str = None, size_in_bytes: int = None,
                 accept_context = None, decline_context = None, **kwargs): ...

class FileConsentCardResponse(Model):
    def __init__(self, *, action: str = None, context = None,
                 upload_info = None, **kwargs): ...

class FileUploadInfo(Model):
    def __init__(self, *, content_url: str = None, name: str = None,
                 upload_url: str = None, unique_id: str = None, **kwargs): ...

class FileDownloadInfo(Model):
    def __init__(self, *, download_url: str = None, unique_id: str = None,
                 file_type: str = None, **kwargs): ...

class FileInfoCard(Model):
    def __init__(self, *, description: str = None, size_in_bytes: int = None,
                 accept_context = None, decline_context = None, **kwargs): ...
from botbuilder.schema.teams import (
    FileConsentCard, FileConsentCardResponse, FileUploadInfo
)

# File consent card
file_consent = FileConsentCard(
    description="Project Documentation.pdf",
    size_in_bytes=2048576,
    accept_context={"file_id": "doc-123"},
    decline_context={"file_id": "doc-123"}
)

# File upload info after consent
upload_info = FileUploadInfo(
    content_url="https://graph.microsoft.com/files/...",
    name="Project Documentation.pdf",
    upload_url="https://teams.microsoft.com/upload/...",
    unique_id="file-unique-id-123"
)

O365 Connector Cards

O365 Connector Card

Rich connector cards for Office 365 integrations.

class O365ConnectorCard(Model):
    def __init__(self, *, title: str = None, text: str = None,
                 summary: str = None, theme_color: str = None,
                 sections: List = None, potential_actions: List = None, **kwargs): ...

class O365ConnectorCardSection(Model):
    def __init__(self, *, title: str = None, text: str = None,
                 activity_title: str = None, activity_subtitle: str = None,
                 activity_text: str = None, activity_image: str = None,
                 facts: List = None, images: List = None, **kwargs): ...

class O365ConnectorCardFact(Model):
    def __init__(self, *, name: str = None, value: str = None, **kwargs): ...
from botbuilder.schema.teams import (
    O365ConnectorCard, O365ConnectorCardSection, O365ConnectorCardFact
)

# O365 connector card
connector_card = O365ConnectorCard(
    title="Build Status",
    text="Build completed successfully",
    theme_color="00FF00",
    sections=[
        O365ConnectorCardSection(
            title="Build Details",
            facts=[
                O365ConnectorCardFact(name="Duration", value="2m 30s"),
                O365ConnectorCardFact(name="Tests", value="45 passed")
            ]
        )
    ]
)

O365 Connector Actions

Action models for O365 connector cards.

class O365ConnectorCardActionBase(Model):
    def __init__(self, *, type: str = None, name: str = None,
                 id: str = None, **kwargs): ...

class O365ConnectorCardHttpPOST(Model):
    def __init__(self, *, target: str = None, headers: List = None,
                 body: str = None, **kwargs): ...

class O365ConnectorCardOpenUri(Model):
    def __init__(self, *, targets: List = None, **kwargs): ...
from botbuilder.schema.teams import O365ConnectorCardHttpPOST, O365ConnectorCardOpenUri

# HTTP POST action
post_action = O365ConnectorCardHttpPOST(
    target="https://api.myservice.com/webhook",
    headers=[{"name": "Authorization", "value": "Bearer token"}],
    body='{"action": "approve", "id": "123"}'
)

# Open URI action
uri_action = O365ConnectorCardOpenUri(
    targets=[
        {"os": "default", "uri": "https://myapp.com/details/123"}
    ]
)

Tab Support

Tab Request and Response

Models for Teams tab applications.

class TabRequest(Model):
    def __init__(self, *, tab_context = None, state = None,
                 properties = None, conversation = None, **kwargs): ...

class TabResponse(Model):
    def __init__(self, *, tab = None, **kwargs): ...

class TabContext(Model):
    def __init__(self, *, theme: str = None, entity_id: str = None,
                 sub_entity_id: str = None, locale: str = None,
                 channel_id: str = None, team_id: str = None,
                 tenant_id: str = None, **kwargs): ...
from botbuilder.schema.teams import TabRequest, TabResponse, TabContext

tab_context = TabContext(
    theme="default",
    entity_id="settings",
    team_id="team-id-12345",
    channel_id="channel-id-67890",
    tenant_id="tenant-id-abcde"
)

tab_request = TabRequest(
    tab_context=tab_context,
    properties={"custom_prop": "value"}
)

Authentication in Teams

Teams Authentication

Teams-specific authentication models.

class SigninStateVerificationQuery(Model):
    def __init__(self, *, state: str = None, **kwargs): ...

class BotConfigAuth(Model):
    def __init__(self, *, type: str = None, id: str = None,
                 connection_name: str = None, text: str = None,
                 suggested_actions = None, **kwargs): ...
from botbuilder.schema.teams import SigninStateVerificationQuery, BotConfigAuth

# State verification for Teams auth
state_query = SigninStateVerificationQuery(
    state="auth-state-token-12345"
)

# Bot configuration auth
config_auth = BotConfigAuth(
    type="oauth",
    connection_name="TeamsAuth",
    text="Please sign in to access Teams resources"
)

Usage Patterns

Teams Bot Setup

from botbuilder.schema import Activity, ActivityTypes
from botbuilder.schema.teams import TeamsChannelData

async def handle_teams_message(activity: Activity):
    """Handle message in Teams context"""
    if hasattr(activity, 'channel_data') and activity.channel_data:
        teams_data = TeamsChannelData(**activity.channel_data)
        
        # Access Teams-specific information
        team_id = teams_data.team.id if teams_data.team else None
        channel_id = teams_data.channel.id if teams_data.channel else None
        
        # Handle Teams-specific logic
        if team_id:
            return await handle_team_message(activity, team_id, channel_id)
    
    # Fallback to regular message handling
    return await handle_regular_message(activity)

Task Module Integration

from botbuilder.schema.teams import TaskModuleRequest, TaskModuleResponse, TaskModuleTaskInfo

async def handle_task_module_fetch(request: TaskModuleRequest):
    """Handle task module fetch request"""
    # Create task module response
    task_info = TaskModuleTaskInfo(
        title="User Settings",
        height=500,
        width=400,
        url="https://myapp.com/settings"
    )
    
    return TaskModuleResponse(task=task_info)

async def handle_task_module_submit(request: TaskModuleRequest):
    """Handle task module submit"""
    user_data = request.data
    
    # Process submitted data
    result = await process_user_settings(user_data)
    
    # Return success message
    return TaskModuleResponse(
        task={"type": "message", "value": "Settings saved successfully!"}
    )

Messaging Extension Implementation

from botbuilder.schema.teams import (
    MessagingExtensionQuery, MessagingExtensionResponse,
    MessagingExtensionResult, MessagingExtensionAttachment
)

async def handle_messaging_extension_query(query: MessagingExtensionQuery):
    """Handle messaging extension search query"""
    search_text = ""
    for param in query.parameters:
        if param.name == "searchText":
            search_text = param.value
            break
    
    # Perform search
    results = await search_items(search_text)
    
    # Create attachments from results
    attachments = []
    for item in results:
        card = create_hero_card(item)
        attachment = MessagingExtensionAttachment(
            content_type="application/vnd.microsoft.card.hero",
            content=card,
            preview=create_preview_card(item)
        )
        attachments.append(attachment)
    
    # Return response
    result = MessagingExtensionResult(
        type="result",
        attachment_type="list",
        attachments=attachments
    )
    
    return MessagingExtensionResponse(compose_extension=result)

Teams-Specific Features

@Mentions in Teams

from botbuilder.schema import Entity
from botbuilder.schema.teams import TeamsChannelAccount

def create_mention_entity(user: TeamsChannelAccount, mentioned_text: str) -> Entity:
    """Create mention entity for Teams"""
    return Entity(
        type="mention",
        properties={
            "mentioned": {
                "id": user.id,
                "name": user.name
            },
            "text": mentioned_text
        }
    )

Teams Meeting Bot

from botbuilder.schema.teams import TeamsMeetingInfo, MeetingStartEventDetails

async def handle_meeting_events(activity: Activity):
    """Handle Teams meeting events"""
    if activity.name == "application/vnd.microsoft.meetingStart":
        meeting_start = MeetingStartEventDetails(**activity.value)
        return await handle_meeting_start(meeting_start)
    
    elif activity.name == "application/vnd.microsoft.meetingEnd":
        meeting_end = MeetingEndEventDetails(**activity.value)
        return await handle_meeting_end(meeting_end)

Message Actions

Message Actions Payload

Models for Teams message action payloads and components.

class MessageActionsPayload(Model):
    def __init__(self, *, id: str = None, timestamp: str = None,
                 action: str = None, body = None, attachments: List = None,
                 from_property = None, conversation = None, recipient = None,
                 channel_data = None, reply_to_id: str = None, value = None, **kwargs): ...

class MessageActionsPayloadApp(Model):
    def __init__(self, *, id: str = None, display_name: str = None,
                 name: str = None, **kwargs): ...

class MessageActionsPayloadAttachment(Model):
    def __init__(self, *, id: str = None, content_type: str = None,
                 content_url: str = None, content = None, name: str = None,
                 thumbnail_url: str = None, **kwargs): ...

class MessageActionsPayloadBody(Model):
    def __init__(self, *, content_type: str = None, content = None, **kwargs): ...

class MessageActionsPayloadConversation(Model):
    def __init__(self, *, id: str = None, display_name: str = None,
                 name: str = None, conversation_type: str = None,
                 tenant_id: str = None, **kwargs): ...

class MessageActionsPayloadFrom(Model):
    def __init__(self, *, id: str = None, display_name: str = None,
                 name: str = None, user_principal_name: str = None, **kwargs): ...

class MessageActionsPayloadUser(Model):
    def __init__(self, *, id: str = None, display_name: str = None,
                 name: str = None, **kwargs): ...

class MessageActionsPayloadMention(Model):
    def __init__(self, *, mentioned = None, text: str = None,
                 type: str = None, **kwargs): ...

class MessageActionsPayloadReaction(Model):
    def __init__(self, *, type: str = None, **kwargs): ...

Additional Teams Models

Notifications and Miscellaneous

class NotificationInfo(Model):
    def __init__(self, *, alert: bool = None, external_resource_url: str = None, **kwargs): ...

class ConversationList(Model):
    def __init__(self, *, conversations: List = None, **kwargs): ...

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

class CacheInfo(Model):
    def __init__(self, *, cache_type: str = None, cache_duration: int = None, **kwargs): ...

class ReadReceiptInfo(Model):
    def __init__(self, *, user = None, last_read_message_id: str = None, **kwargs): ...

class OnBehalfOf(Model):
    def __init__(self, *, display_name: str = None, mri: str = None, **kwargs): ...

Error Handling

from botbuilder.schema import Activity, ActivityTypes

def create_teams_error_response(error: str) -> Activity:
    """Create Teams-appropriate error response"""
    return Activity(
        type=ActivityTypes.message,
        text=f"Teams operation failed: {error}. Please try again or contact your administrator."
    )

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