Microsoft Bot Framework Direct Line JS Client

Common errors

• TypeError: Cannot read properties of undefined (reading 'subscribe')

  cause Attempting to use `activity$` or `connectionStatus$` as a Promise or regular value, when they are RxJS Observables.
  fix Ensure you call `.subscribe()` on the Observable to initiate the stream and receive values. Example: `directLine.activity$.subscribe(activity => { /* handle activity */ });`

• DirectLine error: token expired.

  cause The authentication token used to establish the Direct Line connection has become invalid or has expired.
  fix When `connectionStatus$` reports `ConnectionStatus.ExpiredToken`, your application should request a new token from your backend service and re-initialize or reconnect the `DirectLine` object with the fresh token.

• WebSocket connection to 'wss://directline.botframework.com/v3/directline/conversations/...' failed: WebSocket is closed before the connection is established.

  cause Often indicates an invalid or expired Direct Line secret/token, or a network issue preventing the initial WebSocket handshake.
  fix Verify that your `secret` or `token` is correct and active. If using a secret, ensure it hasn't been revoked. Check network connectivity and firewall rules. For production, always use a generated token from a secure backend.

• Silent message loss or unresponsive bot on iOS/iPadOS after network changes.

  cause The device's WebSocket connection silently stalls without error, as detailed in the `networkInformation` warning.
  fix Implement the `networkInformation` polyfill to detect network changes and proactively manage the Direct Line connection. Reloading the page or re-initializing DirectLine may temporarily resolve it.

Warnings

• gotcha The library utilizes RxJS Observables for all asynchronous operations (e.g., `activity$`, `connectionStatus$`). Developers unfamiliar with RxJS may encounter difficulties when expecting Promise-based or callback-style asynchronous patterns.
  Fix: Familiarize yourself with RxJS basics, especially `subscribe`, `pipe`, and common operators like `filter` and `map`.
• gotcha On iOS/iPadOS 15+, the `WebSocket` object may stall without errors when the network changes (e.g., Wi-Fi to cellular) due to an experimental 'NSURLSession WebSocket' feature. This prevents the library from detecting disconnections automatically.
  Fix: Implement the `networkInformation` option by providing a polyfill for the W3C Network Information API, which should include a `type` property and a `change` event. A common approach involves using Server-Sent Events to detect network status changes.
• gotcha Direct Line secrets should *never* be exposed in client-side code for production applications. They grant full access to your bot's Direct Line channel.
  Fix: Always exchange the Direct Line secret for a short-lived token on a secure backend server and pass only the token to your client application. The `DirectLine` constructor supports both `secret` and `token` options.
• deprecated Older versions of the library, particularly before 0.11.5, used different build output directories (`/dist/directLine.js` vs `/dist/directline.js`). While recent versions standardize `/lib/` for ESM and types, older client code might expect specific paths.
  Fix: Ensure your build tooling and import paths are updated to use the standard `/lib/` directory for ES modules and TypeScript definitions, or the lowercase `/dist/directline.js` for bundles if still relying on older UMD/CJS distribution.

Install

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

Imports

• DirectLine
  wrong:

  const DirectLine = require('botframework-directlinejs');

  correct:

  import { DirectLine } from 'botframework-directlinejs';

  The library primarily uses ES Modules. Named imports are the standard. CommonJS `require()` is not officially supported for modern usage and may lead to issues.
• ConnectionStatus
  wrong:

  import ConnectionStatus from 'botframework-directlinejs';

  correct:

  import { ConnectionStatus } from 'botframework-directlinejs';

  ConnectionStatus is a named enum export. Attempting a default import will fail.
• Activity

  import { Activity } from 'botframework-directlinejs';

  Imports the TypeScript interface or type definition for an Activity, which is crucial for type-checking when sending or receiving messages. While not a runnable class, it's a fundamental type.

Quickstart

This example demonstrates how to initialize the Direct Line client, monitor its connection status, receive messages from a bot using RxJS Observables, and send a message to the bot. It highlights secure token handling and proper cleanup.

import { DirectLine, ConnectionStatus, Activity } from 'botframework-directlinejs';
import { filter } from 'rxjs/operators';

// In a real application, retrieve this securely (e.g., from an environment variable or a server-side call)
const DIRECT_LINE_SECRET = process.env.DIRECT_LINE_SECRET ?? 'YOUR_DIRECT_LINE_SECRET_HERE';
const USER_ID = 'user123'; // A unique user ID for the conversation

console.log('Starting Direct Line client...');

const directLine = new DirectLine({
  secret: DIRECT_LINE_SECRET, // For production, exchange secret for a token via a backend service
  webSocket: true, // Use Web Sockets for real-time communication
  // token: 'YOUR_DIRECT_LINE_TOKEN_HERE' // Recommended for production
});

// Observe connection status changes
directLine.connectionStatus$.subscribe(connectionStatus => {
  const statusMessage = ConnectionStatus[connectionStatus];
  console.log(`Connection status: ${statusMessage}`);
  if (connectionStatus === ConnectionStatus.Uninitialized) {
    console.warn('Direct Line connection is uninitialized. Check your secret/token.');
  } else if (connectionStatus === ConnectionStatus.ExpiredToken) {
    console.error('Direct Line token expired. Reconnect with a new token.'); //
  }
});

// Subscribe to incoming activities from the bot
const activitySubscription = directLine.activity$
  .pipe(
    filter(activity => activity.type === 'message' && activity.from.id !== USER_ID)
  )
  .subscribe(activity => {
    console.log(`Received activity from bot:`);
    console.log(JSON.stringify(activity, null, 2));

    if (activity.text && activity.text.toLowerCase().includes('hello')) {
      console.log('Bot greeted us back!');
    }
  }, error => {
    console.error('Error receiving activities:', error);
  });

// Send a message to the bot after a brief delay
setTimeout(() => {
  const message: Activity = {
    from: { id: USER_ID, name: 'Test User' },
    type: 'message',
    text: 'Hello bot!',
    channelData: { clientActivityID: Date.now().toString() } // Unique ID for client activity
  };

  directLine.postActivity(message).subscribe(
    id => console.log(`Sent activity with ID: ${id}`),
    error => console.error('Error sending activity:', error)
  );
}, 3000);

// Disconnect after some time (e.g., when the user leaves the chat)
setTimeout(() => {
  console.log('Ending conversation and disconnecting...');
  activitySubscription.unsubscribe();
  directLine.end(); // Clean up Direct Line connection
}, 15000); // Disconnect after 15 seconds for this example