BotFramework DirectLine API Server

The Bot Framework DirectLine API Server extension is designed with the Bot Framework developer in mind. It's purpose is to easily allow a developer to "spin up" a token server for use with their BotFramework-DirectLineJS based clients, such as Web Chat or any other custom-built solutions.

By updating the (localhost) port and including the Bot Framework DirectLine channel secret, a token server can be started with a click of a button. Thus, saving the developer time that can be better used in actual development.

This is accomplished by use of the DirectLine API, part of Microsoft's Bot Framework ecosystem, which provides a set of endpoints useful in communicating with a Bot Framework bot. The DirectLine APIs serve as the bridge between the user's client and the DirectLine service connector/bot. User input is sent to the DirectLine service, in the form of an outgoing activity, which then forwards it to the bot (user => bot). It also receives incoming activities which can then be displayed to the user (bot => user).

Why is a token server necessary when the DirectLine channel secret can be used directly within the client?

There are a number of reasons, but the primary reason is security. Most clients that use DirectLine are HTML-based which typically means any of the code is accessible to anyone willing to look. Storing the secret in a browser-sided script is a high security risk.

By using a token server, the secret is stored on a seperate server. A call to the token server will, subsequently, call the DirectLine service exchanging the secret for a token. This token is returned back to the client finalizing the connection.

The Bot Framework DirectLine API Server extension removes all of that complexity allowing for a quick and easy implementation.

Features

• Option to enter the bot's DirectLine channel secret (required)
  • Secrets, once stored in settings, are encrypted for security purposes
• Option to clear the secret from settings
• Option to enter a valid port for use by the local server
  • If the port is not specified by the developer, it will default to port 3000
• Option to start and stop the local server

Requirements

• A Microsoft Azure bot registration
• The DirectLine channel enabled within the bot registration
• The DirectLine channel secret
• An available port on your system

Additional Requirements

• A bot built with one of the following tools:
  • Bot Framework SDK
  • Bot Framework Composer
  • Power Virtual Agent (PVA)
  • Botkit (when configured with a Bot Framework adapter)
• A client built using BotFramework-DirectLineJS library, such as BotFramework-WebChat
• A tunneling service (ngrok, for example)

Usage

Now that you have a running server, it's time to put it to work.

To get a token for use in your DirectLine-based client, make a POST request like below. fetch() is used here, but you can use whichever library you like.

const res = await fetch( 'http://localhost:3000/directline/conversations', { method: 'POST' } );
let { token } = await res.json();

[...]

window.WebChat.renderWebChat(
  {
    directLine: await window.WebChat.createDirectLine({ token })
  },
  document.getElementById( 'webchat' )
);

Please note: Two assumptions are being made about the above code:

1. Default port 3000 is being used, and
2. BotFramework-WebChat is the preferred client

However, one, both, or neither may be used. It is entirely up to you!

Extension Settings

This extension contributes the following settings:

• botframework-directline-api-server.clearDirectLineSecret: Clears the DirectLine channel secret from settings
• botframework-directline-api-server.setDirectLineSecret: Stores the DirectLine channel secret in settings for use in underlying API calls
• botframework-directline-api-server.setDirectLineServerPort: Stores the preferred port in settings for use when starting the local server
• botframework-directline-api-server.startServer: Starts the local server at http://localhost:[PORT]
• botframework-directline-api-server.stopServer: Stops the local server

Known Issues

• Issue #17. Clicking 'Clear DirectLine Secret' only clears the configuration setting of the value. It does not clear the store. This allows the server to be restarted without a new secret having been supplied.

Release Notes

1.0.3

• Necessary republish to VS Code Extension Market to correct a deployment issue.
• Minor changes to package.json included.
• Updates release info in READEME.md and CHANGELOG.md

Reference the CHANGELONG.md file to view all past changes.

To-Do

• [ ] Option to export the token server as code for use in production
• [ ] Add server state to status bar
• [ ] Option to randomly set the user id
• [ ] Option to manually set the user id
• [ ] Ability to call different DirectLine APIs
  • [ ] Token
  • [ ] Refresh token
  • [ ] Reconnect
  • [ ] History
  • [ ] Speech Services
  • [ ] DirectLine ASE
• [ ] Option to pass in custom API
• [ ] Option to pass in custom headers
• [ ] Enable/Disable logging
• [ ] Option to run multiple servers, simultaneously
• [ ] Add tests
• [ ] Convert to TS project
• [ ] Improve extension activation time