Connect a bot to Web Chat

Posted on by The Bot Framework Team

This post shows how to use the Web Chat channel to allow the user to communicate with a bot. This is done by embedding a Web Chat component  in a web page. The Web Chat component, referred here, is included in the Web Chat channel that is associated by default with a bot deployed in Azure. The following picture shows the components involved.

This post assumes that you already have a bot deployed in Azure. For information about deployment, see Deploy your bot.

Also the post gives guidance for developers. Since it uses a manual process to generate a token from a secret it is not intended for a production environment.

Background

The channel is the key connection mechanism that allows the exchange of information between a bot and a communication application. The Bot Framework Service, configured through the Azure portal, connects your bot to the channels and facilitates communication between your bot and the user.

When you create a bot , the Web Chat channel is automatically configured for you. The Web Chat channel includes the Web Chat component , which provides the ability for users to interact with a bot directly from a web page. The Web Chat component is a highly-customizable web-based client for the Bot Framework V4 SDK. For more information, see Connect a bot to channels.

The next sections show how to embed a bot in a web page.

Get the Web Chat channel secret key

  1. In your browser, navigate to Azure portal.
  2. Select your bot registration resource.
  3. In the left panel, click Channels.
  4. In the right panel, click the Edit link by the Web Chat channel.
  5. In the displayed Configure Web Chat wizard,  in the Secret keys section, click the Show button by any of the 2 keys.
  6. Copy a save the Secret key and the Embed code. You will use them when embedding the Web Chat component in a web page.
  7. Click Done.

Generate token and related URL

To avoid security problem it is important that you do not use the secret, generated above, directly in the iframe element. So the first thing you must do, is to generate a token based on the secret and then build the URL to assign to the src attribute in the iframe.

IN a web page, enter the content shown below. The page asks you to enter the Web Chat secret and the name of the bot as shown in the Azure portal. It then generates a URL to use in the iframe in a different page.

Notice that a token is valid for one conversation only; to start another conversation, you must generate a new token. Also this is a private page different form the public page containing the Web Chat control.

<!DOCTYPE html>
<html>
  <body>

      <h2>Generate URL based on token and bot name</h2>

      <span style="background-color:yellow; color:red; font-weight: bold;">Private Page</span><br/>

      This page generates a URL from the Web Chat channel secret and the bot App Service name. <br/>
      The Web Chat channel is associated with the bot to embed in a web page using the <b>iframe</b> element.<br/>
      The use of a token instead of the secret is <span style="background-color:yellow">important to avoid security breaches</span>. <br/>

      <p>
        Make sure to have the following information ready, obtained from the <a href="https://ms.portal.azure.com/">Azure portal</a>:
        <ol>
          <li><b>Bot secret</b>. The Web Chat channel secret.</li>.
          <li><b>Bot name</b>. The bot App Service name.</li>.
        </ol>
      </p>

      <hr style="border-top: 3px dashed red;"/>

      <h3>Enter Bot App Service information</h3>

      <form id="reqFormId" method="GET">
        <label for="secret" style="padding-right: 0px;">Bot Secret:</label>
        <input type="password" id="secretId" name="secret" style="width: 25%" placeholder="Enter secret"> <br/>
        <label for="bot name">Bot Name:</label>
        <input type="text" id="botId" name="bot" size="30" placeholder="Enter bot app service name"> <br/>
        <input type="button" value="Submit" onClick="getToken(this.form)">
      </form>

      <hr style="border-top: 3px dashed rgb(55, 0, 255);"/>

      Assign the following URL to the <b>src</b> attribute of the <b>iframe</b> element in the web page. It allows the user to interact with the bot. <br/> <br/>

      <div id="urlId" style="width: 600px; height: 200px; border: 1px solid black; padding: 2px 4px; overflow: auto; word-spacing: normal">URL here</div>

  </body>

  <script>

     // Add script shown below, 

  </script>

</html>

Add the following script to the previous page.

// Create an HTTP request object.
var xhr = new XMLHttpRequest();

/*
  Process the response. Get the URL.
**/
function processResponse(e) {
  if (xhr.readyState == 4  && xhr.status == 200) {
    var token = JSON.parse(xhr.responseText);

    // Get the bot app service name
    var botname = document.getElementById('botId').value

    // Evaluate the bot url.
    var url = 'https://webchat.botframework.com/embed/' + botname + '?t=' + token

    // alert("The bot url is " + url);

    var elUrl = document.getElementById('urlId');
    elUrl.innerText = url;

  }
}

/*
  Request the token based on the bot secret.
**/
function getToken(formElement)
{

  var secret = formElement['secretId'].value;

  // alert("The secret is " + secret);

  // Issue an HTTP request to generate the token from the secret.
  xhr.open('GET', "https://webchat.botframework.com/api/tokens", true);
  xhr.setRequestHeader('Authorization', 'BotConnector ' + secret);
  xhr.send();

  // Process the response asynchronously.
  xhr.onreadystatechange = processResponse;

  return false;
}

Copy and save the generated URL. You are going to assign it to the src attribute in the iframe element in the web page shown below.

Embed the bot in a web page

Create a web page and add the content shown below.  This page embeds a bot using the iframe element.

Make sure that you assign the URL to the src attribute in the iframe element.

<!DOCTYPE html>
<html>
<body>

    <h2>Web Chat bot client</h2>

    This page embeds a bot using the <b>iframe</b> element. <br/>
    Before you lunch the page, make sure that you assign the URL to the <b>src</b> attribute in the <b>iframe</b> element.<br/>
    Refer to the related example page to see how to generate the URL.<br/>

    <hr style="border-top: 3px dashed blue;"/>

    <p>
    <iframe src='<GENERATED URL>' style='width: 600px; min-height:500px;'/></iframe>
    </p>

</body>

</html>

The following is an example of how the page looks:

Posted in Bot Framework