{"id":15091,"library":"botframework-schema","title":"Bot Framework Activity Schema","description":"The `botframework-schema` package provides the TypeScript interfaces and JSON schema definitions for activities exchanged within the Microsoft Bot Framework. This package defines the fundamental structure for messages, conversations, attachments, and other events that occur between a bot and its users across various communication channels. The current stable version is 4.23.3. It is an integral component of the broader Bot Framework JS SDK and follows a consistent release cadence, typically monthly or bi-monthly, synchronizing with the SDK's updates. Releases frequently address security patches, expand Node.js version support, and ensure compatibility with newer TypeScript versions. Its primary differentiation is serving as the canonical and universally recognized schema for all Bot Framework interactions, thereby guaranteeing interoperability and offering robust type safety for bot developers utilizing TypeScript.","status":"active","version":"4.23.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/Microsoft/botbuilder-js","tags":["javascript","botconnector","bots","chatbots","typescript"],"install":[{"cmd":"npm install botframework-schema","lang":"bash","label":"npm"},{"cmd":"yarn add botframework-schema","lang":"bash","label":"yarn"},{"cmd":"pnpm add botframework-schema","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Activity is a named interface, not a default export.","wrong":"import Activity from 'botframework-schema';","symbol":"Activity","correct":"import { Activity } from 'botframework-schema';"},{"note":"ESM imports are preferred. `ActivityTypes` is a named enum for various activity kinds.","wrong":"const ActivityTypes = require('botframework-schema').ActivityTypes;","symbol":"ActivityTypes","correct":"import { ActivityTypes } from 'botframework-schema';"},{"note":"Imports the specific interface for message activities, which extends the base `Activity` interface.","symbol":"MessageActivity","correct":"import { MessageActivity } from 'botframework-schema';"}],"quickstart":{"code":"import { Activity, ActivityTypes, MessageActivity, ChannelAccount } from 'botframework-schema';\n\n// Define a basic user account\nconst user: ChannelAccount = {\n  id: 'user123',\n  name: 'Test User',\n  role: 'user'\n};\n\n// Define a basic bot account\nconst bot: ChannelAccount = {\n  id: 'bot456',\n  name: 'Test Bot',\n  role: 'bot'\n};\n\n// Create a simple message activity conforming to the schema\nconst messageActivity: MessageActivity = {\n  type: ActivityTypes.Message,\n  id: 'message-1',\n  timestamp: new Date().toISOString(),\n  from: user,\n  recipient: bot,\n  conversation: {\n    id: 'convo-abc',\n    name: 'Test Conversation',\n    isGroup: false,\n    conversationType: 'personal'\n  },\n  channelId: 'emulator',\n  text: 'Hello, bot! How are you?',\n  locale: 'en-US'\n};\n\nconsole.log('Created a message activity:', messageActivity.text);\n\n// You can also create a generic activity and cast it if needed\nconst genericActivity: Activity = {\n  type: ActivityTypes.Trace,\n  id: 'trace-1',\n  timestamp: new Date().toISOString(),\n  text: 'Trace activity initiated.',\n  valueType: 'application/json',\n  value: { method: 'GET', path: '/api/data' }\n};\n\nconsole.log('Created a trace activity:', genericActivity.type, genericActivity.id);\n","lang":"typescript","description":"This example demonstrates how to import and create different types of `Activity` objects, including a `MessageActivity` and a generic `Trace` activity, conforming to the `botframework-schema` interfaces."},"warnings":[{"fix":"Upgrade your project's TypeScript version to 5.9 or higher by updating `typescript` in `devDependencies` and configuring your `tsconfig.json`.","message":"Version 4.23.3 and later dropped support for TypeScript 4.7. Projects must upgrade to TypeScript 5.9 or newer to compile successfully.","severity":"breaking","affected_versions":">=4.23.3"},{"fix":"Ensure your project runs on Node.js 18 or 20 (LTS versions are recommended). Update your Node.js runtime environment.","message":"Starting with version 4.23.0, Node.js versions prior to 18 are no longer supported. This change was necessitated by updates to underlying `Azure Identity` and `MSAL.Node` packages.","severity":"breaking","affected_versions":">=4.23.0"},{"fix":"Regularly update `botframework-schema` and its peer packages in the Bot Framework SDK to the latest versions to incorporate security fixes. Monitor release notes for any breaking changes in associated SDK packages.","message":"The `botframework-schema` package frequently receives dependency updates to address security vulnerabilities. While these updates are crucial, they can sometimes introduce transitive dependency changes.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install botframework-schema` (or `yarn add botframework-schema`). Verify your `tsconfig.json` includes `\"typeRoots\": [\"./node_modules/@types\", \"./typings\"]` and `\"moduleResolution\": \"Node\"` (for most projects) or `\"Node16\"` / `\"Bundler\"` for ESM.","cause":"The package is not installed, or the TypeScript configuration (`tsconfig.json`) does not correctly include `node_modules/@types` or `moduleResolution` is incorrect for your project type (e.g., CommonJS vs. ESM).","error":"TS2307: Cannot find module 'botframework-schema' or its corresponding type declarations."},{"fix":"When working with `channelData`, ensure your activity variable is typed as `MessageActivity` or explicitly cast it, e.g., `(activity as MessageActivity).channelData`. Always check for existence before accessing properties that are not universally present on all activity types.","cause":"The base `Activity` interface in `botframework-schema` does not have a `channelData` property directly. `channelData` is typically found on `MessageActivity` or other specific activity types, or it's implicitly added by the channel.","error":"Property 'channelData' does not exist on type 'Activity'."},{"fix":"Access `activity.text` directly as a string property, e.g., `const message = activity.text;`. If you intended to process text, use string methods like `activity.text.toLowerCase()`.","cause":"Attempting to call `text` as a function on an `Activity` object, but `activity.text` is a string property representing the message content.","error":"TypeError: activity.text is not a function"}],"ecosystem":"npm"}