API Reference

Microsoft Teams SDK — API Reference (TypeScript)

Curated reference for the @microsoft/teams.* npm packages. Full documentation lives at https://microsoft.github.io/teams-sdk/typescript/. A trimmed copy of the SDK's LLM doc is at references/llms-typescript-full.md for offline grep.

Packages

See references/packages-overview.md for what each one exports.

Bootstrapping

import { App, PUBLIC, US_GOV, US_GOV_DOD, CHINA } from '@microsoft/teams.apps';

const app = new App({
  plugins: [],            // DevtoolsPlugin, McpPlugin, ExpressAdapter, etc.
  cloud: PUBLIC,          // default; override for sovereign clouds
  clientId: '...',        // optional — derived from env if omitted
  clientSecret: '...',    // optional — derived from env if omitted
});

await app.start(3978);

See references/app-class.md for the full AppOptions shape.

Activity routing

app.on('message', async (ctx) => { /* MessageActivity */ });
app.on('install.add', async (ctx) => { /* InstallActivity */ });
app.on('config.open', async (ctx) => { /* ConfigOpenActivity */ });
app.on('dialog.open.<id>', async (ctx) => { /* DialogOpenActivity */ });
app.on('dialog.submit.<id>', async (ctx) => { /* DialogSubmitActivity */ });
app.on('card.action.<id>', async (ctx) => { /* CardActionActivity */ });
app.on('message.ext.query', async (ctx) => { /* MessageExtQueryActivity */ });
app.on('message.ext.submit', async (ctx) => { /* MessageExtSubmitActivity */ });
app.on('message.ext.select-item', async (ctx) => { /* MessageExtSelectItemActivity */ });
app.on('message.ext.query-link', async (ctx) => { /* MessageExtQueryLinkActivity */ });
app.on('signin.token-exchange', async (ctx) => { /* token exchange for SSO */ });
app.on('signin.verify-state', async (ctx) => { /* verify state after sign-in */ });

Route-name string drives the activity-type inference. See references/activity-types.md.

Handler context

Every handler receives an object with:

Sending messages

await send('Hello');                                   // text
await send(new MessageActivity('Hello'));              // explicit activity
await send({ type: 'typing' });                        // typing indicator
await app.send(conversationId, 'Hello');               // proactive send
await app.reply(conversationId, threadId, 'Hello');    // thread reply

Adaptive Cards

import { AdaptiveCard, TextBlock, TextInput, ActionSet, ExecuteAction } from '@microsoft/teams.cards';
import { cardAttachment } from '@microsoft/teams.api';

const card = new AdaptiveCard()
  .addBody(new TextBlock('Hi').withWeight('Bolder'))
  .addBody(new TextInput('email').withPlaceholder('you@example.com'))
  .addActions(new ExecuteAction('save').withTitle('Save'));

await send(new MessageActivity().addAttachment(cardAttachment('adaptive', card)));

See adaptive-cards skill for the full builder catalogue.

AI

import { ChatPrompt } from '@microsoft/teams.ai';
import { OpenAIChatModel } from '@microsoft/teams.openai';

const prompt = new ChatPrompt({
  instructions: 'You are a helpful assistant.',
  model: new OpenAIChatModel({ model: 'gpt-4o' }),
});

const { content } = await prompt.send('Quote me Marcus Aurelius');

See ai-agents skill + references/prompts-and-models.md.

Plugins

new App({ plugins: [new DevtoolsPlugin(), new McpPlugin(), new A2AClientPlugin(...)] });

Plugins intercept the activity pipeline. See mcp-plugin for MCP-specific patterns.

Reference files

• references/packages-overview.md — what each @microsoft/teams.* package exports
• references/app-class.md — AppOptions, cloud enum, lifecycle hooks
• references/activity-types.md — exhaustive activity-name → type table
• references/llms-typescript-full.md — trimmed offline copy of the SDK's own LLM reference