{"id":12902,"library":"botbuilder","title":"Microsoft Bot Framework SDK for JavaScript","description":"The Bot Framework SDK for JavaScript (botbuilder) is a comprehensive toolkit for developing intelligent conversational AI bots. It enables developers to build, connect, and manage bots that interact with users across various channels like web chat, Teams, Slack, and more. The current stable version is 4.23.3, with releases occurring monthly or bi-monthly, frequently addressing security updates, dependency bumps, and support for newer Node.js and TypeScript versions. Key differentiators include deep integration with Microsoft Azure Bot Service, a robust middleware pipeline, built-in dialog management, and enterprise-grade scalability. It is designed for both simple Q&A bots and complex, multi-turn conversational agents.","status":"active","version":"4.23.3","language":"javascript","source_language":"en","source_url":"https://github.com/Microsoft/botbuilder-js","tags":["javascript","botbuilder","botframework","bots","chatbots","typescript"],"install":[{"cmd":"npm install botbuilder","lang":"bash","label":"npm"},{"cmd":"yarn add botbuilder","lang":"bash","label":"yarn"},{"cmd":"pnpm add botbuilder","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for development, with specific version compatibility changes between releases.","package":"typescript","optional":false},{"reason":"Runtime dependency. Minimum version requirement has increased over time.","package":"node","optional":false}],"imports":[{"note":"CommonJS `require` works, but ESM `import` is preferred in modern Node.js projects. This class initializes the bot's communication with channels.","wrong":"const { BotFrameworkAdapter } = require('botbuilder');","symbol":"BotFrameworkAdapter","correct":"import { BotFrameworkAdapter } from 'botbuilder';"},{"note":"This is a named export. `ActivityHandler` is the base class for implementing bot logic and processing incoming activities.","wrong":"import ActivityHandler from 'botbuilder';","symbol":"ActivityHandler","correct":"import { ActivityHandler } from 'botbuilder';"},{"note":"Directly importing `TurnContext` and `MessageFactory` is standard for handling interaction context and creating outgoing messages.","wrong":"import * as botbuilder from 'botbuilder'; const context = new botbuilder.TurnContext(...);","symbol":"TurnContext","correct":"import { TurnContext, MessageFactory } from 'botbuilder';"}],"quickstart":{"code":"import { BotFrameworkAdapter, ActivityHandler, TurnContext } from 'botbuilder';\nimport * as restify from 'restify';\n\n// Create adapter.\n// See https://aka.ms/about-bot-adapter to learn more about adapters.\nconst adapter = new BotFrameworkAdapter({\n    appId: process.env.MicrosoftAppId ?? '',\n    appPassword: process.env.MicrosoftAppPassword ?? ''\n});\n\n// Catch-all for errors.\nadapter.onTurnError = async (context, error) => {\n    // This check writes out errors to console log .vs. app insights.\n    console.error(`\\n[onTurnError] Unhandled error: ${ error }`);\n\n    // Send a trace activity, which will be displayed in Bot Framework Emulator\n    await context.sendTraceActivity(\n        'OnTurnError Trace',\n        `${ error }`,\n        'https://www.botframework.com/schemas/error',\n        'TurnError'\n    );\n\n    // Send a message to the user\n    await context.sendActivity('The bot encountered an error or bug.');\n    await context.sendActivity('To continue to run this bot, please fix the bot source code.');\n};\n\n// Define a bot.\nclass MyBot extends ActivityHandler {\n    constructor() {\n        super();\n        this.onMessage(async (context, next) => {\n            const replyText = `Echo: ${ context.activity.text }`;\n            await context.sendActivity(replyText);\n            // By calling next() you ensure that the next BotHandler is run.\n            await next();\n        });\n\n        this.onMembersAdded(async (context, next) => {\n            const welcomeText = 'Hello and welcome!';\n            for (const member of context.activity.membersAdded) {\n                if (member.id !== context.activity.recipient.id) {\n                    await context.sendActivity(`Hi there ${ member.name }. ${ welcomeText }`);\n                }\n            }\n            // By calling next() you ensure that the next BotHandler is run.\n            await next();\n        });\n    }\n}\n\nconst bot = new MyBot();\n\n// Create HTTP server.\nconst server = restify.createServer();\nserver.listen(process.env.port || process.env.PORT || 3978, () => {\n    console.log(`\\n${ server.name } listening to ${ server.url }`);\n    console.log('\\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator');\n    console.log('\\nTo talk to your bot, open the emulator and connect to: http://localhost:3978/api/messages');\n});\n\n// Listen for incoming requests.\nserver.post('/api/messages', (req, res) => {\n    adapter.processActivity(req, res, async (turnContext) => {\n        // Route to main dialog.\n        await bot.run(turnContext);\n    });\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18 or higher (Node 20 or 22 recommended).","message":"Node.js versions prior to 18 are no longer supported due to updates in underlying Azure Identity and MSAL.Node packages.","severity":"breaking","affected_versions":">=4.23.0"},{"fix":"Upgrade your project's TypeScript version to 5.9 or newer.","message":"Support for TypeScript 4.7 has been dropped due to incompatibilities with newer Node.js types. Ensure your project uses a compatible TypeScript version.","severity":"breaking","affected_versions":">=4.23.3"},{"fix":"Regularly update `botbuilder` and its related packages to the latest stable version to incorporate critical security patches and dependency fixes.","message":"Frequent security updates and dependency bumps mean that running older patch versions can expose your bot to known vulnerabilities.","severity":"gotcha","affected_versions":"<4.23.3"},{"fix":"If using federated credentials, ensure your bot application is configured for single-tenant authentication. Multi-tenant support may require alternative authentication methods or future SDK updates.","message":"Federated Identity Credentials for bot-to-channel authentication are currently supported for single-tenant applications only.","severity":"gotcha","affected_versions":">=4.23.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify network connectivity, ensure `MicrosoftAppId` and `MicrosoftAppPassword` are correctly set and valid. Check for firewall rules blocking outbound requests to `login.botframework.com`.","cause":"Issue fetching OpenID configuration, often due to network issues, incorrect bot ID/password, or firewall blocking the endpoint.","error":"FetchError: request to https://login.botframework.com/v1/.well-known/openidconfiguration"},{"fix":"Set the `MicrosoftAppId` and `MicrosoftAppPassword` environment variables or provide them directly when instantiating `BotFrameworkAdapter`.","cause":"The `BotFrameworkAdapter` was initialized without an App ID and/or App Password, which are mandatory for connecting to channels.","error":"Error: MicrosoftAppId and MicrosoftAppPassword are required for production environments."},{"fix":"Ensure `bot` is instantiated correctly (e.g., `const bot = new MyBot();`) and is accessible in the scope where `adapter.processActivity` is called.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'run')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}