0
# Activity Handling
1
2
Core functionality for processing bot activities including messages, member additions, invokes, and other Bot Framework activity types. The ActivityHandler provides event-driven methods for handling different scenarios in conversational flows.
3
4
## Capabilities
5
6
### ActivityHandler Base Class
7
8
Main activity handler that provides the entry point for processing all Bot Framework activities. Inherits from the Bot class and implements turn-based activity processing with specialized methods for different activity types.
9
10
```python { .api }
11
class ActivityHandler:
12
async def on_turn(self, turn_context: TurnContext):
13
"""
14
Main entry point for processing activities.
15
16
Args:
17
turn_context (TurnContext): Context for the current conversation turn
18
"""
19
20
async def on_message_activity(self, turn_context: TurnContext):
21
"""
22
Handle message activities from users.
23
Override this method to process user messages.
24
25
Args:
26
turn_context (TurnContext): Context containing the message activity
27
"""
28
29
async def on_members_added_activity(self, members_added, turn_context: TurnContext):
30
"""
31
Handle when members are added to the conversation.
32
33
Args:
34
members_added (list): List of ChannelAccount objects for added members
35
turn_context (TurnContext): Context for the current turn
36
"""
37
38
async def on_members_removed_activity(self, members_removed, turn_context: TurnContext):
39
"""
40
Handle when members are removed from the conversation.
41
42
Args:
43
members_removed (list): List of ChannelAccount objects for removed members
44
turn_context (TurnContext): Context for the current turn
45
"""
46
47
async def on_invoke_activity(self, turn_context: TurnContext):
48
"""
49
Handle invoke activities (typically from cards or skills).
50
51
Args:
52
turn_context (TurnContext): Context containing the invoke activity
53
54
Returns:
55
InvokeResponse or None: Response to the invoke request
56
"""
57
58
async def on_adaptive_card_invoke(self, turn_context: TurnContext, invoke_value):
59
"""
60
Handle Adaptive Card invoke activities.
61
62
Args:
63
turn_context (TurnContext): Context for the current turn
64
invoke_value: Value from the Adaptive Card invoke
65
66
Returns:
67
InvokeResponse: Response to the Adaptive Card action
68
"""
69
70
async def on_signin_invoke(self, turn_context: TurnContext):
71
"""
72
Handle sign-in invoke activities.
73
74
Args:
75
turn_context (TurnContext): Context for the current turn
76
77
Returns:
78
InvokeResponse: Response to the sign-in invoke
79
"""
80
81
async def on_token_response_event(self, turn_context: TurnContext):
82
"""
83
Handle token response events from OAuth providers.
84
85
Args:
86
turn_context (TurnContext): Context containing the token response
87
"""
88
89
async def on_event_activity(self, turn_context: TurnContext):
90
"""
91
Handle event activities.
92
93
Args:
94
turn_context (TurnContext): Context containing the event activity
95
"""
96
97
async def on_unrecognized_activity_type(self, turn_context: TurnContext):
98
"""
99
Handle unrecognized activity types.
100
101
Args:
102
turn_context (TurnContext): Context containing the unrecognized activity
103
"""
104
105
async def on_message_reaction_activity(self, turn_context: TurnContext):
106
"""
107
Handle message reaction activities.
108
109
Args:
110
turn_context (TurnContext): Context containing the reaction activity
111
"""
112
113
async def on_reactions_added(self, message_reactions, turn_context: TurnContext):
114
"""
115
Handle when reactions are added to messages.
116
117
Args:
118
message_reactions (list): List of MessageReaction objects
119
turn_context (TurnContext): Context for the current turn
120
"""
121
122
async def on_reactions_removed(self, message_reactions, turn_context: TurnContext):
123
"""
124
Handle when reactions are removed from messages.
125
126
Args:
127
message_reactions (list): List of MessageReaction objects
128
turn_context (TurnContext): Context for the current turn
129
"""
130
131
async def on_message_update_activity(self, turn_context: TurnContext):
132
"""
133
Handle message update activities.
134
135
Args:
136
turn_context (TurnContext): Context containing the message update activity
137
"""
138
139
async def on_message_delete_activity(self, turn_context: TurnContext):
140
"""
141
Handle message delete activities.
142
143
Args:
144
turn_context (TurnContext): Context containing the message delete activity
145
"""
146
147
async def on_conversation_update_activity(self, turn_context: TurnContext):
148
"""
149
Handle conversation update activities.
150
151
Args:
152
turn_context (TurnContext): Context containing the conversation update activity
153
"""
154
155
async def on_end_of_conversation_activity(self, turn_context: TurnContext):
156
"""
157
Handle end of conversation activities.
158
159
Args:
160
turn_context (TurnContext): Context containing the end of conversation activity
161
"""
162
163
async def on_typing_activity(self, turn_context: TurnContext):
164
"""
165
Handle typing activities.
166
167
Args:
168
turn_context (TurnContext): Context containing the typing activity
169
"""
170
171
async def on_installation_update(self, turn_context: TurnContext):
172
"""
173
Handle installation update activities.
174
175
Args:
176
turn_context (TurnContext): Context containing the installation update activity
177
"""
178
```
179
180
### Bot Base Class
181
182
Abstract base class that ActivityHandler inherits from, providing the foundation for all bot implementations.
183
184
```python { .api }
185
class Bot:
186
async def on_turn(self, turn_context: TurnContext):
187
"""
188
Main turn processing method that must be implemented by derived classes.
189
190
Args:
191
turn_context (TurnContext): Context for the current conversation turn
192
"""
193
```
194
195
## Usage Examples
196
197
### Basic Message Handler
198
199
```python
200
from botbuilder.core import ActivityHandler, TurnContext, MessageFactory
201
202
class EchoBot(ActivityHandler):
203
async def on_message_activity(self, turn_context: TurnContext):
204
# Echo back the user's message
205
reply_text = f"You said: {turn_context.activity.text}"
206
await turn_context.send_activity(MessageFactory.text(reply_text))
207
208
async def on_members_added_activity(self, members_added, turn_context: TurnContext):
209
# Welcome new members
210
for member in members_added:
211
if member.id != turn_context.activity.recipient.id:
212
welcome_text = f"Welcome {member.name}!"
213
await turn_context.send_activity(MessageFactory.text(welcome_text))
214
```
215
216
### Handling Different Activity Types
217
218
```python
219
class MultiActivityBot(ActivityHandler):
220
async def on_message_activity(self, turn_context: TurnContext):
221
text = turn_context.activity.text.lower()
222
223
if "hello" in text:
224
await turn_context.send_activity(MessageFactory.text("Hello there!"))
225
elif "help" in text:
226
await turn_context.send_activity(MessageFactory.text("How can I help you?"))
227
else:
228
await turn_context.send_activity(MessageFactory.text("I didn't understand that."))
229
230
async def on_members_added_activity(self, members_added, turn_context: TurnContext):
231
for member in members_added:
232
if member.id != turn_context.activity.recipient.id:
233
await turn_context.send_activity(
234
MessageFactory.text("Welcome! Type 'help' for assistance.")
235
)
236
237
async def on_invoke_activity(self, turn_context: TurnContext):
238
# Handle Adaptive Card or other invoke activities
239
if turn_context.activity.name == "adaptiveCard/action":
240
return await self.on_adaptive_card_invoke(turn_context, turn_context.activity.value)
241
return None
242
243
async def on_adaptive_card_invoke(self, turn_context: TurnContext, invoke_value):
244
# Process Adaptive Card action
245
action_type = invoke_value.get("action", "")
246
247
if action_type == "submit":
248
await turn_context.send_activity(MessageFactory.text("Form submitted!"))
249
250
# Return response
251
from botbuilder.core import InvokeResponse
252
return InvokeResponse(status=200, body={"type": "continue"})
253
254
async def on_token_response_event(self, turn_context: TurnContext):
255
# Handle OAuth token response
256
token = turn_context.activity.value.get("token")
257
if token:
258
await turn_context.send_activity(MessageFactory.text("Authentication successful!"))
259
else:
260
await turn_context.send_activity(MessageFactory.text("Authentication failed."))
261
```
262
263
## Types
264
265
```python { .api }
266
class InvokeResponse:
267
"""Response for invoke activities."""
268
def __init__(self, status: int, body: object = None):
269
self.status = status
270
self.body = body
271
272
class MessageReaction:
273
"""Represents a reaction to a message."""
274
type: str
275
276
class ChannelAccount:
277
"""Represents a channel account (user or bot)."""
278
id: str
279
name: str
280
```