One of the great things about the Bot Framework is that, out of the box, there’s a bunch of channels to hook your bot up to without having to worry about any of the plumbing of communicating with those services. the currently supported list of channels can be found here (although, the newly announced Microsoft Teams has not been added to that list yet).
But what do you do when the channels provided aren’t quite enough? That’s simple, you turn to Direct Line! Direct Line is a REST API for the bot framework that allows it’s users to create their own integrations. A great example of this is if you have a mobile app that you directly want to integrate a chat bot into. Microsoft aren’t going to make your app a channel for the Bot Framework as no one else will be able to ingrate with it but you can still get your users using your bot with Direct Line.
v3 of Direct Line
All of the documentation for the Direct Line API can be found on the Bot Framework site. Now, a little background on the first available version of the Direct Line API (v1.1); it sucked. It was quite flaky, prompts were styled as text and attachments were stripped out. There were a number of things that you could do to work around these issues but it was a pain. The new v3 version, however, is awesome and takes all of that pain away.
A client for v3
As well as releasing a new version of the API itself, the Bot Framework team released a new version of it’s Direct Client NuGet package. At the time of writing, the new version is still in beta so you will need to include pre-release packages in your search to find it. That particular fact caused me several hours of pain when trying to work out what was going on in a project of my own to later find out that I wasn’t using the latest package.
Getting started with the new Direct Line Client
Let’s take a look at the simplest way to get started using the Direct Line Client. The 3 things that we want to be able to do are; start a conversation, send some text as an activity and get the responses.
Start a conversation
To get started we need a class that creates an instance of
DirectLineClient and calls
StartConversationAsync on the
public class MyDirectLineIntegration
private readonly DirectLineClient _directLineClient;
private Conversation _conversation;
private string _watermark;
private const string From = "Kristian";
const string secret = "YOUR_SECRET";
public async Task StartConversation()
_conversation = await _directLineClient.Conversations
On line 12, we’re creating an instance of the client with our secret as an argument (your secret can be generated when activating the Direct Line channel for your bot). Lines 17 and 18 show how a conversation is started. We then want to keep a reference to the returned
Conversation object so that we can tell the Bot Framework that any messages we send or retrieve are for this specific conversation.
Once our conversation is started, we can start sending messages:
public async Task SendMessage(string message)
var fromProperty = new ChannelAccount(From);
var activity = new Activity(text: message, fromProperty: fromProperty, type: "message");
Activity object has many fields and it’s hard to find out what is the minimum required. To send a plain text message the only things required are your message as a string, a
ChannelAccount object that identifies the sender and a string which tells the Bot Framework what kind of activity we are sending (in most cases, this will be
ChannelAccount requires an id that is unique to each sender (the Bot Framework also allows group conversations with bots). Once that’s all set up, calling
PostActivityAsync with the
ConversationId from earlier and our activity will send our message to the bot.
Retrieving messages is very similar to sending messages:
public async Task<IList<Activity>> GetMessages()
var response = await _directLineClient.Conversations
_watermark = response.Watermark;
A call to
GetActivitiesAsync with the
watermark will ask the Bot Framework for any messages that are newer than the value of the watermark. With the response, we keep track of what the watermark is so that we only retrieve new messages every time. Although the
Watermark property type is string, it’s actually just a sequence number starting at 1 for activity in a given conversation.
This is just a quick intro into using the new Direct Line C# client. There are a few other things that the client can do that we didn’t cover (resuming a conversation from before and uploading files to a conversation) but this should be enough to get going with.
A quick TL;DR would look like this:
- Show pre-release packages when installing the Direct Line Client (currently, v3 is still in beta)
- Initialise the client with your Direct Line secret
- Start a conversation and keep a reference to at least the conversation id
- When sending messages be sure to include a
ConversationAccountwith an id unique to each user and to send
messageas the type
- When receiving messages, keep a reference to the current watermark to only get new messages
- The code shown here is available on my GitHub
EDIT: I originally didn’t specify that an
Activity sent to the Bot Framework required a
type. Not including a type will cause the Bot Framework to ignore your message! Almost always this type will be “message” but at times, may be something else