Registry / web-framework / botbuilder-integration-aiohttp

botbuilder-integration-aiohttp

JSON →
library4.17.1pypypi✓ verified 85d ago

This library provides the necessary components to integrate a conversational AI bot, built with the Microsoft Bot Framework Python SDK, into an aiohttp web application. As of version 4.17.1, the entire Bot Framework Python SDK, including this library, has reached End-of-Life (EOL). It is no longer actively maintained, supported, or receiving updates, and new development should avoid its use.

pip install botbuilder-integration-aiohttp
INSTALL
IMPORT
SIG · BOTBUILDER-INTEGRA
B
botbuilder-integration-aiohttp
web-frameworkpythonv4.17.1
Install
6.5s avg
Import
1639ms
Disk
56MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.17.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 1.730s · 55.1MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 6.5s · import 1.548s · 57MB
56MB installed
● package 56MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CloudAdapter
from botbuilder.integration.aiohttp import CloudAdapter
The primary adapter for integrating Bot Framework with aiohttp.
ConfigurationBotFrameworkAuthentication
from botbuilder.integration.aiohttp import ConfigurationBotFrameworkAuthentication
Used for configuring authentication credentials for the bot adapter.
aiohttp_error_middleware
from botbuilder.core.integration import aiohttp_error_middleware
A utility middleware for handling errors within the aiohttp integration.

This quickstart sets up a basic 'echo' bot using `botbuilder-integration-aiohttp` to expose a messaging endpoint via an `aiohttp` web server. It demonstrates how to initialize the `CloudAdapter` with authentication, define a simple `ActivityHandler` (EchoBot), and route incoming messages. To run this, save it as `app.py` and ensure `MicrosoftAppId` and `MicrosoftAppPassword` are set in your environment (or left empty for local development with the Bot Framework Emulator). Connect to `http://localhost:3978/api/messages` using the Bot Framework Emulator.

import os import sys import traceback from datetime import datetime from http import HTTPStatus from aiohttp import web from aiohttp.web import Request, Response, json_response from botbuilder.core import ( ActivityHandler, TurnContext, ) from botbuilder.core.integration import aiohttp_error_middleware from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication from botbuilder.schema import Activity, ActivityTypes # Configuration class DefaultConfig: APP_ID = os.environ.get('MicrosoftAppId', '') APP_PASSWORD = os.environ.get('MicrosoftAppPassword', '') PORT = 3978 CONFIG = DefaultConfig() # Create adapter. See https://aka.ms/about-bot-adapter to learn more about how bots work. ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG)) # Catch-all for errors. async def on_error(context: TurnContext, error: Exception): print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr) traceback.print_exc() await context.send_activity("The bot encountered an error or bug.") await context.send_activity("To continue to run this bot, please fix the bot source code.") if context.activity.channel_id == "emulator": trace_activity = Activity( label="TurnError", name="on_turn_error Trace", timestamp=datetime.utcnow(), type=ActivityTypes.trace, value=f"{error}", value_type="https://www.botframework.com/schemas/error", ) await context.send_activity(trace_activity) ADAPTER.on_turn_error = on_error # Define your bot logic class EchoBot(ActivityHandler): async def on_message_activity(self, turn_context: TurnContext): await turn_context.send_activity(f"You said: {turn_context.activity.text}") async def on_members_added_activity(self, members_added: [ChannelAccount], turn_context: TurnContext): for member in members_added: if member.id != turn_context.activity.recipient.id: await turn_context.send_activity("Hello and welcome!") BOT = EchoBot() # Listen for incoming requests on /api/messages async def messages(req: Request) -> Response: if "application/json" in req.headers["Content-Type"]: body = await req.json() else: return Response(status=HTTPStatus.UNSUPPORTED_MEDIA_TYPE) activity = Activity().deserialize(body) auth_header = req.headers["Authorization"] if "Authorization" in req.headers else "" try: response = await ADAPTER.process_activity(activity, auth_header, BOT.on_turn) if response: return json_response(data=response.body, status=response.status) return Response(status=HTTPStatus.OK) except Exception as e: raise e app = web.Application(middlewares=[aiohttp_error_middleware]) app.router.add_post("/api/messages", messages) if __name__ == "__main__": try: web.run_app(app, host="localhost", port=CONFIG.PORT) except Exception as e: print(f"Error starting server: {e}")
Debug
Known issues
breakingThe Microsoft Bot Framework Python SDK, including `botbuilder-integration-aiohttp`, has reached End-of-Life (EOL) with version 4.17.1. It is no longer actively maintained, supported, or receiving updates. New development should avoid this library, and existing projects should consider migration.
fix
Migrate to alternative solutions for building conversational agents, such as the Microsoft 365 Agents SDK or other active bot development frameworks. Do not start new projects with this SDK. Support tickets will no longer be serviced as of December 31, 2025.
affects: 4.17.1 and newer
gotchaAs of SDK version 4.15.0, the underlying `aiohttp` dependency (version 3.9+) requires Python 3.8 or newer. Bots deployed on Python 3.7 or older will encounter dependency conflicts or runtime errors.
fix
Ensure your development and deployment environments are using Python 3.8 or a later compatible version.
affects: 4.15.0 to 4.17.1
gotchaAuthentication is crucial for secure bots. Bots typically require `MicrosoftAppId` and `MicrosoftAppPassword` for production deployments. Running locally without these credentials might require specific adapter configurations to disable authentication checks, which is not recommended for production.
fix
Always configure `MicrosoftAppId` and `MicrosoftAppPassword` securely in production environments. For local testing with the Bot Framework Emulator, these can sometimes be left empty, but be aware of the security implications.
affects: All versions
gotchaThe library is built on `asyncio`. All bot logic, especially I/O operations and callbacks within `ActivityHandler` methods, must be `async` and properly `await`ed. Failure to do so can lead to deadlocks, unresponsive bots, or silent failures.
fix
Familiarize yourself with Python's `asyncio` framework. Ensure all methods interacting with `TurnContext` or performing network/disk I/O are `async def` and called using `await`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'botbuilder'
The `botbuilder` package or its submodules, including `botbuilder-integration-aiohttp`, are not installed or are not accessible in the Python environment where the code is being run. This can also occur if the virtual environment is not activated or if there's a path issue.
fix
Ensure the necessary packages are installed using pip: `pip install botbuilder-core botbuilder-schema botbuilder-integration-aiohttp`. Verify that your Python environment (e.g., virtual environment) is correctly activated and configured.
ModuleNotFoundError: No module named 'aiohttp'
The `aiohttp` library, a core dependency for `botbuilder-integration-aiohttp`, is either not installed, or there's a version incompatibility, particularly with older Python environments (e.g., Python 3.7 or earlier) not meeting `aiohttp`'s requirements.
fix
Install `aiohttp` explicitly: `pip install aiohttp`. If the issue persists, check your Python version; `aiohttp` versions 3.9+ require Python 3.8 or newer. Consider upgrading your Python environment if it's older.
TypeError: __init__() missing 1 required positional argument
This error typically occurs during the instantiation of classes like `BotFrameworkAdapter` or `CloudAdapter` when a required argument for their constructor is not provided. This can happen due to incorrect migration from `BotFrameworkAdapter` to `CloudAdapter` or simply missing parameters.
fix
Review the constructor signature for the adapter you are using (e.g., `BotFrameworkAdapter` or `CloudAdapter`) and ensure all mandatory arguments, such as `settings` or `authentication` configurations, are passed during instantiation. For `CloudAdapter`, ensure `ConfigurationBotFrameworkAuthentication` is correctly provided.
`BotFrameworkAdapter` is deprecated. Use `CloudAdapter` instead.
The `BotFrameworkAdapter` class has been officially deprecated in favor of `CloudAdapter` since `botbuilder@4.16.0`. While not a runtime error itself, ignoring this warning can lead to issues or missed functionality, and migration is recommended for continued development.
fix
Update your bot's code to use `CloudAdapter` instead of `BotFrameworkAdapter`. This involves changing the import statement and potentially adjusting the adapter's initialization parameters to align with `CloudAdapter`'s constructor and authentication requirements.
Building wheel for aiohttp (...) did not run successfully.
This error indicates a problem during the installation of `aiohttp`, often due to incompatibility with newer Python versions (e.g., Python 3.12) where `aiohttp`'s underlying C extensions might not compile correctly.
fix
As the `botbuilder-integration-aiohttp` library is EOL, the most robust fix is to migrate to the Microsoft 365 Agents SDK or another active bot framework. If migration is not immediately possible, consider using an older Python version (e.g., Python 3.8 or 3.9) that is known to be compatible with the specific `aiohttp` and `botbuilder` versions you are using.
Upgrade
Version history
4.17.1latest on PyPI · released Jan 5, 2026
Audit
Dependencies
aiohttprequiredCore web framework for integration. Version 3.9+ requires Python 3.8+ as of SDK 4.15.0.
botbuilder-corerequiredProvides core abstractions like ActivityHandler and TurnContext, which are fundamental for bot logic.
botframework-connectorrequiredHandles communication with the Bot Framework service.
Agent activity
28 hits · last 30 days
node
24
Amazon
1
OpenAI (training)
1
Resources