Key concepts in Direct Line API 3.0

You can enable communication between your bot and your own client application by using the Direct Line API. This article introduces key concepts in Direct Line API 3.0 and provides information about relevant developer resources.

Authentication

Direct Line API 3.0 requests can be authenticated either by using a secret that you obtain from the Direct Line channel configuration page in the Bot Framework Portal or by using a token that you obtain at runtime. For more information, see Authentication.

Starting a conversation

Direct Line conversations are explicitly opened by clients and may run as long as the bot and client participate and have valid credentials. For more information, see Start a conversation.

Sending messages

Using Direct Line API 3.0, a client can send messages to your bot by issuing HTTP POST requests. A client may send a single message per request. For more information, see Send an activity to the bot.

Receiving messages

Using Direct Line API 3.0, a client can receive messages from your bot either via WebSocket stream or by issuing HTTP GET requests. Using either of these techniques, a client may receive multiple messages from the bot at a time as part of an ActivitySet. For more information, see Receive activities from the bot.

Developer resources

Client libraries

The Bot Framework provides client libraries that facilitate access to Direct Line API 3.0 via C# and Node.js.

  • To use the .NET client library within a Visual Studio project, install the Microsoft.Bot.Connector.DirectLine NuGet package.

  • To use the Node.js client library, install the botframework-directlinejs library using NPM (or download the source).

As an alternative to using the C# or Node.js client libraries, you can generate your own client library in the language of your choice by using the Direct Line API 3.0 Swagger file.

Sample code

The BotBuilder-Samples GitHub repo contains multiple samples that show how to use Direct Line API 3.0 with C# and Node.js.

Sample Language Description
Direct Line Bot Sample C# A sample bot and a custom client communicating to each other using the Direct Line API.
Direct Line Bot Sample (using client WebSockets) C# A sample bot and a custom client communicating to each other using the Direct Line API and WebSockets.
Direct Line Bot Sample JavaScript A sample bot and a custom client communicating to each other using the Direct Line API.
Direct Line Bot Sample (using client WebSockets) JavaScript A sample bot and a custom client communicating to each other using the Direct Line API and WebSockets.

Web chat control

The Bot Framework provides a control that enables you to embed a Direct-Line-powered bot into your client application. For more information, see the Microsoft Bot Framework WebChat control.