vercel__chat/packages/adapter-teams

@chat-adapter/teams

Microsoft Teams adapter for Chat SDK. Configure with Azure Bot Service.

Installation

pnpm add @chat-adapter/teams

Usage

The adapter auto-detects TEAMS_APP_ID, TEAMS_APP_PASSWORD, and TEAMS_APP_TENANT_ID from environment variables:

import { Chat } from "chat";
import { createTeamsAdapter } from "@chat-adapter/teams";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    teams: createTeamsAdapter({
      appType: "SingleTenant",
    }),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Teams!");
});

Azure Bot setup

1. Create Azure Bot resource

1. Go to 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:

{
  "$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"]
}

Create icon files (32x32 outline.png and 192x192 color.png), then zip all three files together.

6. Upload app to Teams

For testing (sideloading):

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

For organization-wide deployment:

1. Go to Teams Admin Center
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

Configuration

All options are auto-detected from environment variables when not provided.

Option	Required	Description
appId	No*	Azure Bot App ID. Auto-detected from TEAMS_APP_ID
appPassword	No**	Azure Bot App Password. Auto-detected from TEAMS_APP_PASSWORD
certificate	No**	Certificate-based authentication config
federated	No**	Federated (workload identity) authentication config
appType	No	"MultiTenant" or "SingleTenant" (default: "MultiTenant")
appTenantId	For SingleTenant	Azure AD Tenant ID. Auto-detected from TEAMS_APP_TENANT_ID
logger	No	Logger instance (defaults to ConsoleLogger("info"))

*appId is required — either via config or TEAMS_APP_ID env var.

**Exactly one authentication method is required: appPassword, certificate, or federated.

Authentication methods

The adapter supports three mutually exclusive authentication methods. When no explicit auth is provided, TEAMS_APP_PASSWORD is auto-detected from environment variables.

Client secret (default)

The simplest option — provide appPassword directly or set TEAMS_APP_PASSWORD:

createTeamsAdapter({
  appPassword: "your_app_password_here",
});

Certificate

Authenticate with a PEM certificate. Provide either certificateThumbprint or x5c (public certificate for subject-name validation):

createTeamsAdapter({
  certificate: {
    certificatePrivateKey: "-----BEGIN RSA PRIVATE KEY-----\n...",
    certificateThumbprint: "AB1234...", // hex-encoded thumbprint
  },
});

Or with subject-name validation:

createTeamsAdapter({
  certificate: {
    certificatePrivateKey: "-----BEGIN RSA PRIVATE KEY-----\n...",
    x5c: "-----BEGIN CERTIFICATE-----\n...",
  },
});

Federated (workload identity)

For environments with managed identities (e.g. Azure Kubernetes Service, GitHub Actions):

createTeamsAdapter({
  federated: {
    clientId: "your_managed_identity_client_id_here",
    clientAudience: "api://AzureADTokenExchange", // optional, this is the default
  },
});

Environment variables

TEAMS_APP_ID=...
TEAMS_APP_PASSWORD=...
TEAMS_APP_TENANT_ID=...  # Required for SingleTenant

Features

Messaging

Feature	Supported
Post message	Yes
Edit message	Yes
Delete message	Yes
File uploads	Yes
Streaming	Post+Edit fallback

Rich content

Feature	Supported
Card format	Adaptive Cards
Buttons	Yes
Link buttons	Yes
Select menus	No
Tables	GFM
Fields	Yes
Images in cards	Yes
Modals	No

Conversations

Feature	Supported
Slash commands	No
Mentions	Yes
Add reactions	No
Remove reactions	No
Typing indicator	No
DMs	Yes
Ephemeral messages	No (DM fallback)

Message history

Feature	Supported
Fetch messages	Yes
Fetch single message	No
Fetch thread info	Yes
Fetch channel messages	Yes
List threads	Yes
Fetch channel info	Yes
Post channel message	Yes

Limitations

• Adding reactions: Teams Bot Framework doesn't support bots adding reactions. Calling addReaction() or removeReaction() throws a NotImplementedError. The bot can still receive reaction events via onReaction().
• Typing indicators: Not available via Bot Framework. startTyping() is a no-op.

Message history (fetchMessages)

Fetching message history requires the Microsoft Graph API with client credentials flow. To enable it:

1. Set appTenantId in the adapter config
2. Grant one of these Azure AD app permissions:
   • ChatMessage.Read.Chat
   • Chat.Read.All
   • Chat.Read.WhereInstalled

Without these permissions, fetchMessages will not be able to retrieve channel history.

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:

{
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "ChannelMessage.Read.Group",
          "type": "Application"
        }
      ]
    }
  }
}

Alternatively, configure the bot in Azure to receive all messages.

Troubleshooting

"Unauthorized" error

• Verify TEAMS_APP_ID and your chosen auth credential are correct
• For client secret auth, check that TEAMS_APP_PASSWORD is valid
• For certificate auth, ensure the private key and thumbprint/x5c match what's registered in Azure AD
• For federated auth, verify the managed identity client ID and audience are correct
• 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
• 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
• Check that your server is accessible from the internet
• Review Azure Bot logs for errors

License

MIT