Microsoft Teams

Python dependency commands on this page use a PM-prepared source checkout. After a dependency change, reactivate the checkout and restart Mibyan. Connect Mibyan to Microsoft Teams as a bot. Unlike Slack’s Socket Mode, Teams delivers messages by calling a public HTTPS webhook, so your instance needs a publicly reachable endpoint — either a dev tunnel (local dev) or a real domain (production). Need meeting summaries from Microsoft Graph events rather than normal bot conversations? Use the dedicated setup page: Teams Meetings.

Run mibyan gateway setup and pick Microsoft Teams for a guided walk-through.

How the Bot Responds

Context	Behavior
Personal chat (DM)	Bot responds to every message. No @mention needed.
Group chat	Bot only responds when @mentioned.
Channel	Bot only responds when @mentioned.

Teams delivers @mentions as regular messages with <at>BotName</at> tags, which Mibyan strips automatically before processing. Without resource-specific consent (RSC) Teams only delivers messages that @mention the bot, so no filtering is needed. Once the app manifest grants ChannelMessage.Read.Group or ChatMessage.Read.Chat, Teams delivers every message in the conversation — set require_mention: true (or TEAMS_REQUIRE_MENTION=true) so the bot only answers channel/group-chat messages that @mention it or reply to one of its own messages. Personal chats are never gated, and a gated message is dropped before its attachments are downloaded.

For source or local installs, include the Teams extra so the bundled adapter can import the Microsoft Teams SDK:

python -c "import pm; pm.sync_venv(['teams'], explicit=True)"

Step 1: Install the Teams CLI

The @microsoft/teams.cli automates bot registration — no Azure portal needed.

npm install -g @microsoft/teams.cli@preview
teams login

To verify your login and find your own AAD object ID (needed for TEAMS_ALLOWED_USERS):

teams status --verbose

Step 2: Expose the Webhook Port

Teams cannot deliver messages to localhost. For local development, use any tunnel tool to get a public HTTPS URL. The default port is 3978 — change it with TEAMS_PORT if needed.

# devtunnel (Microsoft)
devtunnel create mibyan-bot --allow-anonymous
devtunnel port create mibyan-bot -p 3978 --protocol http  # replace 3978 with TEAMS_PORT if changed
devtunnel host mibyan-bot

# ngrok
ngrok http 3978  # replace 3978 with TEAMS_PORT if changed

# cloudflared
cloudflared tunnel --url http://localhost:3978  # replace 3978 with TEAMS_PORT if changed

Copy the https:// URL from the output — you’ll use it in the next step. Leave the tunnel running while developing. The public tunnel URL uses HTTPS, but Mibyan’ local webhook listener uses plain HTTP. The tunnel terminates TLS and forwards HTTP to port 3978; do not configure the local tunnel port as HTTPS. For production, point your bot’s endpoint at your server’s public domain instead (see Production Deployment).

Step 3: Create the Bot

teams app create \
  --name "Mibyan" \
  --endpoint "https://<your-tunnel-url>/api/messages"

The CLI outputs your CLIENT_ID, CLIENT_SECRET, and TENANT_ID, plus an install link for Step 6. Save the client secret — it won’t be shown again.

Step 4: Configure Environment Variables

Add to ~/.mibyan/.env:

# Required
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>

# Restrict access to specific users (recommended)
# Use AAD object IDs from `teams status --verbose`
TEAMS_ALLOWED_USERS=<your-aad-object-id>

Step 5: Start the Gateway

Docker (must run from the directory that contains docker-compose.yml — usually your cloned mibyan-agent repo, not ~):

cd /path/to/mibyan-agent
mibyan_UID=$(id -u) mibyan_GID=$(id -g) docker compose up -d gateway

Native / systemd install (typical mibyan one-liner installer under ~/.mibyan/mibyan-agent):

mibyan gateway restart
# or foreground: mibyan gateway run

The Teams SDK is optional. When policy permits, the gateway requests the teams extra through PM on first start. PM prepares a complete environment instead of modifying the running interpreter. To request the extra explicitly from the prepared source checkout:

python -c "import pm; pm.sync_venv(['teams'], explicit=True)"

The default webhook port is 3978 (override with TEAMS_PORT). Check that it’s running:

curl http://localhost:3978/health   # should return: ok
# Docker:
docker logs -f mibyan
# Native:
mibyan gateway status -l

Look for:

[teams] Webhook server listening on * (all interfaces, IPv4+IPv6):3978/api/messages

Step 6: Install the App in Teams

teams app get <teamsAppId> --install-link

Open the printed link in your browser — it opens directly in the Teams client. After installing, send a direct message to your bot — it’s ready.

Configuration Reference

Environment Variables

Variable	Description
`TEAMS_CLIENT_ID`	Azure AD App (client) ID
`TEAMS_CLIENT_SECRET`	Azure AD client secret
`TEAMS_TENANT_ID`	Azure AD tenant ID
`TEAMS_ALLOWED_USERS`	Comma-separated AAD object IDs allowed to use the bot
`TEAMS_ALLOW_ALL_USERS`	Set `true` to skip the allowlist and allow anyone
`TEAMS_HOME_CHANNEL`	Conversation ID for cron/proactive message delivery
`TEAMS_HOME_CHANNEL_NAME`	Display name for the home channel
`TEAMS_PORT`	Webhook port (default: `3978`)
`TEAMS_REQUIRE_MENTION`	Set `true` to answer only @mentions / replies to the bot in channels and group chats (default: `false`; for apps with RSC message-read consent)

config.yaml

Alternatively, configure via ~/.mibyan/config.yaml:

platforms:
  teams:
    enabled: true
    extra:
      client_id: "your-client-id"
      client_secret: "your-secret"
      tenant_id: "your-tenant-id"
      port: 3978
    require_mention: false   # true once the app has RSC message-read consent

Features

Interactive Approval Cards

When the agent needs to run a potentially dangerous command, it sends an Adaptive Card with four buttons instead of asking you to type /approve:

Allow Once — approve this specific command
Allow Session — approve this pattern for the rest of the session
Always Allow — permanently approve this pattern
Deny — reject the command

Clicking a button resolves the approval inline and replaces the card with the decision.

Meeting Summary Delivery (Teams Meeting Pipeline)

When the Teams meeting pipeline plugin is enabled, this adapter also handles outbound delivery of meeting summaries — one Teams integration surface, not two. After a meeting’s transcript is summarized, the writer posts the summary into your chosen Teams target. Pipeline summary delivery is configured under the teams platform entry alongside the bot config:

platforms:
  teams:
    enabled: true
    extra:
      # existing bot config (client_id, client_secret, tenant_id, port) ...

      # Meeting summary delivery (only used when the teams_pipeline plugin is enabled)
      delivery_mode: "graph"       # or "incoming_webhook"
      # For delivery_mode: graph — pick ONE of:
      chat_id: "19:meeting_..."    # post into a Teams chat
      # team_id: "..."             # OR post into a channel
      # channel_id: "..."
      # access_token: "..."        # optional; falls back to MSGRAPH_* app credentials
      # For delivery_mode: incoming_webhook:
      # incoming_webhook_url: "https://outlook.office.com/webhook/..."

Mode	Use when	Trade-off
`incoming_webhook`	Simple “post a summary into this channel” with a static Teams-generated URL.	No reply threading, no reactions, shows as the webhook’s configured identity.
`graph`	Threaded channel posts or 1:1/group chat posts under the bot’s identity via Microsoft Graph.	Requires the Graph app registration with `ChannelMessage.Send` (channel) or `Chat.ReadWrite.All` (chat) application permissions.

If the teams_pipeline plugin is not enabled, these settings are inert — they only wire up when the pipeline runtime binds to the Graph webhook ingress.

Production Deployment

For a permanent server, terminate TLS at a reverse proxy and forward requests to the plain HTTP Mibyan listener, normally http://127.0.0.1:3978. Register the proxy’s public HTTPS endpoint with Teams:

teams app create \
  --name "Mibyan" \
  --endpoint "https://your-domain.com/api/messages"

If you’ve already created the bot and just need to update the endpoint:

teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages"

Make sure the public HTTPS endpoint is reachable from the internet and uses a valid TLS certificate. Teams rejects self-signed certificates. Keep the Mibyan listener behind the proxy; port 3978 does not serve HTTPS itself.

Troubleshooting

Problem	Solution
`Can't find a suitable configuration file` from `docker compose`	You are not in the repo that has `docker-compose.yml`, or you are on a native install — use `mibyan gateway restart` instead, or `cd` into the clone first
`requirements not met` / `Teams SDK missing` / `No adapter available for teams`	Request the `teams` extra through PM as shown above, then restart the gateway. Do not install into a system Python or mutate the Mibyan environment.
`health` endpoint works but bot doesn’t respond	Check that your tunnel is still running and the bot’s messaging endpoint matches the tunnel URL
Logs show `"UNKNOWN / HTTP/1.0" 400` when Teams sends a message	The tunnel or reverse proxy is forwarding HTTPS to Mibyan’ plain HTTP listener. Terminate TLS at the proxy and forward HTTP to port `3978`
`KeyError: 'teams'` in logs	Restart the container — this is fixed in the current version
Bot responds with auth errors	Verify `TEAMS_CLIENT_ID`, `TEAMS_CLIENT_SECRET`, and `TEAMS_TENANT_ID` are all set correctly
`No inference provider configured`	Check that `ANTHROPIC_API_KEY` (or another provider key) is set in `~/.mibyan/.env`
Bot receives messages but ignores them	Your AAD object ID may not be in `TEAMS_ALLOWED_USERS`. Run `teams status --verbose` to find it
Tunnel URL changes on restart	devtunnel URLs are persistent if you use a named tunnel (`devtunnel create mibyan-bot`). ngrok and cloudflared generate a new URL each run unless you have a paid plan — update the bot endpoint with `teams app update` when it changes
Teams shows “This bot is not responding”	The webhook returned an error. Check `docker logs mibyan` / `mibyan gateway status -l` for tracebacks
`[teams] Failed to connect` in logs	The SDK failed to authenticate. Double-check your credentials and that the tenant ID matches the account you used in `teams login`

Security

Always set TEAMS_ALLOWED_USERS with the AAD object IDs of authorized users. Without this, anyone who can find or install your bot can interact with it.Treat TEAMS_CLIENT_SECRET like a password — rotate it periodically via the Azure portal or Teams CLI.

Store credentials in ~/.mibyan/.env with permissions 600 (chmod 600 ~/.mibyan/.env)
The bot only accepts messages from users in TEAMS_ALLOWED_USERS; unauthorized messages are silently dropped
Your public endpoint (/api/messages) is authenticated by the Teams Bot Framework — requests without valid JWTs are rejected

تطبيق ديسكتوب

البداية

استخدام مبيان

الميزات

منصات المراسلة

التكاملات

الأدلة والدروس

دليل المطوّر

المرجع

How the Bot Responds

Step 1: Install the Teams CLI

Step 2: Expose the Webhook Port

Step 3: Create the Bot

Step 4: Configure Environment Variables

Step 5: Start the Gateway

Step 6: Install the App in Teams

Configuration Reference

Environment Variables

config.yaml

Features

Interactive Approval Cards

Meeting Summary Delivery (Teams Meeting Pipeline)

Production Deployment

Troubleshooting

Security

​How the Bot Responds

​Step 1: Install the Teams CLI

​Step 2: Expose the Webhook Port

​Step 3: Create the Bot

​Step 4: Configure Environment Variables

​Step 5: Start the Gateway

​Step 6: Install the App in Teams

​Configuration Reference

​Environment Variables

​config.yaml

​Features

​Interactive Approval Cards

​Meeting Summary Delivery (Teams Meeting Pipeline)

​Production Deployment

​Troubleshooting

​Security

​Related Docs

How the Bot Responds

Step 1: Install the Teams CLI

Step 2: Expose the Webhook Port

Step 3: Create the Bot

Step 4: Configure Environment Variables

Step 5: Start the Gateway

Step 6: Install the App in Teams

Configuration Reference

Environment Variables

config.yaml

Features

Interactive Approval Cards

Meeting Summary Delivery (Teams Meeting Pipeline)

Production Deployment

Troubleshooting

Security

Related Docs