core-DirectLine

Direct Line Bot Sample

A sample bot and a custom client communicating to each other using the Direct Line API.

Prerequisites

The minimum prerequisites to run this sample are:

• Latest Node.js with NPM. Download it from here.
• The Bot Framework Emulator. To install the Bot Framework Emulator, download it from here. Please refer to this documentation article to know more about the Bot Framework Emulator.
• Register your bot with the Microsoft Bot Framework. Please refer to this for the instructions. Once you complete the registration, update your bot configuration with the registered config values (See Debugging locally using ngrok or Deploying to Azure
• [Recommended] Visual Studio Code for IntelliSense and debugging, download it from here for free.

Direct Line API

Credentials for the Direct Line API must be obtained from the Bot Framework developer portal, and will only allow the caller to connect to the bot for which they were generated. In the Bot Framework developer portal, enable Direct Line in the channels list and then, configure the Direct Line secret and update its value in DirectLineClient's app.js (directLineSecret variable). Make sure that the checkbox for version 3.0 [PREVIEW] is checked. Refer to this for more information on how to configure channels.

Publish

Also, in order to be able to run and test this sample you must publish your bot, for example to Azure. Alternatively, you can Debug locally using ngrok. Remember to update the environment variables with the MICROSOFT_APP_ID and MICROSOFT_APP_PASSWORD on the .env file.

Code Highlights

The Direct Line API is a simple REST API for connecting directly to a single bot. This API is intended for developers writing their own client applications, web chat controls, or mobile apps that will talk to their bot. In this sample, we are using the Direct Line Swagger file and Swagger JS to create a client for Node that will simplify access to the underlying REST API. Check out the client's app.js to see the client initialization.

var directLineSecret = 'DIRECTLINE_SECRET';
var directLineClientName = 'DirectLineClient';
var directLineSpecUrl = 'https://docs.botframework.com/en-us/restapi/directline3/swagger.json';

var directLineClient = rp(directLineSpecUrl)
    .then(function (spec) {
        // client
        return new Swagger({
            spec: JSON.parse(spec.trim()),
            usePromise: true
        });
    })
    .then(function (client) {
        // add authorization header to client
        client.clientAuthorizations.add('AuthorizationBotConnector', new Swagger.ApiKeyAuthorization('Authorization', 'Bearer ' + directLineSecret, 'header'));
        return client;
    })
    .catch(function (err) {
        console.error('Error initializing DirectLine client', err);
    });

Each conversation on the Direct Line channel must be explicitly started using the client.Conversations.Conversations_StartConversation() function. Check out the client's app.js createConversation function which creates a new conversation.

// once the client is ready, create a new conversation 
directLineClient.then(function (client) {
    client.Conversations.Conversations_StartConversation()                          // create conversation
        .then(function (response) {
            return response.obj.conversationId;
        })                            // obtain id
        .then(function (conversationId) {
            sendMessagesFromConsole(client, conversationId);                        // start watching console input for sending new messages to bot
            pollMessages(client, conversationId);                                   // start polling messages from bot
        });
});

Once the conversation is created, a conversationId is returned that we can use to call other endpoints to poll or send messages and other activities. User messages are sent to the Bot using the Direct Line Client client.Conversations.Conversations_PostActivity function using the conversationId generated in the previous step.

// send message
client.Conversations.Conversations_PostActivity(
    {
        conversationId: conversationId,
        activity: {
            textFormat: 'plain',
            text: input,
            type: 'message',
            from: {
                id: directLineClientName,
                name: directLineClientName
            }
        }
    }).catch(function (err) {
        console.error('Error sending message:', err);
    });

Messages from the Bot are continually polled from the API using an interval. Check out the client's app.js usage of client.Conversations.Conversations_GetActivities function which retrieves conversation messages newer than the stored watermark. Messages are then filtered from anyone but our own client using the printMessages function.

var watermark = null;
setInterval(function () {
    client.Conversations.Conversations_GetActivities({ conversationId: conversationId, watermark: watermark })
        .then(function (response) {
            watermark = response.obj.watermark;                                 // use watermark so subsequent requests skip old messages 
            return response.obj.activities;
        })
        .then(printMessages);
}, pollInterval);

DirectLine v3.0 (unlike version 1.1) has supports for Attachments (see Send and receive attachments for more information about attachments). Check out the printMessage function to see how the Attachments are retrieved and rendered appropriately based on their type.

function printMessage(activity) {
    if (activity.text) {
        console.log(activity.text);
    }

    if (activity.attachments) {
        activity.attachments.forEach(function (attachment) {
            switch (attachment.contentType) {
                case "application/vnd.microsoft.card.hero":
                    renderHeroCard(attachment);
                    break;

                case "image/png":
                    console.log('Opening the requested image ' + attachment.contentUrl);
                    open(attachment.contentUrl);
                    break;
            }
        });
    }
}

Outcome

To run the sample, you'll need to run both Bot and Client apps.

• Running Bot app
  1. Open a CMD console and CD to sample's DirectLineBot directory
  2. Run node app.js
• Running Client app
  1. Open a CMD console and CD to sample's DirectLineClient directory
  2. Run node app.js

To test the ChannelData custom messages type in the Client's console show me a hero card or send me a botframework image and you should see the following outcome.

More Information

To get more information about how to get started in Bot Builder for Node and Direct Line API please review the following resources:

• Bot Builder for Node.js Reference
• Bot Framework FAQ
• Direct Line API - v3.0
• Direct Line Swagger file - v3.0
• Swagger-JS
• Send and receive attachments
• Debugging locally using ngrok