0
# BotBuilder Schema
1

2
BotBuilder-schema contains the serialized data sent across the wire between user and bot when using Bot Framework. This package provides comprehensive data models for activities, conversations, channels, attachments, and authentication flows, serving as the foundational schema layer for Microsoft Bot Framework applications.
3

4
## Package Information
5

6
- **Package Name**: botbuilder-schema
7
- **Language**: Python
8
- **Installation**: `pip install botbuilder-schema`
9
- **Dependencies**: msrest==0.7.*, urllib3
10

11
## Core Imports
12

13
```python
14
from botbuilder.schema import Activity, ChannelAccount, ConversationAccount
15
```
16

17
Activity types and enums:
18

19
```python
20
from botbuilder.schema import ActivityTypes, RoleTypes, TextFormatTypes
21
```
22

23
Teams extension:
24

25
```python
26
from botbuilder.schema.teams import TeamsChannelData, TaskModuleRequest
27
```
28

29
## Basic Usage
30

31
```python
32
from botbuilder.schema import (
33
    Activity, 
34
    ActivityTypes, 
35
    ChannelAccount, 
36
    ConversationAccount,
37
    TextFormatTypes
38
)
39

40
# Create a simple message activity
41
message = Activity(
42
    type=ActivityTypes.message,
43
    text="Hello, World!",
44
    from_property=ChannelAccount(id="user123", name="User"),
45
    recipient=ChannelAccount(id="bot456", name="Bot"),
46
    conversation=ConversationAccount(id="conversation789"),
47
    channel_id="webchat",
48
    text_format=TextFormatTypes.plain
49
)
50

51
# Create a conversation update activity
52
update = Activity(
53
    type=ActivityTypes.conversation_update,
54
    members_added=[ChannelAccount(id="newuser", name="New User")],
55
    conversation=ConversationAccount(id="conversation789"),
56
    channel_id="webchat"
57
)
58

59
# Create a reply to an existing activity
60
reply = message.create_reply("Thanks for your message!")
61
```
62

63
## Architecture
64

65
The BotBuilder Schema follows a hierarchical design:
66

67
- **Activity**: Central communication model containing all message types, events, and conversation updates
68
- **Channel Models**: Account and conversation representations for different chat platforms  
69
- **Card Models**: Rich interactive content (Hero, Thumbnail, Receipt, OAuth, etc.)
70
- **Attachment Models**: File and media handling structures
71
- **Entity Models**: Semantic data like mentions, places, and geographic coordinates
72
- **Teams Extension**: Microsoft Teams-specific models for meetings, task modules, and O365 connectors
73

74
All models inherit from `msrest.serialization.Model` providing automatic JSON serialization for REST API communication across Bot Framework channels.
75

76
## Capabilities
77

78
### Core Activity Management
79

80
The foundational Activity model and supporting types that enable communication between bots and users across all Bot Framework channels. Includes activity creation, manipulation, and conversation management.
81

82
```python { .api }
83
class Activity(Model):
84
    def __init__(self, *, type: str = None, id: str = None, 
85
                 text: str = None, from_property = None, 
86
                 recipient = None, conversation = None, **kwargs): ...
87
    def create_reply(self, text: str = None) -> 'Activity': ...
88
    def apply_conversation_reference(self, reference: 'ConversationReference') -> 'Activity': ...
89
    def get_conversation_reference(self) -> 'ConversationReference': ...
90
    def has_content(self) -> bool: ...
91
```
92

93
[Core Activity Management](./core-activity.md)
94

95
### Channel and Conversation Models
96

97
Account and conversation representations that identify participants and conversation contexts across different chat platforms and channels.
98

99
```python { .api }
100
class ChannelAccount(Model):
101
    def __init__(self, *, id: str = None, name: str = None, 
102
                 aad_object_id: str = None, role: str = None, **kwargs): ...
103

104
class ConversationAccount(Model):
105
    def __init__(self, *, is_group: bool = None, conversation_type: str = None,
106
                 id: str = None, name: str = None, **kwargs): ...
107
```
108

109
[Channel and Conversation Models](./channel-conversation.md)
110

111
### Rich Card Components
112

113
Interactive card models for creating rich user experiences including hero cards, thumbnails, receipts, OAuth flows, and media content with buttons and actions.
114

115
```python { .api }
116
class HeroCard(Model):
117
    def __init__(self, *, title: str = None, subtitle: str = None,
118
                 text: str = None, images: List = None, buttons: List = None, **kwargs): ...
119

120
class CardAction(Model):
121
    def __init__(self, *, type: str = None, title: str = None,
122
                 value = None, **kwargs): ...
123
```
124

125
[Rich Card Components](./rich-cards.md)
126

127
### Attachment and Media Handling
128

129
File attachment and media management models supporting upload, download, and display of documents, images, audio, and video content.
130

131
```python { .api }
132
class Attachment(Model):
133
    def __init__(self, *, content_type: str = None, content_url: str = None,
134
                 content = None, name: str = None, **kwargs): ...
135

136
class AttachmentData(Model):
137
    def __init__(self, *, type: str = None, name: str = None,
138
                 original_base64: str = None, **kwargs): ...
139
```
140

141
[Attachment and Media Handling](./attachments-media.md)
142

143
### Authentication and OAuth
144

145
OAuth token management, authentication flows, and signin processes including token requests, responses, and exchange mechanisms for secure bot authentication.
146

147
```python { .api }
148
class TokenResponse(Model):
149
    def __init__(self, *, connection_name: str = None, token: str = None,
150
                 expiration: str = None, **kwargs): ...
151

152
class TokenRequest(Model):
153
    def __init__(self, *, provider: str = None, settings: dict = None, **kwargs): ...
154
```
155

156
[Authentication and OAuth](./authentication-oauth.md)
157

158
### Activity Types and Enums
159

160
Comprehensive enumeration types defining activity types, role types, input hints, action types, and other standardized values used throughout the Bot Framework.
161

162
```python { .api }
163
class ActivityTypes(str, Enum):
164
    message = "message"
165
    conversation_update = "conversationUpdate"
166
    typing = "typing"
167
    # ... additional types
168

169
class RoleTypes(str, Enum):
170
    user = "user"
171
    bot = "bot"
172
    skill = "skill"
173
```
174

175
[Activity Types and Enums](./activity-types-enums.md)
176

177
### Entities and Semantic Data
178

179
Semantic entity models for representing structured data like mentions, places, geographic coordinates, and generic schema.org entities within Bot Framework activities.
180

181
```python { .api }
182
class Entity(Model):
183
    def __init__(self, *, type: str = None, **kwargs): ...
184

185
class GeoCoordinates(Model):
186
    def __init__(self, *, elevation: float = None, latitude: float = None,
187
                 longitude: float = None, type: str = None, name: str = None, **kwargs): ...
188

189
class Place(Model):
190
    def __init__(self, *, address=None, geo=None, has_map=None,
191
                 type: str = None, name: str = None, **kwargs): ...
192

193
class Thing(Model):
194
    def __init__(self, *, type: str = None, name: str = None, **kwargs): ...
195
```
196

197
[Entities and Semantic Data](./entities-semantic.md)
198

199
### Microsoft Teams Integration
200

201
Teams-specific models for meetings, task modules, messaging extensions, O365 connector cards, and file handling within Microsoft Teams environments.
202

203
```python { .api }
204
class TeamsChannelData(Model):
205
    def __init__(self, *, team = None, channel = None, meeting = None, **kwargs): ...
206

207
class TaskModuleRequest(Model):
208
    def __init__(self, *, data = None, context = None, **kwargs): ...
209
```
210

211
[Microsoft Teams Integration](./teams-integration.md)
212

213
## Types
214

215
### Core Types
216

217
```python { .api }
218
# Import from botbuilder.schema
219
Activity: Model
220
ChannelAccount: Model  
221
ConversationAccount: Model
222
ConversationReference: Model
223
ResourceResponse: Model
224
ErrorResponse: Model
225
```
226

227
### Enum Types
228

229
```python { .api }
230
# Activity and message types
231
ActivityTypes: Enum
232
RoleTypes: Enum
233
TextFormatTypes: Enum
234
ActivityImportance: Enum
235

236
# Action and input types  
237
ActionTypes: Enum
238
InputHints: Enum
239
AttachmentLayoutTypes: Enum
240
MessageReactionTypes: Enum
241

242
# Status and flow types
243
EndOfConversationCodes: Enum
244
DeliveryModes: Enum
245
ContactRelationUpdateActionTypes: Enum
246
InstallationUpdateActionTypes: Enum
247
```
248

249
### Constant Types
250

251
```python { .api }
252
# Authentication constants
253
SignInConstants: Enum
254
CallerIdConstants: Enum
255

256
# Speech synthesis constants
257
SpeechConstants: class
258
```