Registry /
web-framework / botbuilder-integration-aiohttp
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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.730s · 55.1MB
glibcpy 3.10–3.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.fixMigrate 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.fixEnsure 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.fixAlways 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.fixFamiliarize 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.
fixEnsure 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.
fixInstall `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.
fixReview 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.
fixUpdate 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.
fixAs 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.