0
# Bot Adapters
1

2
Adapter classes that connect bot logic to various communication channels and handle the low-level details of activity processing, authentication, and response management. Includes the main BotFrameworkAdapter and specialized adapters.
3

4
## Capabilities
5

6
### BotFrameworkAdapter
7

8
Main adapter for Bot Framework integration that handles activity processing, authentication, OAuth token management, and connector client creation for communicating with Bot Framework channels.
9

10
```python { .api }
11
class BotFrameworkAdapter:
12
    def __init__(self, settings: BotFrameworkAdapterSettings):
13
        """
14
        Initialize adapter with Bot Framework settings.
15
        
16
        Args:
17
            settings (BotFrameworkAdapterSettings): Configuration settings
18
        """
19
    
20
    async def process_activity(self, req, auth_header: str, logic):
21
        """
22
        Process incoming activity from Bot Framework channels.
23
        
24
        Args:
25
            req: HTTP request containing the activity
26
            auth_header (str): Authorization header from the request  
27
            logic: Bot logic function to execute
28
            
29
        Returns:
30
            Response object for the HTTP framework
31
        """
32
    
33
    async def send_activities(self, context: TurnContext, activities):
34
        """
35
        Send multiple activities to the channel.
36
        
37
        Args:
38
            context (TurnContext): Turn context
39
            activities (list): List of Activity objects to send
40
            
41
        Returns:
42
            list: List of ResourceResponse objects
43
        """
44
    
45
    async def update_activity(self, context: TurnContext, activity):
46
        """
47
        Update an existing activity.
48
        
49
        Args:
50
            context (TurnContext): Turn context
51
            activity (Activity): Activity to update
52
            
53
        Returns:
54
            ResourceResponse: Response from the update operation
55
        """
56
    
57
    async def delete_activity(self, context: TurnContext, reference):
58
        """
59
        Delete an activity.
60
        
61
        Args:
62
            context (TurnContext): Turn context
63
            reference (ConversationReference): Reference to activity to delete
64
            
65
        Returns:
66
            ResourceResponse: Response from the delete operation
67
        """
68
    
69
    async def continue_conversation(self, reference, callback, bot_id=None, claims_identity=None, audience=None):
70
        """
71
        Continue a conversation with a proactive message.
72
        
73
        Args:
74
            reference (ConversationReference): Conversation reference
75
            callback: Callback function to execute
76
            bot_id (str, optional): Bot ID
77
            claims_identity (ClaimsIdentity, optional): Claims identity
78
            audience (str, optional): Audience for the conversation
79
        """
80
    
81
    async def get_user_token(self, context: TurnContext, connection_name: str, magic_code: str = None, oauth_app_credentials=None):
82
        """
83
        Get OAuth token for user.
84
        
85
        Args:
86
            context (TurnContext): Turn context
87
            connection_name (str): OAuth connection name
88
            magic_code (str, optional): Magic code from OAuth provider
89
            oauth_app_credentials (optional): OAuth app credentials
90
            
91
        Returns:
92
            TokenResponse: Token response or None if no token
93
        """
94
    
95
    async def sign_out_user(self, context: TurnContext, connection_name: str, user_id: str = None, oauth_app_credentials=None):
96
        """
97
        Sign out user from OAuth provider.
98
        
99
        Args:
100
            context (TurnContext): Turn context
101
            connection_name (str): OAuth connection name
102
            user_id (str, optional): User ID to sign out
103
            oauth_app_credentials (optional): OAuth app credentials
104
        """
105
    
106
    async def get_oauth_sign_in_link(self, context: TurnContext, connection_name: str, oauth_app_credentials=None):
107
        """
108
        Get OAuth sign-in link.
109
        
110
        Args:
111
            context (TurnContext): Turn context
112
            connection_name (str): OAuth connection name
113
            oauth_app_credentials (optional): OAuth app credentials
114
            
115
        Returns:
116
            str: Sign-in URL
117
        """
118
    
119
    async def create_connector_client(self, service_url: str, identity=None, audience: str = None):
120
        """
121
        Create connector client for communicating with Bot Framework.
122
        
123
        Args:
124
            service_url (str): Service URL for the channel
125
            identity (optional): Claims identity
126
            audience (str, optional): Audience for the client
127
            
128
        Returns:
129
            ConnectorClient: Configured connector client
130
        """
131
    
132
    async def exchange_token(self, turn_context: TurnContext, connection_name: str, user_id: str, exchange_request):
133
        """
134
        Exchange token with OAuth provider.
135
        
136
        Args:
137
            turn_context (TurnContext): Turn context
138
            connection_name (str): OAuth connection name
139
            user_id (str): User ID
140
            exchange_request: Token exchange request
141
            
142
        Returns:
143
            TokenResponse: Exchange response
144
        """
145
```
146

147
### BotFrameworkAdapterSettings
148

149
Configuration settings for BotFrameworkAdapter including app credentials, OAuth endpoints, and channel authentication settings.
150

151
```python { .api }
152
class BotFrameworkAdapterSettings:
153
    def __init__(self, app_id: str = None, app_password: str = None, channel_auth_tenant: str = None, 
154
                 oauth_endpoint: str = None, open_id_metadata: str = None, channel_service: str = None,
155
                 validate_authority: bool = True, to_channel_from_bot_login_url: str = None,
156
                 to_channel_from_bot_oauth_scope: str = None, to_bot_from_channel_token_issuer: str = None,
157
                 to_bot_from_channel_open_id_metadata_url: str = None, to_bot_from_emulator_open_id_metadata_url: str = None,
158
                 caller_id: str = None, authority: str = None):
159
        """
160
        Initialize Bot Framework adapter settings.
161
        
162
        Args:
163
            app_id (str, optional): Microsoft App ID
164
            app_password (str, optional): Microsoft App Password
165
            channel_auth_tenant (str, optional): Channel auth tenant
166
            oauth_endpoint (str, optional): OAuth endpoint URL
167
            open_id_metadata (str, optional): OpenID metadata URL
168
            channel_service (str, optional): Channel service URL
169
            validate_authority (bool): Whether to validate authority
170
            to_channel_from_bot_login_url (str, optional): Login URL for bot-to-channel
171
            to_channel_from_bot_oauth_scope (str, optional): OAuth scope for bot-to-channel
172
            to_bot_from_channel_token_issuer (str, optional): Token issuer for channel-to-bot
173
            to_bot_from_channel_open_id_metadata_url (str, optional): OpenID metadata for channel-to-bot
174
            to_bot_from_emulator_open_id_metadata_url (str, optional): OpenID metadata for emulator
175
            caller_id (str, optional): Caller ID
176
            authority (str, optional): Authority URL
177
        """
178
```
179

180
### BotAdapter Base Class
181

182
Abstract base class that defines the interface for all bot adapters, providing core functionality for activity processing, middleware management, and conversation handling.
183

184
```python { .api }
185
class BotAdapter:
186
    # Constants for turn context services
187
    BOT_IDENTITY_KEY: str = "BotIdentity"
188
    BOT_OAUTH_SCOPE_KEY: str = "BotOAuthScope"
189
    BOT_CONNECTOR_CLIENT_KEY: str = "ConnectorClient"
190
    
191
    async def send_activities(self, context: TurnContext, activities):
192
        """
193
        Send multiple activities. Must be implemented by derived classes.
194
        
195
        Args:
196
            context (TurnContext): Turn context
197
            activities (list): Activities to send
198
            
199
        Returns:
200
            list: List of ResourceResponse objects
201
        """
202
    
203
    async def update_activity(self, context: TurnContext, activity):
204
        """
205
        Update an activity. Must be implemented by derived classes.
206
        
207
        Args:
208
            context (TurnContext): Turn context
209
            activity (Activity): Activity to update
210
            
211
        Returns:
212
            ResourceResponse: Update response
213
        """
214
    
215
    async def delete_activity(self, context: TurnContext, reference):
216
        """
217
        Delete an activity. Must be implemented by derived classes.
218
        
219
        Args:
220
            context (TurnContext): Turn context
221
            reference (ConversationReference): Activity reference
222
        """
223
    
224
    def use(self, middleware):
225
        """
226
        Register middleware with the adapter.
227
        
228
        Args:
229
            middleware (Middleware): Middleware to register
230
            
231
        Returns:
232
            BotAdapter: Self for method chaining
233
        """
234
    
235
    async def continue_conversation(self, reference, callback, bot_id=None, claims_identity=None, audience=None):
236
        """
237
        Continue a conversation.
238
        
239
        Args:
240
            reference (ConversationReference): Conversation reference
241
            callback: Callback function
242
            bot_id (str, optional): Bot ID
243
            claims_identity (optional): Claims identity
244
            audience (str, optional): Audience
245
        """
246
    
247
    async def run_pipeline(self, context: TurnContext, callback):
248
        """
249
        Run the middleware pipeline.
250
        
251
        Args:
252
            context (TurnContext): Turn context
253
            callback: Bot logic callback
254
        """
255
```
256

257
### CloudAdapterBase
258

259
Abstract base class for cloud-based adapters that provides additional functionality for cloud deployment scenarios and streaming connections.
260

261
```python { .api }
262
class CloudAdapterBase(BotAdapter):
263
    async def process_activity(self, req, auth_header: str, logic):
264
        """
265
        Process incoming activity. Must be implemented by derived classes.
266
        
267
        Args:
268
            req: HTTP request
269
            auth_header (str): Authorization header
270
            logic: Bot logic function
271
        """
272
    
273
    async def create_connector_client(self, service_url: str, identity=None, audience: str = None):
274
        """
275
        Create connector client. Must be implemented by derived classes.
276
        
277
        Args:
278
            service_url (str): Service URL
279
            identity (optional): Claims identity
280
            audience (str, optional): Audience
281
            
282
        Returns:
283
            ConnectorClient: Connector client
284
        """
285
```
286

287
## Usage Examples
288

289
### Basic Adapter Setup
290

291
```python
292
from botbuilder.core import BotFrameworkAdapter, BotFrameworkAdapterSettings
293
from botbuilder.core import ActivityHandler
294

295
# Create adapter settings
296
settings = BotFrameworkAdapterSettings(
297
    app_id="your-app-id",
298
    app_password="your-app-password"
299
)
300

301
# Create adapter
302
adapter = BotFrameworkAdapter(settings)
303

304
# Create bot
305
class EchoBot(ActivityHandler):
306
    async def on_message_activity(self, turn_context):
307
        await turn_context.send_activity(f"You said: {turn_context.activity.text}")
308

309
bot = EchoBot()
310
```
311

312
### Processing Activities with Error Handling
313

314
```python
315
async def process_request(req):
316
    try:
317
        # Extract auth header
318
        auth_header = req.headers.get("Authorization", "")
319
        
320
        # Process the activity
321
        response = await adapter.process_activity(req, auth_header, bot.on_turn)
322
        return response
323
        
324
    except Exception as e:
325
        print(f"Error processing activity: {e}")
326
        return {"status": 500, "body": "Internal server error"}
327
```
328

329
### Middleware Registration
330

331
```python
332
from botbuilder.core import AutoSaveStateMiddleware, ShowTypingMiddleware
333

334
# Add middleware to adapter
335
adapter.use(ShowTypingMiddleware(delay=0.5, period=2.0))
336
adapter.use(AutoSaveStateMiddleware([conversation_state, user_state]))
337
```
338

339
### Proactive Messaging
340

341
```python
342
async def send_proactive_message(conversation_reference, message_text):
343
    async def proactive_callback(turn_context):
344
        await turn_context.send_activity(MessageFactory.text(message_text))
345
    
346
    await adapter.continue_conversation(
347
        conversation_reference,
348
        proactive_callback
349
    )
350
```
351

352
## Types
353

354
```python { .api }
355
class ConversationReference:
356
    """Reference to a conversation for proactive messaging."""
357
    activity_id: str
358
    user: ChannelAccount
359
    bot: ChannelAccount
360
    conversation: ConversationAccount
361
    channel_id: str
362
    service_url: str
363

364
class ResourceResponse:
365
    """Response from Bot Framework operations."""
366
    id: str
367

368
class TokenResponse:
369
    """OAuth token response."""
370
    channel_id: str
371
    connection_name: str
372
    token: str
373
    expiration: str
374

375
class ConnectorClient:
376
    """Client for Bot Framework Connector API."""
377
    pass
378
```