Use the backchannel mechanism in the v3 JavaScript SDK

  • Article

APPLIES TO: SDK v3

The open source web chat control communicates with bots by using the Direct Line API, which allows activities to be sent back and forth between client and bot. The most common type of activity is message, but there are other types as well. For example, the activity type typing indicates that a user is typing or that the bot is working to compile a response.

You can use the backchannel mechanism to exchange information between client and bot without presenting it to the user by setting the activity type to event. The web chat control will automatically ignore any activities where type="event".

Walk through

The open source web chat control accesses the Direct Line API by using a JavaScript class called DirectLineJS. The control can either create its own instance of Direct Line, or it can share one with the hosting page. If the control shares an instance of Direct Line with the hosting page, both the control and the page will be capable of sending and receiving activities. The following diagram shows the high-level architecture of a website that supports bot functionality by using the open source web (chat) control and the Direct Line API.

Backchannel

Sample code

In this example, the bot and web page will use the backchannel mechanism to exchange information that is invisible to the user. The bot will request that the web page change its background color, and the web page will notify the bot when the user clicks a button on the page.

Note

The code snippets in this article originate from the backchannel sample and the backchannel bot.

Client-side code

First, the web page creates a DirectLine object.

var botConnection = new BotChat.DirectLine(...);

Then, it shares the DirectLine object when creating the WebChat instance.

BotChat.App({
    botConnection: botConnection,
    user: user,
    bot: bot
}, document.getElementById("BotChatGoesHere"));

When the user clicks a button on the web page, the web page posts an activity of type "event" to notify the bot that the button was clicked.

const postButtonMessage = () => {
    botConnection
        .postActivity({type: "event", value: "", from: {id: "me" }, name: "buttonClicked"})
        .subscribe(id => console.log("success"));
    }

Tip

Use the attributes name and value to communicate any information that the bot may need in order to properly interpret and/or respond to the event.

Finally, the web page also listens for a specific event from the bot. In this example, the web page listens for an activity where type="event" and name="changeBackground". When it receives this type of activity, it changes the background color of the web page to the value specified by the activity.

botConnection.activity$
    .filter(activity => activity.type === "event" && activity.name === "changeBackground")
    .subscribe(activity => changeBackgroundColor(activity.value))

Server-side code

The backchannel bot creates an event by using a helper function.

var bot = new builder.UniversalBot(connector, 
    function (session) {
        var reply = createEvent("changeBackground", session.message.text, session.message.address);
        session.endDialog(reply);
    }
);

const createEvent = (eventName, value, address) => {
    var msg = new builder.Message().address(address);
    msg.data.type = "event";
    msg.data.name = eventName;
    msg.data.value = value;
    return msg;
}

Likewise, the bot also listens for events from the client. In this example, if the bot receives an event with name="buttonClicked", it will send a message to the user to say "I see that you clicked a button."

bot.on("event", function (event) {
    var msg = new builder.Message().address(event.address);
    msg.data.textLocale = "en-us";
    if (event.name === "buttonClicked") {
        msg.data.text = "I see that you clicked a button.";
    }
    bot.send(msg);
})

Additional resources