Microsoft Teams API

2.0.0 verified Sat May 09 auth: no python

Official Python SDK for building Microsoft Teams apps, bots, and message extensions. Current version 2.0.0 (stable), requiring Python 3.12+. The v2.0.0 release introduces a new namespace `microsoft_teams` (replacing `microsoft.teams`), proactive threading support, and sovereign cloud endpoints. Release cadence is irregular, with alpha releases leading to the stable v2.0.0.

pip install microsoft-teams-api

Common errors

error ModuleNotFoundError: No module named 'microsoft.teams' ↓

cause Imports use old namespace from v1.x or v2.0.0 alphas.

fix

Change imports to use microsoft_teams (e.g., from microsoft_teams import TeamsApp).

error TypeError: 'coroutine' object is not callable ↓

cause Message handler not defined as async or event handlers not awaited.

fix

Ensure all event handlers are declared with async def and use await when calling async methods.

error AttributeError: 'TeamsApp' object has no attribute 'on_message' ↓

cause Decorator usage is wrong; on_message expects a function argument.

fix

Use @app.on_message decorator on an async function, not on the TeamsApp instance.

error ValueError: Cannot connect to service URL: https://smba.trafficmanager.net/amer/ ↓

cause Missing or incorrect SERVICE_URL environment variable for sovereign clouds.

fix

Set SERVICE_URL appropriate to your cloud (e.g., 'https://smba.infra.gccustom.microsoft.com' for GCCH).

Warnings

breaking Namespace changed from `microsoft.teams` to `microsoft_teams` in v2.0.0. All import paths must be updated. ↓

fix Replace all imports from `microsoft.teams.*` with `microsoft_teams.*`.

breaking HttpPlugin replaced by HttpServer and HttpServerAdapter. Existing HttpPlugin code will break. ↓

fix Use HttpServer and HttpServerAdapter from microsoft_teams.server.

gotcha Python requirement is 3.12+ (not 3.11 or lower). Installation will fail on older Python versions. ↓

fix Ensure Python >=3.12 is used.

deprecated Custom logger removed; use standard logging library. ↓

fix Replace custom logger calls with import logging.

gotcha Sovereign cloud endpoints (GCCH, DoD, China) require explicit configuration. Default endpoint only works for global Azure. ↓

fix Initialize TeamsApp with `cloud='GCCH'` or `cloud='DoD'` for those environments.

Imports

TeamsApp
wrong
```
from microsoft.teams import TeamsApp
```
correct
```
from microsoft_teams import TeamsApp
```
Renamed in v2.0.0. Old namespace deprecated with warning in alpha, removed in stable.

BotBuilderPlugin

from microsoft_teams.plugins import BotBuilderPlugin

Quickstart

Minimal Teams bot using the new microsoft_teams namespace.

import os
from microsoft_teams import TeamsApp

# Initialize the app
app = TeamsApp(
    app_id=os.environ.get("TEAMS_APP_ID", ""),
    app_password=os.environ.get("TEAMS_APP_PASSWORD", ""),
)

# Register a simple message handler
@app.on_message
async def on_message(context, activity):
    await context.reply("Hello from Teams SDK!")

# Start the bot
app.run()