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.95 runs
installs and imports cleanly · install 0.0s · import 0.828s · 25.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.728s · 26MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Activity
✓ from botbuilder.schema import Activity
Commonly imported for defining bot messages and events.
ConversationAccount
✓ from botbuilder.schema import ConversationAccount
Used to represent a conversation's identity.
ChannelAccount
✓ from botbuilder.schema import ChannelAccount
Represents the identity of a user or bot in a channel.
This quickstart demonstrates how to instantiate core schema objects like `Activity`, `ConversationAccount`, and `ChannelAccount`, which are fundamental for representing messages and participants in the Bot Framework.
import datetime
from botbuilder.schema import Activity, ActivityTypes, ConversationAccount, ChannelAccount
# Create a sample conversation account
conversation = ConversationAccount(
id="conversationId123",
conversation_type="personal",
is_group=False,
tenant_id="tenantId123"
)
# Create a sample channel account for the user
user = ChannelAccount(
id="userId123",
name="Test User",
role="user"
)
# Create a sample channel account for the bot
bot = ChannelAccount(
id="botId456",
name="Test Bot",
role="bot"
)
# Create an Activity object
activity = Activity(
type=ActivityTypes.message,
id="messageId789",
timestamp=datetime.datetime.now(datetime.timezone.utc),
service_url="https://example.azurewebsites.net/api/messages",
channel_id="emulator",
conversation=conversation,
from_property=user, # 'from' is a reserved keyword in Python, hence from_property
recipient=bot,
text="Hello from the botbuilder-schema quickstart!",
locale="en-US"
)
print(f"Created Activity of type: {activity.type}")
print(f"Activity text: {activity.text}")
print(f"From: {activity.from_property.name} ({activity.from_property.id})")
print(f"To: {activity.recipient.name} ({activity.recipient.id})")
Debug
Known issues
breakingEnd-of-Life (EOL) Status: The `botbuilder-schema` library is part of the Bot Framework Python SDK, which has officially reached End-of-Life (EOL) with version 4.17.1. It will no longer receive updates, maintenance, or support. Existing applications will not be immediately disrupted, but new development or seeking support is highly discouraged.fixFor new projects, consider the Microsoft 365 Agents SDK or alternative bot development frameworks. Existing users should avoid upgrading beyond 4.17.1 and plan for migration if future compatibility or features are critical.
affects: 4.17.1 onwards
gotchaPython 3.8+ Requirement: Beginning with SDK version 4.15.0, the broader Bot Framework SDK (of which `botbuilder-schema` is a component) requires Python 3.8 or newer due to its `aiohttp` dependency (version 3.9+). Deployments using Python 3.7 or earlier will encounter compatibility issues.fixEnsure your development and deployment environments are running Python 3.8 or a later supported version.
affects: 4.15.0 onwards
gotchaMissing Schema for Newer Features: As an EOL library, `botbuilder-schema` will not receive updates for new Microsoft Teams or Bot Framework features. If your bot needs to interact with recently introduced invoke types (e.g., 'config/fetch', 'config/submit' added in 4.17.0) or other new schema elements, older `botbuilder-schema` versions might lack the necessary definitions, leading to runtime errors or unexpected behavior when deserializing activities.fixReview the specific features you intend to use and cross-reference with the `botbuilder-schema` versions. If critical schema elements are missing, consider alternatives as the library will not be updated.
affects: Prior to 4.17.0 (for specific Teams invoke types), and all versions (for future features)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'botbuilder_schema'
The `botbuilder-schema` package is not installed in your Python environment or the environment where your code is running.
fixInstall the package using pip: `pip install botbuilder-schema`
ImportError: cannot import name 'Activity' from 'botbuilder.schema'
The `Activity` class, or another specified class, could not be found within the `botbuilder.schema` package. This usually indicates a typo in the import statement or an issue with the package installation.
fixEnsure the package is correctly installed (`pip install botbuilder-schema`) and that the import statement `from botbuilder.schema import Activity` (or the specific class you are trying to import) is spelled correctly and matches the library's API.
AttributeError: 'Activity' object has no attribute 'value'
You are attempting to access an attribute (e.g., `value`, `text`, `channel_id`) on an `Activity` object that either does not exist, is misspelled, or is not populated in that specific `Activity` instance for its `ActivityTypes`.
fixConsult the `botbuilder.schema.Activity` documentation to verify the correct attribute names and ensure the attribute is expected to be present for the particular `Activity.type` you are processing. Use `hasattr(activity, 'attribute_name')` or check `activity.type` before accessing specific attributes.
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
An invalid, empty, or non-JSON formatted string was provided to a JSON parsing function (e.g., `json.loads()`) when attempting to deserialize an incoming message into a `botbuilder.schema.Activity` object. This often happens if the raw input from the bot channel is malformed or empty.
fixEnsure that the input string you are attempting to deserialize is valid JSON. This might involve debugging the raw payload received from the bot connector or ensuring any external data sources provide correct JSON.
Upgrade
Version history
4.17.1latest on PyPI · released Jan 5, 2026
Audit
Dependencies
No dependency data recorded yet.