Microsoft Bot Framework Bot Builder SDK for Python (Connector)

4.17.1 · abandoned · verified Sun Apr 12

The `botframework-connector` library, part of the Microsoft Bot Framework Bot Builder SDK for Python (version 4.17.1), provides the necessary components for a bot to communicate directly with the Bot Connector service. This allows for sending and receiving activities (messages, events, etc.) to users across various channels configured in the Bot Framework Portal. However, the Bot Framework Python SDK reached its end-of-life with the 4.17.1 release and will no longer be updated, maintained, or supported through service tickets in the Azure portal. For new agent development, Microsoft recommends considering the Microsoft 365 Agents SDK.

Warnings

breaking The Bot Framework Python SDK, including `botframework-connector`, has reached its End-of-Life (EOL) with version 4.17.1. It will no longer receive updates, maintenance, or support through Azure portal service tickets.
Fix: Migrate to the Microsoft 365 Agents SDK or another supported framework for new development. Existing bots will continue to function but without official support or updates. Support tickets will no longer be serviced as of December 31, 2025.
breaking Beginning with SDK version 4.15.0, `aiohttp` package version 3.9+ (a core dependency) now requires Python 3.8 or newer. Bots running on Python 3.7 or earlier will encounter compatibility issues.
Fix: Upgrade your Python environment to Python 3.8 or a newer compatible version. This includes updating the Python version in your Azure App Service if deployed.
gotcha Proper authentication using `MicrosoftAppId` and `MicrosoftAppPassword` is critical for production bots. Misconfiguration or absence of these credentials will prevent your bot from communicating with the Bot Connector Service.
Fix: Always set `MicrosoftAppId` and `MicrosoftAppPassword` as environment variables for your bot. For local development, these might be optional for some configurations, but they are mandatory for production deployments.
gotcha The `botframework-connector` library is typically used for low-level interactions with the Bot Connector Service, such as sending proactive messages. For a complete bot experience (handling incoming activities, managing turn context, dialogs), you would usually integrate it with `botbuilder-core` and its `BotFrameworkAdapter`.
Fix: Understand the scope of `botframework-connector`. If building a complete conversational bot, combine it with `botbuilder-core` components to handle the full lifecycle of a conversation.

Install

pip install botframework-connector Latest Release

Imports

ConnectorClient

from botframework.connector import ConnectorClient

MicrosoftAppCredentials

from botframework.connector.auth import MicrosoftAppCredentials

Activity
```
from botbuilder.schema import Activity
```
Schema objects like Activity, ActivityTypes, ChannelAccount, and ConversationParameters reside in the `botbuilder.schema` package, not directly in `botframework.connector`.

ActivityTypes

from botbuilder.schema import ActivityTypes

ChannelAccount

from botbuilder.schema import ChannelAccount

ConversationParameters

from botbuilder.schema import ConversationParameters

Quickstart

This example demonstrates how to use `botframework-connector` to directly send an activity (a 'Hello World' message) to a user in a specific channel. It initializes a `ConnectorClient` with Microsoft App Credentials (typically set via environment variables) and then creates a conversation to send a message. This library focuses on the low-level interaction with the Bot Connector Service, primarily for proactive messaging or direct API calls.

import os
from botbuilder.schema import Activity, ActivityTypes, ChannelAccount, ConversationParameters
from botframework.connector import ConnectorClient
from botframework.connector.auth import MicrosoftAppCredentials

APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
SERVICE_URL = os.environ.get("BotServiceUrl", "https://slack.botframework.com") # Replace with your bot's service URL
CHANNEL_ID = os.environ.get("ChannelId", "slack") # Example channel ID, replace as needed
BOT_ID = os.environ.get("BotId", "your_bot_id") # Replace with your bot's ID
RECIPIENT_ID = os.environ.get("RecipientId", "user_id") # Replace with the recipient's user ID

if not APP_ID or not APP_PASSWORD:
    print("WARNING: MicrosoftAppId and MicrosoftAppPassword environment variables not set. Authentication might fail for production scenarios.")

try:
    credentials = MicrosoftAppCredentials(APP_ID, APP_PASSWORD)
    connector = ConnectorClient(credentials, base_url=SERVICE_URL)

    conversation_parameters = ConversationParameters(
        is_group=False,
        bot=ChannelAccount(id=BOT_ID),
        members=[ChannelAccount(id=RECIPIENT_ID)],
        # channel_data={"tenantId": "your_tenant_id"} # Optional: Add tenant ID for Teams, etc. if needed
    )
    conversation = connector.conversations.create_conversation(conversation_parameters)

    activity = Activity(
        type=ActivityTypes.message,
        channel_id=CHANNEL_ID,
        recipient=ChannelAccount(id=RECIPIENT_ID),
        from_property=ChannelAccount(id=BOT_ID),
        text='Hello World from botframework-connector!'
    )
    response = connector.conversations.send_to_conversation(conversation.id, activity)
    print(f"Message sent. Activity ID: {response.id}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure APP_ID, APP_PASSWORD, SERVICE_URL, BOT_ID, RECIPIENT_ID are correctly configured and accessible.")

view raw JSON →