Registry / communication / botframework-schema

botframework-schema

JSON →
library4.23.3jsnpmunverified

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.

npm install botframework-schema
INSTALL
IMPORT
SIG · BOTFRAMEWORK-SCHEM
B
botframework-schema
communicationjavascriptv4.23.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Activity
import { Activity } from 'botframework-schema';
import Activity from 'botframework-schema';
Activity is a named interface, not a default export.
ActivityTypes
import { ActivityTypes } from 'botframework-schema';
const ActivityTypes = require('botframework-schema').ActivityTypes;
ESM imports are preferred. `ActivityTypes` is a named enum for various activity kinds.
MessageActivity
import { MessageActivity } from 'botframework-schema';
Imports the specific interface for message activities, which extends the base `Activity` interface.

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.

import { Activity, ActivityTypes, MessageActivity, ChannelAccount } from 'botframework-schema'; // Define a basic user account const user: ChannelAccount = { id: 'user123', name: 'Test User', role: 'user' }; // Define a basic bot account const bot: ChannelAccount = { id: 'bot456', name: 'Test Bot', role: 'bot' }; // Create a simple message activity conforming to the schema const messageActivity: MessageActivity = { type: ActivityTypes.Message, id: 'message-1', timestamp: new Date().toISOString(), from: user, recipient: bot, conversation: { id: 'convo-abc', name: 'Test Conversation', isGroup: false, conversationType: 'personal' }, channelId: 'emulator', text: 'Hello, bot! How are you?', locale: 'en-US' }; console.log('Created a message activity:', messageActivity.text); // You can also create a generic activity and cast it if needed const genericActivity: Activity = { type: ActivityTypes.Trace, id: 'trace-1', timestamp: new Date().toISOString(), text: 'Trace activity initiated.', valueType: 'application/json', value: { method: 'GET', path: '/api/data' } }; console.log('Created a trace activity:', genericActivity.type, genericActivity.id);
Debug
Known issues
breakingVersion 4.23.3 and later dropped support for TypeScript 4.7. Projects must upgrade to TypeScript 5.9 or newer to compile successfully.
fix
Upgrade your project's TypeScript version to 5.9 or higher by updating `typescript` in `devDependencies` and configuring your `tsconfig.json`.
affects: >=4.23.3
breakingStarting 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.
fix
Ensure your project runs on Node.js 18 or 20 (LTS versions are recommended). Update your Node.js runtime environment.
affects: >=4.23.0
gotchaThe `botframework-schema` package frequently receives dependency updates to address security vulnerabilities. While these updates are crucial, they can sometimes introduce transitive dependency changes.
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.
affects: >=4.0.0
Errors
Common errors & fixes
TS2307: Cannot find module 'botframework-schema' or its corresponding type declarations.
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).
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.
Property 'channelData' does not exist on type 'Activity'.
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.
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.
TypeError: activity.text is not a function
Attempting to call `text` as a function on an `Activity` object, but `activity.text` is a string property representing the message content.
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()`.
Upgrade
Version history
4.23.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
44 hits · last 30 days
node
38
OpenAI (training)
1
Resources
botframework-schema — npm install botframework-schema · libregistry