Bot Framework Activity Schema

Common errors

• TS2307: Cannot find module 'botframework-schema' or its corresponding type declarations.

  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).
  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'.

  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.
  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

  cause 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()`.

Warnings

• breaking Version 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`.
• breaking 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.
  Fix: Ensure your project runs on Node.js 18 or 20 (LTS versions are recommended). Update your Node.js runtime environment.
• gotcha The `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.

Install

• npm install botframework-schema npm
• yarn add botframework-schema yarn
• pnpm add botframework-schema pnpm

Imports

• Activity
  wrong:

  import Activity from 'botframework-schema';

  correct:

  import { Activity } from 'botframework-schema';

  Activity is a named interface, not a default export.
• ActivityTypes
  wrong:

  const ActivityTypes = require('botframework-schema').ActivityTypes;

  correct:

  import { ActivityTypes } from 'botframework-schema';

  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.

Quickstart

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);