diff --git a/packages/adapter-teams/README.md b/packages/adapter-teams/README.md index 25e45d68..3af1acbc 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,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= +TEAMS_APP_PASSWORD= +TEAMS_APP_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 --install-link +``` + +Or download the app package for sideloading: + +```bash +teams app package download -o my-bot.zip +``` + +Then in Teams: **Apps** > **Manage your apps** > **Upload an app** > **Upload a custom app**. + +### 3. Verify + +```bash +teams app doctor +``` + +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 ChannelMessage.Read.Group --type Application +teams app rsc add 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 \ + --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 ``` -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 ` 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