0
# Channel and Conversation Models
1
2
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.
3
4
## Capabilities
5
6
### Channel Account
7
8
Represents a channel participant including users, bots, and skills with identity and role information.
9
10
```python { .api }
11
class ChannelAccount(Model):
12
def __init__(self, *,
13
id: str = None,
14
name: str = None,
15
aad_object_id: str = None,
16
role: str = None,
17
**kwargs):
18
"""
19
Channel account information.
20
21
Parameters:
22
- id: Channel-specific identifier for the account
23
- name: Display name of the account
24
- aad_object_id: Azure Active Directory object ID
25
- role: Role of the account (user, bot, skill)
26
"""
27
```
28
29
### Conversation Account
30
31
Represents a conversation including group/individual context and properties.
32
33
```python { .api }
34
class ConversationAccount(Model):
35
def __init__(self, *,
36
is_group: bool = None,
37
conversation_type: str = None,
38
id: str = None,
39
name: str = None,
40
aad_object_id: str = None,
41
role: str = None,
42
tenant_id: str = None,
43
properties: dict = None,
44
**kwargs):
45
"""
46
Conversation account information.
47
48
Parameters:
49
- is_group: Whether conversation is a group conversation
50
- conversation_type: Type of conversation (personal, group, channel)
51
- id: Unique identifier for the conversation
52
- name: Display name of the conversation
53
- aad_object_id: Azure Active Directory object ID
54
- role: Role in the conversation
55
- tenant_id: Tenant identifier
56
- properties: Additional conversation properties
57
"""
58
```
59
60
### Conversation Management Models
61
62
Models for creating, managing, and tracking conversations.
63
64
```python { .api }
65
class ConversationParameters(Model):
66
def __init__(self, *,
67
is_group: bool = None,
68
bot = None, # ChannelAccount
69
members: List = None, # List[ChannelAccount]
70
topic_name: str = None,
71
activity = None, # Activity
72
channel_data = None,
73
tenant_id: str = None,
74
**kwargs):
75
"""
76
Parameters for creating a new conversation.
77
78
Parameters:
79
- is_group: Whether to create a group conversation
80
- bot: Bot account creating the conversation
81
- members: Initial members of the conversation
82
- topic_name: Topic name for the conversation
83
- activity: Initial activity to send
84
- channel_data: Channel-specific data
85
- tenant_id: Tenant identifier
86
"""
87
88
class ConversationResourceResponse(Model):
89
def __init__(self, *,
90
activity_id: str = None,
91
service_url: str = None,
92
id: str = None,
93
**kwargs):
94
"""
95
Response from conversation operations.
96
97
Parameters:
98
- activity_id: ID of the created activity
99
- service_url: Service URL for the conversation
100
- id: Unique identifier for the resource
101
"""
102
103
class ConversationsResult(Model):
104
def __init__(self, *,
105
continuation_token: str = None,
106
conversations: List = None, # List[ConversationAccount]
107
**kwargs):
108
"""
109
Results from batch conversation operations.
110
111
Parameters:
112
- continuation_token: Token for fetching next batch
113
- conversations: Array of conversation accounts
114
"""
115
116
class ConversationMembers(Model):
117
def __init__(self, *,
118
members: List = None, # List[ChannelAccount]
119
**kwargs):
120
"""
121
Members of a conversation.
122
123
Parameters:
124
- members: List of conversation members
125
"""
126
```
127
128
### Response Models
129
130
Models for handling API responses and resource references.
131
132
```python { .api }
133
class ResourceResponse(Model):
134
def __init__(self, *,
135
id: str = None,
136
**kwargs):
137
"""
138
Generic resource response.
139
140
Parameters:
141
- id: Unique identifier of the resource
142
"""
143
144
class InvokeResponse(Model):
145
def __init__(self, *,
146
status: int = None,
147
body = None,
148
**kwargs):
149
"""
150
Response to an invoke activity.
151
152
Parameters:
153
- status: HTTP status code
154
- body: Response body content
155
"""
156
```
157
158
### Error Handling Models
159
160
Models for representing errors and exceptions in Bot Framework operations.
161
162
```python { .api }
163
class Error(Model):
164
def __init__(self, *,
165
code: str = None,
166
message: str = None,
167
**kwargs):
168
"""
169
Error information.
170
171
Parameters:
172
- code: Error code
173
- message: Error message
174
"""
175
176
class ErrorResponse(Model):
177
def __init__(self, *,
178
error = None, # Error
179
**kwargs):
180
"""
181
Error response wrapper.
182
183
Parameters:
184
- error: Error object with details
185
"""
186
187
class ErrorResponseException(HttpOperationError):
188
def __init__(self, error_response: ErrorResponse):
189
"""
190
Exception for error responses.
191
192
Parameters:
193
- error_response: ErrorResponse object with error details
194
"""
195
196
class InnerHttpError(Model):
197
def __init__(self, *,
198
status_code: int = None,
199
body = None,
200
**kwargs):
201
"""
202
Inner HTTP error details.
203
204
Parameters:
205
- status_code: HTTP status code
206
- body: Error response body
207
"""
208
```
209
210
### Expected Replies Model
211
212
Model for handling expected replies in conversation flows.
213
214
```python { .api }
215
class ExpectedReplies(Model):
216
def __init__(self, *,
217
activities: List = None, # List[Activity]
218
**kwargs):
219
"""
220
Expected replies structure.
221
222
Parameters:
223
- activities: Array of expected activity replies
224
"""
225
```
226
227
## Usage Examples
228
229
### Creating Channel Accounts
230
231
```python
232
from botbuilder.schema import ChannelAccount, RoleTypes
233
234
# Create user account
235
user = ChannelAccount(
236
id="user123",
237
name="John Doe",
238
role=RoleTypes.user
239
)
240
241
# Create bot account
242
bot = ChannelAccount(
243
id="bot456",
244
name="HelpBot",
245
role=RoleTypes.bot
246
)
247
248
# Create skill account
249
skill = ChannelAccount(
250
id="skill789",
251
name="WeatherSkill",
252
role=RoleTypes.skill
253
)
254
```
255
256
### Creating Conversation Accounts
257
258
```python
259
from botbuilder.schema import ConversationAccount
260
261
# Create individual conversation
262
personal_conv = ConversationAccount(
263
id="conv_personal_123",
264
name="Personal Chat",
265
is_group=False,
266
conversation_type="personal"
267
)
268
269
# Create group conversation
270
group_conv = ConversationAccount(
271
id="conv_group_456",
272
name="Team Discussion",
273
is_group=True,
274
conversation_type="group",
275
tenant_id="tenant789"
276
)
277
```
278
279
### Starting a New Conversation
280
281
```python
282
from botbuilder.schema import ConversationParameters, ChannelAccount, Activity, ActivityTypes
283
284
# Define conversation participants
285
bot = ChannelAccount(id="bot", name="MyBot")
286
user1 = ChannelAccount(id="user1", name="Alice")
287
user2 = ChannelAccount(id="user2", name="Bob")
288
289
# Create conversation parameters
290
conv_params = ConversationParameters(
291
is_group=True,
292
bot=bot,
293
members=[user1, user2],
294
topic_name="Project Planning",
295
activity=Activity(
296
type=ActivityTypes.message,
297
text="Welcome to the project planning discussion!"
298
)
299
)
300
301
# Use with Bot Framework Connector API to create conversation
302
# connector.create_conversation(conv_params)
303
```
304
305
### Handling Conversation Updates
306
307
```python
308
from botbuilder.schema import Activity, ActivityTypes
309
310
def handle_conversation_update(activity: Activity):
311
"""Handle members joining or leaving conversations."""
312
313
if activity.members_added:
314
for member in activity.members_added:
315
if member.id != activity.recipient.id: # Not the bot itself
316
print(f"Welcome {member.name}!")
317
318
if activity.members_removed:
319
for member in activity.members_removed:
320
print(f"Goodbye {member.name}!")
321
```
322
323
### Working with Conversation References
324
325
```python
326
from botbuilder.schema import ConversationReference, Activity, ActivityTypes
327
328
# Create conversation reference for proactive messaging
329
conv_ref = ConversationReference(
330
activity_id="msg123",
331
user=ChannelAccount(id="user456", name="User"),
332
bot=ChannelAccount(id="bot789", name="Bot"),
333
conversation=ConversationAccount(id="conv123"),
334
channel_id="webchat",
335
service_url="https://webchat.botframework.com"
336
)
337
338
# Use reference to send proactive message
339
proactive_activity = Activity(
340
type=ActivityTypes.message,
341
text="This is a proactive message"
342
)
343
proactive_activity = proactive_activity.apply_conversation_reference(conv_ref)
344
```
345
346
### Error Handling
347
348
```python
349
from botbuilder.schema import ErrorResponse, ErrorResponseException
350
351
try:
352
# Bot Framework operation that might fail
353
pass
354
except ErrorResponseException as e:
355
error_response = e.error_response
356
if error_response and error_response.error:
357
print(f"Error {error_response.error.code}: {error_response.error.message}")
358
```