Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
B

BotFramework-DirectLineJS

> 编程语言
Open source

JavaScript client library for Microsoft Bot Framework's Direct Line protocol

200 stars0 likes2 views
WebsiteGitHub

About

JavaScript client library for Microsoft Bot Framework's Direct Line protocol

Microsoft Bot Framework Direct Line JS Client

Client library for the Microsoft Bot Framework Direct Line protocol.

Used by WebChat and thus (by extension) Emulator, WebChat channel, and Azure Bot Service.

FAQ

Who is this for?

Anyone who is building a Bot Framework JavaScript client who does not want to use WebChat.

If you're currently using WebChat, you don't need to make any changes as it includes this package.

What is that funny subscribe() method in the samples below?

Instead of callbacks or Promises, this library handles async operations using Observables. Try it, you'll like it! For more information, check out RxJS.

Can I use TypeScript?

You bet.

How ready for prime time is this library?

This is an official Microsoft-supported library, and is considered largely complete. Future changes (aside from supporting future updates to the Direct Line protocol) will likely be limited to bug fixes, performance improvements, tutorials, and samples. The big missing piece here is unit tests.

That said, the public API is still subject to change.

Why the library did not detect Web Socket disconnections?

On iOS/iPadOS, when network change from Wi-Fi to cellular, the WebSocket object will be stalled without any errors. This is not detectable nor workaroundable without any additional assistance. The issue is related to an experimental feature named "NSURLSession WebSocket". The feature is enabled by default on iOS/iPadOS 15 and up.

An option named networkInformation can be used to assist the library to detect any connection issues. The option is based on W3C Network Information API and it should implement at least 2 members:

  • A type property to indicate the current network type
    • When the type is "offline", network is not available and no connection will be made
  • A change event should dispatch when the type property change

However, Safari on iOS/iPadOS does not support W3C Network Information API. It is up to web developers to implement the NetworkInformation polyfill.

One effective way to detect network type change is to subscribe to a Server-Sent Events source. The service would send a message every 30 seconds. If network type changed and current network type is no longer available, the connection will be closed prematurely and an error event will be dispatched to the EventSource instance. Upon receiving the error event, the NetworkInformation.type should then change to "offline". The browser would automatically retry the Server-Sent Events connection. Upon receiving an open event, the polyfill should change the type back to "unknown".

If the library is being used in a native iOS/iPadOS app, a less resource-intensive solution would be partially implementing the Network Information API using NWPathMonitor. When network change happens, the NetworkInformation instance should update the type property based on network type and dispatch a change event.

How to build from source

  1. Clone this repo
  2. npm install
  3. npm run build (or npm run watch to rebuild on every change, or npm run prepublishOnly to build production)

How to include in your app

There are several ways:

  1. Build from scratch and include either /directLine.js (webpacked with rxjs) or lib/directline.js in your app
  2. npm install botframework-directlinejs

Using from within a Node environment

This library uses RxJs/AjaxObserverable which is meant for use in a DOM environment. That doesn't mean you can't also use it from Node though, you just need to do a couple of extra things:

  1. npm install --save ws xhr2
  2. Add the following towards the top of your main application file:
typescript
global.XMLHttpRequest = require('xhr2');
global.WebSocket = require('ws');

How to create and use a directLine object

Obtain security credentials for your bot:

  1. If you haven't already, register your bot.
  2. Add a DirectLine (not WebChat) channel, and generate a Direct Line Secret. Make sure Direct Line 3.0 is enabled.
  3. For testing you can use your Direct Line Secret as a security token, but for production you will likely want to exchange that Secret for a Token as detailed in the Direct Line documentation.

Create a DirectLine object:

…

Post activities to the bot:

typescript
directLine
  .postActivity({
    from: { id: 'myUserId', name: 'myUserName' }, // required (from.name is optional)
    type: 'message',
    text: 'a message for you, Rudy'
  })
  .subscribe(
    id => console.log('Posted activity, assigned ID ', id),
    error => console.log('Error posting activity', error)
  );

You can also post messages with attachments, and non-message activities such as events, by supplying the appropriate fields in the activity.

Listen to activities sent from the bot:

typescript
directLine.activity$.subscribe(activity => console.log('received activity ', activity));

You can use RxJS operators on incoming activities. To see only message activities:

typescript
directLine.activity$
  .filter(activity => activity.type === 'message')
  .subscribe(message => console.log('received message ', message));

Direct Line will helpfully send your client a copy of every sent activity, so a common pattern is to filter incoming messages on from:

typescript
directLine.activity$
  .filter(activity => activity.type === 'message' && activity.from.id === 'yourBotHandle')
  .subscribe(message => console.log('received message ', message));

Monitor connection status

Subscribing to either postActivity or activity$ will start the process of connecting to the bot. Your app can listen to the connection status and react appropriately :

…

Reconnect to a conversation

If your app created your DirectLine object by passing a token, DirectLine will refresh that token every 15 minutes. Should your client lose connectivity (e.g. close laptop, fail to pay Internet access bill, go under a tunnel), connectionStatus$ will change to ConnectionStatus.ExpiredToken. Your app can request a new token from its server, which should call the Reconnect API. The resultant Conversation object can then be passed by the app to DirectLine.

typescript
var conversation = /* a Conversation object obtained from your app's server */;
directLine.reconnect(conversation);

Resume an existing conversation

When using DirectLine with WebChat, closing the current tab or refreshing the page will create a new conversation in most cases. You can resume an existing conversation to keep the user in the same context.

When using a secret you can resume a conversation by:

  • Storing the conversationid (in a permanent place, like local storage)
  • Giving this value back while creating the DirectLine object along with the secret
typescript
import { DirectLine } from 'botframework-directlinejs';

const dl = new DirectLine({
    secret: /* SECRET */,
    conversationId: /* the conversationid you stored from previous conversation */
});

When using a token you can resume a conversation by:

  • Storing the conversationid and your token (in a permanent place, like local storage)
  • Calling the DirectLine reconnect API yourself to get a refreshed token and a streamurl
  • Creating the DirectLine object using the ConversationId, Token, and StreamUrl
typescript
import { DirectLine } from 'botframework-directlinejs';

const dl = new DirectLine({
    token: /* the token you retrieved while reconnecting */,
    streamUrl: /* the streamUrl you retrieved while reconnecting */,
    conversationId: /* the conversationid you stored from previous conversation */
});

Getting any history that Direct Line has cached : you can retrieve history using watermarks: You can see the watermark as an activity 'bookmark'. The resuming scenario will replay all the conversation activities from the watermark you specify.

typescript
import { DirectLine } from 'botframework-directlinejs';

const dl = new DirectLine({
    token: /* the token you retrieved while reconnecting */,
    streamUrl: /* the streamUrl you retrieved while reconnecting */,
    conversationId: /* the conversationid you stored from previous conversation */,
    watermark: /* a watermark you saved from a previous conversation */,
    webSocket: false
});

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

Copyright (c) Microsoft Corporation. All rights reserved.

Issues· 81 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

TypeScript

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言