From 3cdd9f0d82a6dbf27d415cbe49ca644c7ad4460b Mon Sep 17 00:00:00 2001 From: heyitsaamir Date: Sun, 19 Apr 2026 09:23:25 -0700 Subject: [PATCH 1/5] docs(adapter-teams): simplify bot setup using Teams CLI Replace manual 6-step Azure portal walkthrough with Teams CLI commands. `teams app create` handles AAD registration, secret generation, bot registration, and channel setup in a single command. Also updates RSC permission and troubleshooting sections to reference CLI equivalents. Co-Authored-By: Claude Opus 4.6 (1M context) --- packages/adapter-teams/README.md | 188 ++++++++++++------------------- 1 file changed, 74 insertions(+), 114 deletions(-) diff --git a/packages/adapter-teams/README.md b/packages/adapter-teams/README.md index 25e45d68..359bbcb2 100644 --- a/packages/adapter-teams/README.md +++ b/packages/adapter-teams/README.md @@ -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,77 @@ 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 app create --name "My Bot" --endpoint "https://your-domain.com/api/webhooks/teams" --env .env +``` + +Credentials (`CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`) are written to `.env`. Rename them to match the adapter: + +```bash +TEAMS_APP_ID= +TEAMS_APP_PASSWORD= +TEAMS_APP_TENANT_ID= +``` + +### 2. Install in Teams + +Get a direct install link: + +```bash +teams app get --install-link +``` + +Or download the app package for sideloading: + +```bash +teams app package download -o my-bot.zip ``` -Create icon files (32x32 `outline.png` and 192x192 `color.png`), then zip all three files together. +Then in Teams: **Apps** > **Manage your apps** > **Upload an app** > **Upload a custom app**. -### 6. Upload app to Teams +### 3. Verify -**For testing (sideloading):** +```bash +teams app doctor +``` -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 +Checks bot registration, AAD app health, manifest consistency, and endpoint reachability. -**For organization-wide deployment:** +### Azure bots (optional) -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 +By default, `teams app create` creates a Teams-managed bot (no Azure subscription required). For OAuth connections or SSO, create an Azure bot instead: + +```bash +az login +teams app create --name "My Bot" --endpoint "https://your-domain.com/api/webhooks/teams" --env .env --azure --resource-group my-rg +``` + +You can also migrate an existing Teams-managed bot to Azure later: + +```bash +teams app bot migrate --resource-group my-rg --create-resource-group +``` + +### Managing your app + +```bash +# Update the messaging endpoint +teams app update --endpoint "https://new-domain.com/api/webhooks/teams" + +# Rotate the client secret +teams app auth secret create --env .env +``` ## Configuration @@ -248,46 +221,33 @@ Without these permissions, `fetchMessages` will throw a `NotImplementedError`. ### Receiving all messages -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" - } - ] - } - } -} -``` +By default, Teams bots only receive messages when directly @-mentioned. To receive all messages in a channel or group chat, add the RSC permission: -Alternatively, configure the bot in Azure to receive all messages. +```bash +teams app rsc add ChannelMessage.Read.Group --type Application +``` ## Troubleshooting +Run `teams app doctor ` 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 -- For client secret auth, check that `TEAMS_APP_PASSWORD` is valid and not expired +- Check that `TEAMS_APP_PASSWORD` is valid and not expired (rotate with `teams app auth secret create`) - For federated auth, verify the managed identity client ID is correct and that federated credentials are configured in Azure AD - For SingleTenant apps, ensure `TEAMS_APP_TENANT_ID` is set -- Check that the messaging endpoint URL is correct in Azure ### Bot not appearing in Teams -- Verify the Teams channel is enabled in Azure Bot +- Run `teams app doctor` to check registration and channel status - Check that the app manifest is correctly configured - Ensure the app is installed in the workspace/team ### Messages not received -- Verify the messaging endpoint URL is correct +- Verify the messaging endpoint is correct (`teams app update --endpoint`) - Check that your server is accessible from the internet -- Review Azure Bot logs for errors ## License From a5899bcb12406585a180ed29114480b532c26f3a Mon Sep 17 00:00:00 2001 From: heyitsaamir Date: Sun, 19 Apr 2026 10:04:49 -0700 Subject: [PATCH 2/5] docs(adapter-teams): remove bot migration section Co-Authored-By: Claude Opus 4.6 (1M context) --- packages/adapter-teams/README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/packages/adapter-teams/README.md b/packages/adapter-teams/README.md index 359bbcb2..cb7981ca 100644 --- a/packages/adapter-teams/README.md +++ b/packages/adapter-teams/README.md @@ -89,12 +89,6 @@ az login teams app create --name "My Bot" --endpoint "https://your-domain.com/api/webhooks/teams" --env .env --azure --resource-group my-rg ``` -You can also migrate an existing Teams-managed bot to Azure later: - -```bash -teams app bot migrate --resource-group my-rg --create-resource-group -``` - ### Managing your app ```bash From a001cfe836f7e21de35f2f9d0f2d0d66d19db7d8 Mon Sep 17 00:00:00 2001 From: heyitsaamir Date: Sun, 19 Apr 2026 15:55:31 -0700 Subject: [PATCH 3/5] docs(adapter-teams): clarify message history permissions by context RSC permissions cover channels and group chats (no admin consent). Azure AD Chat.Read.All is only needed for DM history. Add permission table and az CLI commands for DM setup. Co-Authored-By: Claude Opus 4.6 (1M context) --- packages/adapter-teams/README.md | 36 +++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/packages/adapter-teams/README.md b/packages/adapter-teams/README.md index cb7981ca..980e6990 100644 --- a/packages/adapter-teams/README.md +++ b/packages/adapter-teams/README.md @@ -97,6 +97,10 @@ teams app update --endpoint "https://new-domain.com/api/webhooks/teams" # Rotate the client secret teams app auth secret create --env .env + +# Receive all messages (not just @mentions) + enable message history +teams app rsc add ChannelMessage.Read.Group --type Application +teams app rsc add ChatMessage.Read.Chat --type Application ``` ## Configuration @@ -203,24 +207,36 @@ 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 ChannelMessage.Read.Group --type Application +teams app rsc add ChatMessage.Read.Chat --type Application +``` -By default, Teams bots only receive messages when directly @-mentioned. To receive all messages in a channel or group chat, add the RSC permission: +These also enable receiving all messages without @mention as a side effect. + +For DM message history, RSC is not sufficient. Add the `Chat.Read.All` Azure AD permission: ```bash -teams app rsc add ChannelMessage.Read.Group --type Application +az ad app permission add \ + --id \ + --api 00000003-0000-0000-c000-000000000000 \ + --api-permissions 6b7d71aa-70aa-4810-a8d9-5d9fb2830017=Role + +az ad app permission admin-consent --id ``` +Without any of these permissions, `fetchMessages` will throw a `NotImplementedError`. + ## Troubleshooting Run `teams app doctor ` to diagnose common issues — it checks bot registration, AAD app health, manifest consistency, and endpoint reachability. From 2cc22b4ce540681c181468fcebb823b70835e14e Mon Sep 17 00:00:00 2001 From: heyitsaamir Date: Sun, 19 Apr 2026 20:25:38 -0700 Subject: [PATCH 4/5] docs(adapter-teams): simplify bot setup using Teams CLI Replace manual 6-step Azure portal walkthrough with Teams CLI commands. Correct message history permissions: RSC for channels/group chats, Azure AD only for DM history. Add local dev tunnel tip. --- packages/adapter-teams/README.md | 42 ++++++++++---------------------- 1 file changed, 13 insertions(+), 29 deletions(-) diff --git a/packages/adapter-teams/README.md b/packages/adapter-teams/README.md index 980e6990..931e6f3e 100644 --- a/packages/adapter-teams/README.md +++ b/packages/adapter-teams/README.md @@ -48,6 +48,9 @@ teams login teams app create --name "My Bot" --endpoint "https://your-domain.com/api/webhooks/teams" --env .env ``` +> [!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. + Credentials (`CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`) are written to `.env`. Rename them to match the adapter: ```bash @@ -80,29 +83,6 @@ teams app doctor Checks bot registration, AAD app health, manifest consistency, and endpoint reachability. -### Azure bots (optional) - -By default, `teams app create` creates a Teams-managed bot (no Azure subscription required). For OAuth connections or SSO, create an Azure bot instead: - -```bash -az login -teams app create --name "My Bot" --endpoint "https://your-domain.com/api/webhooks/teams" --env .env --azure --resource-group my-rg -``` - -### Managing your app - -```bash -# Update the messaging endpoint -teams app update --endpoint "https://new-domain.com/api/webhooks/teams" - -# Rotate the client secret -teams app auth secret create --env .env - -# Receive all messages (not just @mentions) + enable message history -teams app rsc add ChannelMessage.Read.Group --type Application -teams app rsc add ChatMessage.Read.Chat --type Application -``` - ## Configuration All options are auto-detected from environment variables when not provided. Internally, the adapter maps these options to the Teams SDK (`@microsoft/teams.apps`). @@ -222,9 +202,7 @@ teams app rsc add ChannelMessage.Read.Group --type Application teams app rsc add ChatMessage.Read.Chat --type Application ``` -These also enable receiving all messages without @mention as a side effect. - -For DM message history, RSC is not sufficient. Add the `Chat.Read.All` Azure AD permission: +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 \ @@ -237,6 +215,10 @@ az ad app permission admin-consent --id 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 ` to diagnose common issues — it checks bot registration, AAD app health, manifest consistency, and endpoint reachability. @@ -244,20 +226,22 @@ Run `teams app doctor ` to diagnose common issues — it checks bot regis ### "Unauthorized" error - Verify `TEAMS_APP_ID` and your chosen auth credential are correct -- Check that `TEAMS_APP_PASSWORD` is valid and not expired (rotate with `teams app auth secret create`) +- For client secret auth, check that `TEAMS_APP_PASSWORD` is valid and not expired - For federated auth, verify the managed identity client ID is correct and that federated credentials are configured in Azure AD - For SingleTenant apps, ensure `TEAMS_APP_TENANT_ID` is set +- Check that the messaging endpoint URL is correct in Azure ### Bot not appearing in Teams -- Run `teams app doctor` to check registration and channel status +- Verify the Teams channel is enabled in Azure Bot - Check that the app manifest is correctly configured - Ensure the app is installed in the workspace/team ### Messages not received -- Verify the messaging endpoint is correct (`teams app update --endpoint`) +- Verify the messaging endpoint URL is correct - Check that your server is accessible from the internet +- Review Azure Bot logs for errors ## License From 4f91d9729e938f151dd90117f9bc136d154f11e8 Mon Sep 17 00:00:00 2001 From: heyitsaamir Date: Thu, 23 Apr 2026 15:55:42 -0700 Subject: [PATCH 5/5] docs(adapter-teams): add teams status step after login --- packages/adapter-teams/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/adapter-teams/README.md b/packages/adapter-teams/README.md index 931e6f3e..3af1acbc 100644 --- a/packages/adapter-teams/README.md +++ b/packages/adapter-teams/README.md @@ -45,6 +45,7 @@ npm install -g @microsoft/teams.cli@preview ```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 ```