vercel__chat/packages/adapter-teams

@chat-adapter/teams

npm package: @chat-adapter/teams

Microsoft Teams adapter for Chat SDK.

Documentation: chat-sdk.dev/adapters/official/teams · Guides: vercel.com/kb/chat-sdk

Installation

pnpm add @chat-adapter/teams

Scaffold with the CLI

To scaffold a new Microsoft Teams bot with this adapter preselected:

npx create-chat-sdk@latest my-bot --adapter teams memory

Visit the adapters directory to see other available official and vendor-official adapters.

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!");
});

Bot setup

The Teams CLI handles AAD app registration, client secret generation, bot registration, and Teams channel setup in one command.

npm install -g @microsoft/teams.cli

1. Create the app

teams login
teams status          # verify auth + sideloading permissions
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, ngrok) to expose your local server.

Credentials (CLIENT_ID, CLIENT_SECRET, TENANT_ID) are written to .env. Rename them to match the adapter:

TEAMS_APP_ID=<CLIENT_ID>
TEAMS_APP_PASSWORD=<CLIENT_SECRET>
TEAMS_APP_TENANT_ID=<TENANT_ID>

2. Install in Teams

Get a direct install link:

teams app get <appId> --install-link

Or download the app package for sideloading:

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

teams app doctor <appId>

Checks bot registration, AAD app health, manifest consistency, and endpoint reachability.

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).

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
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
userName	No	Bot display name (default: "bot")
apiUrl	No	Override the Teams API base URL (e.g. for GCC-High or sovereign-cloud deployments). Auto-detected from TEAMS_API_URL
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 or federated. When neither is provided, TEAMS_APP_PASSWORD is auto-detected from environment.

Authentication methods

The adapter supports two 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",
});

Federated (workload identity)

For environments with managed identities (e.g. Azure Kubernetes Service, GitHub Actions). Maps to managedIdentityClientId in the Teams SDK:

createTeamsAdapter({
  federated: {
    clientId: "your_managed_identity_client_id_here",
  },
});

Environment variables

TEAMS_APP_ID=...
TEAMS_APP_PASSWORD=...
TEAMS_APP_TENANT_ID=...  # Required for SingleTenant apps
TEAMS_API_URL=...        # Optional, for GCC-High or sovereign-cloud deployments

Mentions

Incoming Teams mentions are supported. Outgoing @name text, including multi-word names, stays plain text and does not notify the user. The adapter does not resolve display names into user identities or generate mention entities. Teams requires matching mention text and entities for a real mention; <at> markup alone is not sufficient.

Features

Messaging

Feature	Supported
Post message	Yes
Edit message	Yes
Delete message	Yes
File uploads	Yes
Streaming	Native (DMs) / Buffered fallback (group chats)

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	Yes

Conversations

Feature	Supported
Slash commands	No
Mentions	Yes
Add reactions	Yes
Remove reactions	Yes
Receive reactions	Yes
Typing indicator	Yes
DMs	Yes
Ephemeral messages	Yes (native targeted messages, public preview)
User lookup (getUser)	Yes (requires User.Read.All)

Message history

Feature	Supported
Fetch messages	Yes (requires Graph permissions)
Fetch single message	No
Fetch thread info	Yes
Fetch channel messages	Yes (requires Graph permissions)
List threads	Yes (requires Graph permissions)
Fetch channel info	Yes (requires Graph permissions)
Post channel message	Yes

Conversation routing

Incoming thread IDs preserve the Teams conversation type when the legacy ID-prefix heuristic would route it incorrectly. When Teams omits conversationType, the adapter falls back to conversation.isGroup and the activity's team context. This keeps correctly classified IDs stable while selecting the buffered fallback for group chats whose IDs begin with a:. Thread IDs created by older adapter versions remain supported.

Bot joins

onMemberJoinedChannel fires when a conversationUpdate activity adds this bot to a channel or group chat. adapter.botUserId is the Teams bot ID (28:<appId>), so the same bot-join guard works across adapters:

bot.onMemberJoinedChannel(async (event) => {
  if (event.userId !== event.adapter.botUserId) {
    return;
  }
  await bot.channel(event.channelId).post("Hello! Thanks for adding me.");
});

For team installations, channelId identifies the channel selected during installation, not the team ID. inviterId comes from the activity sender. Pass your platform's waitUntil to the webhook handler to track asynchronous welcome handlers.

This dispatches bot joins only. Personal installs, ordinary member additions, removals, and installationUpdate activities do not emit this event. See Microsoft's conversation event documentation for the underlying payloads.

Incoming attachments

Incoming inline images and files are exposed through message.attachments with a lazy fetchData() method. The adapter authenticates connector-hosted inline attachments through the configured Teams bot client, while Teams file download cards use their direct download URL without the bot token.

Anonymous downloads require HTTPS URLs that resolve to public addresses; private and internal hosts are refused, including after redirects. Responses are limited to 25 MB and downloads time out after 30 seconds. Inline attachments served by the connector use bot authentication instead, including the Bot Framework Emulator's plain-HTTP loopback connector. To change the limits or route downloads through a proxy, override createFetchDataFn() in a subclass and call downloadAttachment from @chat-adapter/shared with your own options.

User lookup (getUser)

The adapter supports looking up user profiles via the Microsoft Graph API. To enable it:

1. Grant the User.Read.All application permission in your Azure AD app registration
2. Grant admin consent for the permission

const user = await bot.getUser(message.author);
console.log(user?.email);    // "alice@contoso.com"
console.log(user?.fullName); // "Alice Smith"

Incoming message authors also include email when the Teams conversation members API resolves the sender. This lookup uses the bot's access to the current conversation and does not require Microsoft Graph permissions. Lookup failures leave message.author.email undefined without preventing message delivery. This applies to live incoming messages only. Authors on edited-message events and messages returned by fetchMessages are not hydrated with an email. Resolved profiles are cached in the state adapter for 1 hour, so busy conversations don't trigger a lookup per message.

The adapter caches each user's Azure AD object ID from incoming activities for later getUser calls. getUser returns null if the user hasn't been seen or the Graph call fails.

Targeted / ephemeral messages

Teams targeted messages are available in public preview. Use the standard Chat SDK postEphemeral API to send a message that is visible only to a specific Teams conversation member:

await thread.postEphemeral(message.author, "Only you can see this.", {
  fallbackToDM: false,
});

The adapter sends these natively with Teams targeted message metadata. usedFallback is false when the Teams API accepts the message.

Message history (fetchMessages)

Fetching message history requires TEAMS_APP_TENANT_ID and the right permissions depending on the conversation type:

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

RSC permissions are set via the Teams CLI (no admin consent needed):

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:

az ad app permission add \
  --id <appId> \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions 6b7d71aa-70aa-4810-a8d9-5d9fb2830017=Role

az ad app permission admin-consent --id <appId>

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
• 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

• 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

AI Coding Agents

If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.

npx skills add vercel/chat

The skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.

You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:

npx plugins add vercel/vercel-plugin

The plugin is optional; the skill alone is enough to build with Chat SDK.

For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).

License

MIT