package
Microsoft Teams adapter for Chat SDK — Bot Framework webhooks, Adaptive Cards, and Graph API
npm install @chat-adapter/teamsGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
vercel-release-bot
infra+release@vercel.com
Microsoft Teams adapter for Chat SDK.
Documentation: chat-sdk.dev/adapters/official/teams · Guides: vercel.com/kb/chat-sdk
pnpm add @chat-adapter/teamsTo scaffold a new Microsoft Teams bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter teams memoryVisit the adapters directory to see other available official and vendor-official adapters.
For managed credentials and webhook verification, see Vercel Connect.
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!");
});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 or sync/async resolver. 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 |
token | No** | Custom (scope, tenantId?) token factory for Bot Framework and Microsoft Graph |
webhookVerifier | No | Custom raw-body verifier that replaces Microsoft JWT verification |
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.
**One authentication method is required: appPassword, federated, or token. token takes precedence over federated, which takes precedence over appPassword.
Use Vercel Connect to manage the bot identity and tokens, or configure Microsoft app credentials directly.
Use Vercel Connect to resolve the bot's app ID and request short-lived tokens for Bot Framework and Microsoft Graph:
import { createTeamsAdapter } from "@chat-adapter/teams";
import { connectTeamsAdapter } from "@vercel/connect/chat";
const teams = createTeamsAdapter({
...connectTeamsAdapter("microsoft-teams/acme-teams"),
});The helper resolves appId during initialization and supplies a scope-aware token callback. It also verifies Connect-forwarded webhooks with Vercel OIDC instead of Microsoft's native JWT. Enable trigger forwarding to /api/webhooks/teams and omit TEAMS_APP_ID and TEAMS_APP_PASSWORD when using the helper.
The callback requests separate tokens for https://api.botframework.com/.default and https://graph.microsoft.com/.default. Graph reads still require the appropriate installation and consent permissions; Connect uses the bot's home tenant for managed tokens.
An appId resolver runs once during successful initialization. Call await bot.initialize() before using adapter methods directly; Chat initializes automatically before handling webhooks. botUserId becomes available after initialization when using a resolver.
A custom webhookVerifier receives the incoming request and its raw body. Return a truthy value to accept, or return a falsy value or throw to reject with HTTP 401. Without a verifier, the adapter retains Microsoft's native JWT verification.
The Teams CLI handles AAD app registration, client secret generation, bot registration, and Teams channel setup in one command.
npm install -g @microsoft/teams.cliteams 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>Get a direct install link:
teams app get <appId> --install-linkOr download the app package for sideloading:
teams app package download <appId> -o my-bot.zipThen in Teams: Apps > Manage your apps > Upload an app > Upload a custom app.
teams app doctor <appId>Checks bot registration, AAD app health, manifest consistency, and endpoint reachability.
The adapter supports client-secret, federated, and custom-token authentication. When no explicit auth is provided, TEAMS_APP_PASSWORD is auto-detected from environment variables.
The simplest option — provide appPassword directly or set TEAMS_APP_PASSWORD:
createTeamsAdapter({
appPassword: "your_app_password_here",
});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",
},
});Provide token: (scope, tenantId?) => string | Promise<string> to acquire tokens externally. The requested scope identifies Bot Framework or Microsoft Graph. This takes precedence over configured credentials and client-secret environment variables, including CLIENT_SECRET.
TEAMS_APP_ID=...
TEAMS_APP_PASSWORD=...
TEAMS_APP_TENANT_ID=... # Required for SingleTenant apps
TEAMS_API_URL=... # Optional, for GCC-High or sovereign-cloud deploymentsIncoming 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.
| Feature | Supported |
|---|---|
| Post message | Yes |
| Edit message | Yes |
| Delete message | Yes |
| File uploads | Yes |
| Streaming | Native (DMs) / Buffered fallback (group chats) |
| Feature | Supported |
|---|---|
| Card format | Adaptive Cards |
| Buttons | Yes |
| Link buttons | Yes |
| Select menus | No |
| Tables | Adaptive Card Table |
| Fields | Yes |
| Images in cards | Yes |
| Modals | Yes |
| 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) |
| 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 |
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.
onMessageUpdated fires when Teams sends the bot an edited message. Teams sends only the new version, so previousMessage is undefined, and isMention comes from the edited message's mentions. metadata.dateSent and metadata.editedAt are both the edit time, because Teams doesn't send the original send time. Undeleted messages are ignored.
The adapter assumes that a channel edit's conversation.id carries ;messageid=<root>, the same as a new channel message, so the thread ID points at the reply chain. This hasn't been checked against a captured channel edit yet.
In a DM, a stream that an onMessageUpdated handler posts goes out as its own message, the same as in group chats and channels. It doesn't use native DM streaming, because that stream belongs to the reply to the original message, which may still be in progress.
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.
Use bot.onInstalled for personal, group chat, and team installation updates,
and bot.onUninstalled for removal cleanup. The add-upgrade and
remove-upgrade actions mean an app upgrade added or removed the bot from its
manifest; handle persistence and cleanup for those actions too. Routine app
upgrades do not emit these events. A team or group
chat install also emits onMemberJoinedChannel; keep each welcome flow in one
handler and make side effects idempotent.
Events include the platform conversationId, optional tenant and actor
metadata, and a channelId that encodes the conversation's service URL. Persist
channelId in your own durable store and post to it later from any process with
bot.channel(channelId).post(). Removal events still reach your cleanup handler
when the activity carries no service URL. Pass webhook waitUntil to track
asynchronous work. For team installs, associate the destination with
event.raw.channelData.team.id, plus bot and tenant IDs: the selected-channel
conversationId on install can differ from the team/root ID on removal.
See the installation lifecycle guide for persistence, upgrade cleanup, and proactive examples.
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.
getUser)The adapter supports looking up user profiles via the Microsoft Graph API. To enable it:
User.Read.All application permission in your Azure AD app registrationconst 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 and their edits. 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.
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.
For Adaptive Card features that Chat SDK cards don't cover, such as Badge, pass the card as adaptiveCard to the adapter's postMessage, postChannelMessage, postEphemeral, or editMessage. The adapter sends the card as is and uses fallbackText as the activity summary:
const teams = bot.getAdapter("teams");
await teams.postMessage(thread.id, {
adaptiveCard: {
type: "AdaptiveCard",
version: "1.5",
body: [{ type: "Badge", text: "Bug", style: "Attention" }],
},
fallbackText: "Bug: checkout fails on Safari",
});adaptiveCard takes the card's JSON or a card object built with @microsoft/teams.cards. See the Teams adapter docs for details.
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 ApplicationFor 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.
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.
Run teams app doctor <appId> to diagnose common issues — it checks bot registration, AAD app health, manifest consistency, and endpoint reachability.
TEAMS_APP_ID and your chosen auth credential are correctTEAMS_APP_PASSWORD is valid and not expiredTEAMS_APP_TENANT_ID is setIf 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/chatThe 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-pluginThe 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).
MIT
Estimated unpacked size across 67 packages.
55.4 MB+
Includes dependencies.
7 direct dependencies.
4.45.0
4.45.0
4.45.0
4.45.0
^2.0.14
2.2.1
^2.0.14
2.2.1
^2.0.14
2.2.1
^2.0.14
2.2.1
2.2.1