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.
Quick start
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!");});
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 or sync/async resolver. Auto-detected from TEAMS_APP_ID
appPassword
No**
Azure Bot App Password. Auto-detected from TEAMS_APP_PASSWORD
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.
Authentication
Use Vercel Connect to manage the bot identity and tokens, or configure Microsoft app credentials directly.
Option A — Vercel Connect
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.
Option B — Microsoft app credentials
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 loginteams status # verify auth + sideloading permissionsteams 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:
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.
Client secret (default)
The simplest option — provide appPassword directly or set TEAMS_APP_PASSWORD:
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.
Environment variables
TEAMS_APP_ID=...TEAMS_APP_PASSWORD=...TEAMS_APP_TENANT_ID=... # Required for SingleTenant appsTEAMS_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
Adaptive Card Table
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.
Message edits
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.
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.
Installation lifecycle
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.
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:
Grant the User.Read.Allapplication permission in your Azure AD app registration
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 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.
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.
Raw Adaptive Cards
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:
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=Roleaz 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.