Verbinden eines Bots mit dem WebchatConnect a bot to Web Chat

gilt für: SDK v4APPLIES TO: SDK v4

Wenn Sie einen Bot mit dem Framework-Bot Service erstellen, wird der Webchat automatisch für Sie konfiguriert.When you create a bot with the Framework Bot Service, the Web Chat channel is automatically configured for you. Der Webchat-Kanal enthält das Webchat-Steuerelement,das Benutzern die Möglichkeit bietet, direkt auf einer Webseite mit dem Bot zu interagieren.The Web Chat channel includes the Web Chat control, which provides the ability for users to interact with the bot directly in a web page.

Webchatbeispiel

Der Webchat-Kanal im Bot Framework-Portal enthält alles, was Sie zum Einbetten des Webchat-Steuerelements in eine Webseite benötigen.The Web Chat channel in the Bot Framework Portal contains everything you need to embed the Web Chat control in a web page. Zur Nutzung des Webchat-Steuerelements müssen Sie nur den geheimen Schlüssel des Bots abrufen und das Steuerelement in eine Webseite einbetten.All you have to do to use the web chat control is get your bot's secret key and embed the control in a web page.

Webchat SicherheitsüberlegungenWeb Chat security considerations

Wenn Sie die Azure Bot Service-Authentifizierung mit Web Chat verwenden, müssen einige wichtige Sicherheitsaspekte beachtet werden.When you use Azure Bot Service authentication with Web Chat there are some important security considerations you must keep in mind. Weitere Informationen finden Sie unter Sicherheitsüberlegungen.Please, refer to Security considerations.

Einbetten des Webchat-Steuerelements in eine WebseiteEmbed the Web Chat control in a web page

Die folgende Abbildung zeigt die Komponenten, die beim Einbetten des Webchat Steuerelements in eine Webseite beteiligt sind.The following picture shows the components involved when embedding the Web Chat control in a web page.

Bot-Einbettungskomponenten

Wichtig

Wie in der vorherigen Abbildung zu sehen ist, müssen Sie Direct Line (mit erweiterter Authentifizierung) verwenden, um Sicherheitsrisiken beim Herstellen einer Verbindung mit einem Bot mithilfe des Webchat verringern.As the previous picture implies, you need to use Direct Line (with enhanced authentication) to mitigate security risks when connecting to a bot using the Web Chat control. Weitere Informationen finden Sie unter Direct Line der erweiterten Authentifizierung.For more information, see Direct Line enhanced authentication.

Abrufen des geheimen BotschlüsselsGet your bot secret key

  1. Öffnen Sie Ihren Bot im Azure-Portal, und klicken Sie auf das Blatt Kanäle.Open your bot in the Azure Portal and click Channels blade.

  2. Klicken Sie in der Zeile für den Webchatkanal auf Bearbeiten.Click Edit for the Web Chat channel.

    Webchatkanal

  3. Klicken Sie unter Secret keys (Geheime Schlüssel) unter dem ersten Schlüssel auf Anzeigen.Under Secret keys, click Show for the first key.

    Geheimer Schlüssel

  4. Kopieren Sie den geheimen Schlüssel und den Einbettungscode.Copy the Secret key and the Embed code.

  5. Klicken Sie auf Fertig.Click Done.

Einbettungsoptionen für die EntwicklungDevelopment embedding options

Option 1: Austauschen Ihres Geheimnisses gegen ein Token und Generieren der EinbettungOption 1 - Exchange your secret for a token, and generate the embed

Verwenden Sie diese Option, wenn Sie eine Server-zu-Server-Anforderung ausführen, um Ihr Webchatgeheimnis gegen ein temporäres Token einzutauschen,Use this option if you can execute a server-to-server request to exchange your web chat secret for a temporary token, and if you want to make it difficult for other developers to embed your bot in their websites. und wenn Sie es anderen Entwicklern erschweren möchten, den Bot in ihre Website einzubetten.Although using this option will not absolutely prevent other developers from embedding your bot in their websites, it does make it difficult for them to do so.

So tauschen Sie Ihr Geheimnis gegen ein Token ein und erstellen den Einbettungscode:To exchange your secret for a token and generate the embed:

  1. Senden Sie eine GET-Anforderung an https://webchat.botframework.com/api/tokens, und übergeben Sie das Webchatgeheimnis mithilfe des Authorization-Headers.Issue a GET request to https://webchat.botframework.com/api/tokens and pass your web chat secret via the Authorization header. Der Authorization-Header verwendet das BotConnector-Schema und enthält Ihr Geheimnis, wie in der unten stehenden Beispielanforderung gezeigt wird.The Authorization header uses the BotConnector scheme and includes your secret, as shown in the example request below.

  2. Die Antwort auf Ihre GET-Anforderung enthält das Token (in Anführungszeichen eingeschlossen), mit dem eine Konversation gestartet werden kann. Hierzu muss das Webchat-Steuerelement innerhalb eines iframe-Tags gerendert werden.The response to your GET request will contain the token (surrounded with quotation marks) that can be used to start a conversation by rendering the web chat control within an iframe. Ein Token ist nur für eine Konversation gültig. Wenn Sie eine weitere Konversation starten möchten, müssen Sie ein neues Token erstellen.A token is valid for one conversation only; to start another conversation, you must generate a new token.

  3. Ändern Sie im Einbettungscodeiframe, den Sie aus dem Webchatkanal im Bot Framework-Portal kopiert haben (siehe Abrufen des geheimen Botschlüssels oben) den s=-Parameter in t=, und ersetzen Sie „YOUR_SECRET_HERE“ durch Ihr Token.Within the iframe Embed code that you copied from the Web Chat channel within the Bot Framework Portal (as described in Get your bot secret key above), change the s= parameter to t= and replace "YOUR_SECRET_HERE" with your token.

Hinweis

Tokens werden automatisch verlängert, bevor sie ablaufen.Tokens will automatically be renewed before they expire.

BeispielanforderungExample request
requestGET https://webchat.botframework.com/api/tokens
Authorization: BotConnector YOUR_SECRET_HERE

Hinweis

Beachten Sie, dass Azure Government url für den Tokenaustausch anders ist.Please note that for Azure Government, the token exchange URL is different.

requestGET https://webchat.botframework.azure.us/api/tokens
Authorization: BotConnector YOUR_SECRET_HERE
BeispielantwortExample response
"IIbSpLnn8sA.dBB.MQBhAFMAZwBXAHoANgBQAGcAZABKAEcAMwB2ADQASABjAFMAegBuAHYANwA.bbguxyOv0gE.cccJjH-TFDs.ruXQyivVZIcgvosGaFs_4jRj1AyPnDt1wk1HMBb5Fuw"
Beispiel-iframe (mithilfe eines Tokens)Example iframe (using token)
<iframe src="https://webchat.botframework.com/embed/YOUR_BOT_ID?t=YOUR_TOKEN_HERE"></iframe>

Hinweis

Beachten Sie, dass Azure Government beispiel iframe anders aussieht.Please note that for Azure Government, the example iframe looks different.

<iframe src="https://webchat.botframework.azure.us/embed/YOUR_BOT_ID?t=YOUR_TOKEN_HERE"></iframe>
Beispiel-HTML-CodeExample html code
<!DOCTYPE html>
<html>
<body>
  <iframe id="chat" style="width: 400px; height: 400px;" src=''></iframe>
</body>
<script>

    var xhr = new XMLHttpRequest();
    xhr.open('GET', "https://webchat.botframework.com/api/tokens", true);
    xhr.setRequestHeader('Authorization', 'BotConnector ' + 'YOUR SECRET HERE');
    xhr.send();
    xhr.onreadystatechange = processRequest;

    function processRequest(e) {
      if (xhr.readyState == 4  && xhr.status == 200) {
        var response = JSON.parse(xhr.responseText);
        document.getElementById("chat").src="https://webchat.botframework.com/embed/<botname>?t="+response
      }
    }

  </script>
</html>

Option 2: Betten Sie das Webchat-Steuerelement mithilfe des Geheimnisses in Ihre Website ein.Option 2 - Embed the web chat control in your website using the secret

Verwenden Sie diese Option, wenn Sie es anderen Entwicklern ermöglichen möchten, den Bot auf einfache Weise in ihre Websites einzubetten.Use this option if you want to allow other developers to easily embed your bot into their websites.

Warnung

Mit dieser Option wird der Webchat auf der Clientwebseite verfügbar gemacht.With this option, the Web Chat channel secret key is exposed in the client web page. Verwenden Sie diese Option nur zu Entwicklungszwecken und nicht in einer Produktionsumgebung.Use this option only for development purposes and not in a production environment.

Führen Sie die unten beschriebenen Schritte aus, um Ihren Bot in eine Webseite einbetten zu können, indem Sie das Geheimnis innerhalb des iframe Tags angeben.To embed your bot in a web page by specifying the secret within the iframe tag, perform the steps described below.

  1. Kopieren Sie den Einbettungscodeiframe aus dem Webchatkanal innerhalb des Bot Framework-Portals (siehe Abrufen des geheimen Botschlüssels oben).Copy the iframe Embed code from the Web Chat channel within the Bot Framework Portal (as described in Get your bot secret key above).

  2. Ersetzen Sie im Einbettungscode „YOUR_SECRET_HERE“ durch den Wert des geheimen Schlüssels, den Sie von der gleichen Seite kopiert haben.Within that Embed code, replace "YOUR_SECRET_HERE" with the Secret key value that you copied from the same page.

Beispiel-iframe (mithilfe eines Geheimnisses)Example iframe (using secret)
<iframe style="height:480px; width:402px" src="https://webchat.botframework.com/embed/YOUR_BOT_ID?s=YOUR_SECRET_HERE"></iframe>

Hinweis

Beachten Sie, dass Azure Government beispiel iframe anders aussieht.Please note that for Azure Government, the example iframe looks different.

<iframe style="height:480px; width:402px" src="https://webchat.botframework.azure.us/embed/YOUR_BOT_ID?s=YOUR_SECRET_HERE"></iframe>

Webchat Client

Einbettungsoption für die ProduktionProduction embedding option

Halten Sie Ihr Geheimnis ausgeblendet, tauschen Sie Ihr Geheimnis gegen ein Token aus, und generieren Sie die Einbettung.Keep your secret hidden, exchange your secret for a token, and generate the embed

Diese Option macht den geheimen Kanalschlüssel Webchat auf der Clientwebseite nicht verfügbar, da dies in einer Produktionsumgebung erforderlich ist.This option does not expose the Web Chat channel secret key in the client web page, as it is required in a production environment.

Der Client muss ein Token bereitstellen, um mit dem Bot zu kommunizieren.The client must provide a token to talk to the bot. Informationen zu den Unterschieden zwischen Geheimnissen und Token sowie informationen zu den Risiken im Zusammenhang mit der Verwendung von Geheimnissen finden Sie unter Direct Line-Authentifizierung.To learn about the differences between secrets and tokens and to understand the risks associated with using secrets, visit Direct Line authentication.

Die folgende Clientwebseite zeigt, wie Sie ein Token mit dem Webchat verwenden.The following client web page shows how to use a token with the Web Chat. Wenn Sie Azure Gov verwenden, passen Sie die URLs von public in government an.If you use Azure Gov, please adjust the URLs from public to government.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
  </head>
  <body>
    <h2>Web Chat bot client using Direct Line</h2>

    <div id="webchat" role="main"></div>

    <script>

     // "styleSet" is a set of CSS rules which are generated from "styleOptions"
     const styleSet = window.WebChat.createStyleSet({
         bubbleBackground: 'rgba(0, 0, 255, .1)',
         bubbleFromUserBackground: 'rgba(0, 255, 0, .1)',

         botAvatarImage: '<your bot avatar URL>',
         botAvatarInitials: 'BF',
         userAvatarImage: '<your user avatar URL>',
         userAvatarInitials: 'WC',
         rootHeight: '100%',
         rootWidth: '30%'
      });

      // After generated, you can modify the CSS rules
      styleSet.textContent = {
         ...styleSet.textContent,
         fontFamily: "'Comic Sans MS', 'Arial', sans-serif",
         fontWeight: 'bold'
      };

      const res = await fetch('https:<YOUR_TOKEN_SERVER/API>', { method: 'POST' });
      const { token } = await res.json();

      window.WebChat.renderWebChat(
        {
          directLine: window.WebChat.createDirectLine({ token }),
          userID: 'WebChat_UserId',
          locale: 'en-US',
          username: 'Web Chat User',
          locale: 'en-US',
          // Passing 'styleSet' when rendering Web Chat
          styleSet
        },
        document.getElementById('webchat')
      );
    </script>
  </body>
</html>

Beispiele zum Generieren eines Tokens finden Sie unter:For examples on how to generate a token, see:

Zusätzliche RessourcenAdditional resources