microsoft/BotFramework-DirectLineJS

microsoft/BotFramework-DirectLineJS

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

Language: TypeScript

License: MIT

Stars: 200

Forks: 130

Open issues: 90

Created: 2017-01-23T21:47:55Z

Pushed: 2026-06-17T06:48:57Z

Default branch: master

Fork: no

Archived: no

README: 

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

0. Clone this repo 1. npm install 2. 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:

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:

import { DirectLine } from 'botframework-directlinejs';
// For Node.js:
// const { DirectLine } = require('botframework-directlinejs');

var directLine = new DirectLine({
secret: /* put your Direct Line secret here */,
token: /* or put your Direct Line token here (supply secret OR token, not both) */,
domain: /* optional: if you are not using the default...