Connect a bot to Direct Line

Article
11/16/2022

This article describes how to connect a bot to the Direct Line channel. Use this channel to communicate with a bot via your client application.

Note

Direct Line is a standard channel over HTTPS protocol to allow communication between a client application and a bot. If you require network isolation instead, use the Direct Line App Service Extension over WebSockets.

Prerequisites

An Azure account. If you don't already have one, create a free account before you begin.
An existing bot published to Azure.

Add the Direct Line channel

The first thing you need to do is to add the Direct Line channel to your bot.

Go to the Azure portal.
Go to your Azure Bot resource. Under Bot Settings, select Channels.
Select Direct Line from the list of Available Channels.

Your bot's now configured to use Direct Line using the Default site.

Alternatively, you can add a new site instead of using the default site. Select the New site button on the Direct Line channel page to create a new site. Direct Line new site button in Azure portal

Manage secret keys

When you add the Direct Channel, the Bot Framework generates secret keys. Your client application uses these keys to authenticate the Direct Line API requests that it issues to communicate with a bot. For more information, see Authentication.

To view a site's Direct Line secret in plain text, go to the Direct Line channel page.
Select the Direct Line tab, then the site you want to get the key for, such as Default_Site. Azure will open a Configure the site pane.
Under Secret keys, select the eye icon next to the corresponding key.
Copy and securely store the key. Use the key to authenticate the Direct Line API requests that your client application issues to communicate with a bot.

Note

Secrets shouldn't be exposed or embedded in client applications. See next step.
The best practice is to use the Direct Line API to exchange the key for a token. The client application then will use the token to authenticate its requests within the scope of a single conversation.

Configure settings

To configure your site settings:

On the Direct Line channel page, select the site you want to configure from the Sites list. The Configure the site pane will open, shown below:
Select the Direct Line protocol version that your client application will use to communicate with a bot.

Tip

If you're creating a new connection between your client application and bot, use Direct Line API 3.0.
When finished, select Apply to save the site configuration. Repeat this process, beginning with a new site, for each client application that you want to connect to your bot.

Configure enhanced authentication

One of the available site configurations is Enhanced authentication options, which helps to mitigate security risks when connecting to a bot (using the Web Chat control, for example). For more information, see Direct Line enhanced authentication.

To add enhanced authentication:

Enable Enhance authentication options. A message that says "You must have at least one trusted origin." will appear with an Add a trusted origin link. If you enable the enhanced authentication, you must specify at least one trusted origin.

A trusted origin is a domain used by the system to authenticate users. In this case, Direct Line uses the domain to generate a token.
- If you configure trusted origins as part of the configuration UI page, these settings will always be used as the only set for the generation of a token. Sending additional trusted origins (or setting trusted origins to none) when either generating a token or starting a conversation will be ignored (they aren't appended to the list or cross validated).
- If you didn't enable enhanced authentication, any origin URL you send as part of the API calls will be used.
After adding a trusted domain URL, select Apply.

Direct Line example bot

You can download a .NET example from this location: Direct Line Bot Sample.

The example contains two projects:

DirectLineBot. It creates a bot to connect via a Direct Line channel.
DirectLineClient. This is a console application that talks to the previous bot via Direct Line channel.

Direct Line API

Credentials for the Direct Line API must be obtained from the Azure Bot registration, and will only allow the caller to connect to the bot for which they were generated. In the bot project, update the appsettings.json file with these values.
```
{
"MicrosoftAppId": "",
"MicrosoftAppPassword": ""
}
```
In the Azure portal, enable Direct Line in the channels list, and then configure the Direct Line secret. Make sure that the checkbox for version 3.0 is checked. In the console client project, update the App.config file with the Direct Line secret key and the bot handle (Bot ID).
```
<appSettings>
    <add key="DirectLineSecret" value="YourBotDirectLineSecret" />
    <add key="BotId" value="YourBotHandle" />
</appSettings>
```

User messages are sent to the bot using the Direct Line Client Conversations.PostActivityAsync method using the ConversationId generated previously.

while (true)
{
    string input = Console.ReadLine().Trim();

    if (input.ToLower() == "exit")
    {
        break;
    }
    else
    {
        if (input.Length > 0)
        {
            Activity userMessage = new Activity
            {
                From = new ChannelAccount(fromUser),
                Text = input,
                Type = ActivityTypes.Message
            };

            await client.Conversations.PostActivityAsync(conversation.ConversationId, userMessage);
        }
    }
}

Share via