Using the Direct Line API to communicate with your Bot Framework Chatbot

I’ve been doing a lot with voice enabled chatbots recently and making programmatic connections to existing bots.

One thing I’ve been experimenting with is surfacing existing chatbots in other systems. You can use out of the box Channels to help you do this but sometimes there might not be a Channel that matches your use case.

One option is to write your own customer adapter to surface your bot in the channel that you need.

Another way to communicate with your bot is by using the Direct Line API. I’ve used the Direct Line API with JavaScript before so was already familiar with it but hadn’t used it with C#.

In this blog post I’ll show you how to perform some basic interaction with your chatbot using the Direct Line and C#.

We’ll see how to:

• Start a conversation with the chatbot
• Send a message to the chatbot
• Get the responses to our message from the chatbot

Note: This blog assumes that you already have a chatbot hosted in Azure and have obtained your DirectLine Secret Token.

Direct Line Client

The Direct Line API can be accessed from a NuGet package. This makes is easy for you to access the core features of the API an interact with your bot. I’m create my own class to encapsulate the main methods we’re implementing.

We’ll call this DirectLineInterface.  It’ll have the following private variables:

string directLineSecret = XXXXX

string botId = YYYYY

string fromUser = "testuser";

Microsoft.Bot.Connector.DirectLine.DirectLineClient _directLineInterface;

Conversation _conversation;

string _watermark;

The constructor for DirectLineInterface instantiates an instance of the DirectLineClient and passes in our DirectLineSecret. You can get this secrete from the Azure Portal.

public DirectLineInterface()
{
  _ directLineInterface = new DirectLineInterface(directLineSecret);
}

We need 3 more methods to let us:

• Start a conversation
• Send a message to the bot
• Receive a message from our bot

Let’s look at the code for these 3 methods.

Starting a Conversation

This method lets us make a connection to our chatbot in Azure. It returns a Conversation object.  This gets placed into the private variable for our class:

public Conversation StartConversation()
{
  _conversation = _directLineInterface.Conversations.StartConversation();

  return _conversation;
}

Next, we need some code to send a message to our bot.

Sending a Message

This method lets use send a message to the bot.  We create an Activity and set the parameters.  The parameter fromProperty is the sender of the message.

public ResourceResponse SendMessage(string message)
{
  var fromProperty = new ChannelAccount(fromUser);

  var activity = new Activity(text: message, fromProperty: fromProperty, type: "message");

  return _directLineInterface.Conversations.PostActivity(_conversation.ConversationId,   activity);
}

After creating the Activity we send it to our bot using the Direct Line Clients PostActivity method.

Receiving Messages

We need a way to get response from our bot. A method GetMessages will let us do this.  In this method we take the conversation that we got from StartConversation and find the ID. We then pass this into the Direct Line Clients GetActivities method:

public IList<Activity> GetMessages()
{
  var response = _directLineInterface.Conversations.GetActivities(_conversation.ConversationId, _watermark);

  _watermark = response.Watermark;

  return response.Activities;
}

We then return the list of Activities to the caller.

One thing to note is that we’re also setting a private variable called _watermark.

This value is sent by your bot with each response.  Any code you write needs to keep track of this value.  Failure to do so can mean your client may not be able to reconnect to your bot or receive the most recent collection of messages.

You can read more about processing messages here.

Testing It Out

With all the pieces in play we can take our client for a spin. We’ll do this in a console application. In this code we create an instance of our interface.  We send a message and then fetch the responses:

static void Main(string[] args)
{
  DirectLineInterface integration = new DirectLineInterface();

  integration.StartConversation();

  integration.SendMessage("hi");

  var list = integration.GetMessages();

  foreach (Microsoft.Bot.Connector.DirectLine.Activity a in list)
  {
    Console.WriteLine(a.Text);
  }

}

After running the console application, we can see that a message has been sent (hi) and our bot sent a response:

Granted this is a simple example but it’s shown that that we’re able to connect to our chatbot using the Direct Line with C#.

Summary

In this blog post we’ve seen how to programmatically connect to a chatbot in Azure using the Direct Line API.  One other way to connect to the Direct Line API us by using Web Sockets. That might be the subject of a future blog post.  Let me know if you’d like to see that or have further questions.