Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BotFrameworkAdapter
✓ import { BotFrameworkAdapter } from 'botbuilder';
✗ const { BotFrameworkAdapter } = require('botbuilder');
CommonJS `require` works, but ESM `import` is preferred in modern Node.js projects. This class initializes the bot's communication with channels.
ActivityHandler
✓ import { ActivityHandler } from 'botbuilder';
✗ import ActivityHandler from 'botbuilder';
This is a named export. `ActivityHandler` is the base class for implementing bot logic and processing incoming activities.
TurnContext
✓ import { TurnContext, MessageFactory } from 'botbuilder';
✗ import * as botbuilder from 'botbuilder'; const context = new botbuilder.TurnContext(...);
Directly importing `TurnContext` and `MessageFactory` is standard for handling interaction context and creating outgoing messages.
This quickstart sets up a basic 'echo' bot using `botbuilder` and `restify`. It demonstrates handling incoming messages, welcoming new members, and configuring error handling for the adapter. It uses environment variables for bot credentials.
import { BotFrameworkAdapter, ActivityHandler, TurnContext } from 'botbuilder';
import * as restify from 'restify';
// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about adapters.
const adapter = new BotFrameworkAdapter({
appId: process.env.MicrosoftAppId ?? '',
appPassword: process.env.MicrosoftAppPassword ?? ''
});
// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
// This check writes out errors to console log .vs. app insights.
console.error(`\n[onTurnError] Unhandled error: ${ error }`);
// Send a trace activity, which will be displayed in Bot Framework Emulator
await context.sendTraceActivity(
'OnTurnError Trace',
`${ error }`,
'https://www.botframework.com/schemas/error',
'TurnError'
);
// Send a message to the user
await context.sendActivity('The bot encountered an error or bug.');
await context.sendActivity('To continue to run this bot, please fix the bot source code.');
};
// Define a bot.
class MyBot extends ActivityHandler {
constructor() {
super();
this.onMessage(async (context, next) => {
const replyText = `Echo: ${ context.activity.text }`;
await context.sendActivity(replyText);
// By calling next() you ensure that the next BotHandler is run.
await next();
});
this.onMembersAdded(async (context, next) => {
const welcomeText = 'Hello and welcome!';
for (const member of context.activity.membersAdded) {
if (member.id !== context.activity.recipient.id) {
await context.sendActivity(`Hi there ${ member.name }. ${ welcomeText }`);
}
}
// By calling next() you ensure that the next BotHandler is run.
await next();
});
}
}
const bot = new MyBot();
// Create HTTP server.
const server = restify.createServer();
server.listen(process.env.port || process.env.PORT || 3978, () => {
console.log(`\n${ server.name } listening to ${ server.url }`);
console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator');
console.log('\nTo talk to your bot, open the emulator and connect to: http://localhost:3978/api/messages');
});
// Listen for incoming requests.
server.post('/api/messages', (req, res) => {
adapter.processActivity(req, res, async (turnContext) => {
// Route to main dialog.
await bot.run(turnContext);
});
});
Errors
Common errors & fixes
FetchError: request to https://login.botframework.com/v1/.well-known/openidconfiguration
Issue fetching OpenID configuration, often due to network issues, incorrect bot ID/password, or firewall blocking the endpoint.
fixVerify network connectivity, ensure `MicrosoftAppId` and `MicrosoftAppPassword` are correctly set and valid. Check for firewall rules blocking outbound requests to `login.botframework.com`.
Error: MicrosoftAppId and MicrosoftAppPassword are required for production environments.
The `BotFrameworkAdapter` was initialized without an App ID and/or App Password, which are mandatory for connecting to channels.
fixSet the `MicrosoftAppId` and `MicrosoftAppPassword` environment variables or provide them directly when instantiating `BotFrameworkAdapter`.
TypeError: Cannot read properties of undefined (reading 'run')
Typically occurs when `await bot.run(turnContext)` is called, but `bot` (an instance of `ActivityHandler` or a derived class) is not properly initialized or scoped.
fixEnsure `bot` is instantiated correctly (e.g., `const bot = new MyBot();`) and is accessible in the scope where `adapter.processActivity` is called.
Audit
Dependencies
typescriptrequiredRequired for development, with specific version compatibility changes between releases.
noderequiredRuntime dependency. Minimum version requirement has increased over time.