This sample demonstrates how to implement Web Chat in a way that does not expose your Direct Line secret to the browser.

When embedding Web Chat into a site, you must provide either your Direct Line secret or a Direct Line token so that Web Chat can communicate with the bot. The Direct Line secret can be used to access all of the bot's conversations, and it doesn't expire. A Direct Line token can only be used to access a single conversation, and it does expire. See the Direct Line Authentication documentation for more information.

Therefore, embedding Web Chat using the Direct Line secret directly is strongly discouraged because it would expose your secret on the client-side. Instead, the recommended approach is to exchange the secret for a Direct Line token on the server-side. This sample shows how to obtain and use the token.

Web Chat allows you to specify a user ID on the client-side, which will be sent in activities to the bot. However, this is susceptible to user impersonation because a malicious user could modify their user ID. Since the user ID typically isn't verified, this is a security risk if the bot stores sensitive data keyed on the user ID. For example, the built-in user authentication support in Azure Bot Service associates access tokens with user IDs.

To avoid impersonation, the recommended approach is for the server to bind a user ID to the Direct Line token. Then any conversation using that token will send the bound user ID to the bot. However, if the client is going to provide the user ID to the server, it is important for the server to validate the ID somehow (see below). Otherwise, a malicious user could still modify the user ID being sent by the client.

To keep things simple, this sample generates a random user ID on the server-side and binds it to the Direct Line token. While this mitigates impersonation concerns, the downside is that users will have a different ID every time they talk to the bot. If you need a consistent and validated user ID, see the Direct Line user token sample.

This sample contains three components:

• The backend API performs the Direct Line token acquisition. It generates a random user ID that will be bound to the Direct Line token.
• The UI is static HTML/JS that could be hosted using any web server. It makes a POST request to the backend API and uses the resulting Direct Line token to render Web Chat.
• The bot is a bare-bones bot that responds to every activity by sending the user's ID.

Depending on the scenario, the backend API could be called from a client (such as a single-page application) or a server (such as a more traditional web app). After receiving the Direct Line token, the caller can then use it to render Web Chat, and the bot will receive the randomly-generated user ID on every activity.

In this sample, the user is anonymous, so the API randomly generates a user ID:

// server.js

async function generateRandomUserId() {
    const buffer = await randomBytesAsync(16);
    return `dl_${buffer.toString('hex')}`;
}

// DirectLineTokenController.cs

private static string GenerateRandomUserId()
{
    byte[] tokenData = new byte[16];
    using var rng = new RNGCryptoServiceProvider();
    rng.GetBytes(tokenData);

    return $"dl_{BitConverter.ToString(tokenData).Replace("-", "").ToLower()}";
}

The user ID is prefixed with "dl_" as required by the Direct Line token API.

The API calls the Direct Line API to retrieve a Direct Line token. Notice that we pass the user ID in the body of the request:

// fetchDirectLineToken.js

const response = await fetch('https://directline.botframework.com/v3/directline/tokens/generate', {
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${secret}`,
    },
    method: 'post',
    body: JSON.stringify({ user: { id: userId } })
});

// DirectLineTokenService.cs

httpClient.BaseAddress = new Uri("https://directline.botframework.com/");

...

var fetchTokenRequestBody = new { user = new { id = userId } };

var fetchTokenRequest = new HttpRequestMessage(HttpMethod.Post, "v3/directline/tokens/generate")
{
    Headers =
    {
        { "Authorization", $"Bearer {directLineSecret}" },
    },
    Content = new StringContent(JsonSerializer.Serialize(fetchTokenRequestBody), Encoding.UTF8, MediaTypeNames.Application.Json),
};

var fetchTokenResponse = await _httpClient.SendAsync(fetchTokenRequest, cancellationToken);

The resulting Direct Line token will be bound to the passed user ID.

The UI calls the API and uses the resulting Direct Line token to render Web Chat:

// index.html

const res = await fetch('http://localhost:3000/api/direct-line-token', { method: 'POST' });
const { token } = await res.json();

window.WebChat.renderWebChat(
    {
    directLine: window.WebChat.createDirectLine({ token }),
    },
    document.getElementById('webchat')
);

Note that we do not specify a user ID when initiating Web Chat. Direct Line will handle sending the user ID to the bot based on the token.

• A registered Bot Framework bot (see documentation on registering a bot with Azure Bot Service)

1. Navigate to the bot directory.
2. Fill in the environment variables in the .env file, according to the following table:

   Variable	Description	Example value
   PORT	The port on which the bot server will run.	3978
   MICROSOFT_APP_ID	The app ID of the registered Bot Framework bot. Can be found in the Azure Bot Channels Registration resource.
   MICROSOFT_APP_SECRET	The app secret of the registered Bot Framework Bot. Issued during registration.

3. Run npm install to install the required dependencies.
4. Run npm start to start the bot.
5. Run ngrok to expose your bot to a public URL. For example:

   ngrok http -host-header=rewrite 3978

6. Update the messaging endpoint in your Bot Channels Registration to the ngrok URL. For example: https://abcdef.ngrok.io/api/messages

The sample API is available in multiple languages. Choose one and expand the corresponding section for specific steps.

1. Navigate to the ui directory.
2. Serve index.html on localhost:5500 using a web server.
   • A quick way to get started is using the http-server npm package. You can use npx to run it without installation:

     npx http-server ./ -p 5500

   • Another option is a local development server such as the Live Server Visual Studio Code extension.
3. Open http://localhost:5500 in a browser.