vercel · dancer · Apr 29, 2026 · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026
@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@chat-adapter/teams)](https://www.npmjs.com/package/@chat-adapter/teams)
 [![npm downloads](https://img.shields.io/npm/dm/@chat-adapter/teams)](https://www.npmjs.com/package/@chat-adapter/teams)
 
-Microsoft Teams adapter for [Chat SDK](https://chat-sdk.dev). Configure with Azure Bot Service.
+Microsoft Teams adapter for [Chat SDK](https://chat-sdk.dev).
 
 ## Installation
 
@@ -33,104 +33,56 @@ bot.onNewMention(async (thread, message) => {
 });
 ```
 
-## Azure Bot setup
-
-### 1. Create Azure Bot resource
-
-1. Go to [portal.azure.com](https://portal.azure.com)
-2. Click **Create a resource**
-3. Search for **Azure Bot** and select it
-4. Click **Create** and fill in:
-   - **Bot handle**: Unique identifier for your bot
-   - **Subscription**: Your Azure subscription
-   - **Resource group**: Create new or use existing
-   - **Pricing tier**: F0 (free) for testing
-   - **Type of App**: **Single Tenant** (recommended for enterprise)
-   - **Creation type**: **Create new Microsoft App ID**
-5. Click **Review + create** then **Create**
-
-### 2. Get app credentials
-
-1. Go to your Bot resource then **Configuration**
-2. Copy **Microsoft App ID** as `TEAMS_APP_ID`
-3. Click **Manage Password** (next to Microsoft App ID)
-4. In the App Registration page, go to **Certificates & secrets**
-5. Click **New client secret**, add description, select expiry, click **Add**
-6. Copy the **Value** immediately (shown only once) as `TEAMS_APP_PASSWORD`
-7. Go to **Overview** and copy **Directory (tenant) ID** as `TEAMS_APP_TENANT_ID`
-
-### 3. Configure messaging endpoint
-
-1. In your Azure Bot resource, go to **Configuration**
-2. Set **Messaging endpoint** to `https://your-domain.com/api/webhooks/teams`
-3. Click **Apply**
-
-### 4. Enable Teams channel
-
-1. In your Azure Bot resource, go to **Channels**
-2. Click **Microsoft Teams**
-3. Accept the terms of service
-4. Click **Apply**
-
-### 5. Create Teams app package
-
-Create a `manifest.json` file:
-
-```json
-{
-  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
-  "manifestVersion": "1.16",
-  "version": "1.0.0",
-  "id": "your_app_id_here",
-  "packageName": "com.yourcompany.chatbot",
-  "developer": {
-    "name": "Your Company",
-    "websiteUrl": "https://your-domain.com",
-    "privacyUrl": "https://your-domain.com/privacy",
-    "termsOfUseUrl": "https://your-domain.com/terms"
-  },
-  "name": {
-    "short": "Chat Bot",
-    "full": "Chat SDK Demo Bot"
-  },
-  "description": {
-    "short": "A chat bot powered by Chat SDK",
-    "full": "A chat bot powered by Chat SDK that responds to messages and commands."
-  },
-  "icons": {
-    "outline": "outline.png",
-    "color": "color.png"
-  },
-  "accentColor": "#FFFFFF",
-  "bots": [
-    {
-      "botId": "your_app_id_here",
-      "scopes": ["personal", "team", "groupchat"],
-      "supportsFiles": false,
-      "isNotificationOnly": false
-    }
-  ],
-  "permissions": ["identity", "messageTeamMembers"],
-  "validDomains": ["your-domain.com"]
-}
+## Bot setup
+
+The [Teams CLI](https://microsoft.github.io/teams-sdk/cli) handles AAD app registration, client secret generation, bot registration, and Teams channel setup in one command.
+
+```bash
+npm install -g @microsoft/teams.cli@preview
+```
+
+### 1. Create the app
+
+```bash
+teams login
+teams status          # verify auth + sideloading permissions
+teams app create --name "My Bot" --endpoint "https://your-domain.com/api/webhooks/teams" --env .env
 ```
 
-Create icon files (32x32 `outline.png` and 192x192 `color.png`), then zip all three files together.
+> [!TIP]
+> For local development, use a tunnel (e.g. [devtunnel](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/), ngrok) to expose your local server.
 
-### 6. Upload app to Teams
+Credentials (`CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`) are written to `.env`. Rename them to match the adapter:
 
-**For testing (sideloading):**
+```bash
+TEAMS_APP_ID=<CLIENT_ID>
+TEAMS_APP_PASSWORD=<CLIENT_SECRET>
+TEAMS_APP_TENANT_ID=<TENANT_ID>
+```
 
-1. In Teams, click **Apps** in the sidebar
-2. Click **Manage your apps** then **Upload an app**
-3. Click **Upload a custom app** and select your zip file
+### 2. Install in Teams
 
-**For organization-wide deployment:**
+Get a direct install link:
 
-1. Go to [Teams Admin Center](https://admin.teams.microsoft.com)
-2. Go to **Teams apps** then **Manage apps**
-3. Click **Upload new app** and select your zip file
-4. Go to **Setup policies** to control who can use the app
+```bash
+teams app get <appId> --install-link
+```
+
+Or download the app package for sideloading:
+
+```bash
+teams app package download <appId> -o my-bot.zip
+```
+
+Then in Teams: **Apps** > **Manage your apps** > **Upload an app** > **Upload a custom app**.
+
+### 3. Verify
+
+```bash
+teams app doctor <appId>
+```
+
+Checks bot registration, AAD app health, manifest consistency, and endpoint reachability.
 
 ## Configuration
 
@@ -236,39 +188,42 @@ TEAMS_APP_TENANT_ID=...  # Required for SingleTenant apps
 
 ## Message history (`fetchMessages`)
 
-Fetching message history requires the Microsoft Graph API with client credentials flow. To enable it:
+Fetching message history requires `TEAMS_APP_TENANT_ID` and the right permissions depending on the conversation type:
 
-1. Set `appTenantId` in the adapter config (or `TEAMS_APP_TENANT_ID` env var)
-2. Grant one of these Azure AD app permissions:
-   - `ChatMessage.Read.Chat`
-   - `Chat.Read.All`
-   - `Chat.Read.WhereInstalled`
+| Context | Permission | Type | Admin consent? |
+|---------|-----------|------|---------------|
+| Channel | `ChannelMessage.Read.Group` | RSC | No |
+| Group chat | `ChatMessage.Read.Chat` | RSC | No |
+| DM | `Chat.Read.All` | Azure AD | Yes |
 
-Without these permissions, `fetchMessages` will throw a `NotImplementedError`.
+RSC permissions are set via the Teams CLI (no admin consent needed):
 
-### Receiving all messages
+```bash
+teams app rsc add <appId> ChannelMessage.Read.Group --type Application
+teams app rsc add <appId> ChatMessage.Read.Chat --type Application
+```
+
+For DM message history, RSC is not sufficient. Add the `Chat.Read.All` Azure AD permission using the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/):
+
+```bash
+az ad app permission add \
+  --id <appId> \
+  --api 00000003-0000-0000-c000-000000000000 \
+  --api-permissions 6b7d71aa-70aa-4810-a8d9-5d9fb2830017=Role
 
-By default, Teams bots only receive messages when directly @-mentioned. To receive all messages in a channel or group chat, add Resource-Specific Consent (RSC) permissions to your Teams app manifest:
-
-```json
-{
-  "authorization": {
-    "permissions": {
-      "resourceSpecific": [
-        {
-          "name": "ChannelMessage.Read.Group",
-          "type": "Application"
-        }
-      ]
-    }
-  }
-}
+az ad app permission admin-consent --id <appId>
 ```
 
-Alternatively, configure the bot in Azure to receive all messages.
+Without any of these permissions, `fetchMessages` will throw a `NotImplementedError`.
+
+### Receiving all messages
+
+By default, Teams bots only receive messages when directly @-mentioned. The RSC permissions above (`ChannelMessage.Read.Group` and `ChatMessage.Read.Chat`) also enable receiving all messages in channels and group chats as a side effect.
 
 ## Troubleshooting
 
+Run `teams app doctor <appId>` to diagnose common issues — it checks bot registration, AAD app health, manifest consistency, and endpoint reachability.
+
 ### "Unauthorized" error
 
 - Verify `TEAMS_APP_ID` and your chosen auth credential are correct