Freigeben über

Verbinden eines Bots mit Webchat

  • Artikel

Gilt für: SDK v4

Wenn Sie einen Bot mit Azure erstellen, wird der Webchat-Kanal automatisch für Sie konfiguriert. Der Webchat-Kanal enthält das Webchat-Steuerelement, das Benutzern die Möglichkeit bietet, direkt auf einer Webseite mit dem Bot zu interagieren.

Der Webchatkanal enthält alles, was Sie zum Einbetten des Webchat-Steuerelements in eine Webseite benötigen. Dazu erhalten Sie den geheimen Schlüssel Ihres Bots und betten das Steuerelement dann in eine Webseite ein.

Voraussetzungen

  • Ein Azure-Konto. Wenn Sie noch kein Konto haben, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.
  • Ein vorhandener Bot, der in Azure veröffentlicht wurde.

Überlegungen zur Webchatsicherheit

Wenn Sie die Azure AI Bot Service-Authentifizierung mit Web-Chat verwenden, müssen Sie einige wichtige Sicherheitsaspekte berücksichtigen. Weitere Informationen finden Sie unter Sicherheitsüberlegungen.

Einbetten des Webchat-Steuerelements in eine Webseite

Die folgende Abbildung zeigt die Komponenten, die beim Einbetten des Webchat-Steuerelements in eine Webseite beteiligt sind.

Webchat-Steuerelementkomponenten

Wichtig

Verwenden Sie Direct Line (mit erweiterter Authentifizierung), um Sicherheitsrisiken beim Herstellen einer Verbindung mit einem Bot mithilfe des Webchat-Steuerelements zu minimieren. Weitere Informationen finden Sie unter erweiterte Direct Line-Authentifizierung.

Abrufen des geheimen Botschlüssels

  1. Wechseln Sie zu Azure-Portal, und öffnen Sie Ihren Bot.
  2. Wählen Sie in den Einstellungen Kanäle. Wählen Sie dann Web-Chataus.
  3. Die Seite Webchat wird geöffnet. Wählen Sie die Standardwebsite aus der Liste der Websitesaus.
  4. Kopieren Sie den ersten geheimen Schlüssel und den Einbettungscode.

Einbettungsoptionen für die Entwicklung

Option 1 : Tauschen Sie Ihren geheimen Schlüssel für ein Token aus, und generieren Sie die Einbettung.

Dies ist eine gute Option, wenn:

  • Sie können eine Server-zu-Server-Anforderung ausführen, um Ihren Geheimen Webchat für ein temporäres Token auszutauschen.
  • Sie möchten es anderen Entwicklern erschweren, Ihren Bot in ihre Websites einzubetten.

Die Verwendung dieser Option verhindert nicht vollständig, dass andere Entwickler Ihren Bot in ihre Websites einbetten, aber dies macht es für sie schwierig.

So tauschen Sie Ihr Geheimnis gegen ein Token ein und erstellen den Einbettungscode:

  1. Stellen Sie eine GET--Anforderung an die Tokenaustausch-URL und übergeben Sie Ihr Webchat-Geheimnis über den Authorization-Header. Die kopfzeile Authorization verwendet das BotConnector Schema und enthält Ihren geheimen Schlüssel.

    • Bei einem globalen Bot ist die Tokenaustausch-URL https://webchat.botframework.com/api/tokens.
    • Geben Sie für einen regionalen Bot folgende URL gemäß der ausgewählten Region ein:
    Region Token-Austausch-URL
    Europa https://europe.webchat.botframework.com/api/tokens
    Indien https://india.webchat.botframework.com/api/tokens

  2. Die Antwort auf Ihre GET-Anfrage enthält das Token (in Anführungszeichen), mit dem eine Konversation gestartet werden kann. Hierzu muss das Webchat-Steuerelement gerendert werden. Ein Token ist nur für eine Unterhaltung gültig; um eine weitere Unterhaltung zu starten, müssen Sie ein neues Token generieren.

  3. Ändern Sie im eingebetteten Code, den Sie zuvor aus dem Webchatkanal kopiert haben, den parameter s= in t= und ersetzen Sie "YOUR_SECRET_HERE" durch Ihr Token.

Anmerkung

Token werden automatisch verlängert, bevor sie ablaufen.

Beispielanforderungen

Für einen globalen Bot:

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

Für einen regionalen Bot:

requestGET 
    ## Europe region
    https://europe.webchat.botframework.com/api/tokens
    ## India region
    https://india.webchat.botframework.com/api/tokens
Authorization: BotConnector YOUR_SECRET_HERE

Anmerkung

Bei Azure Government unterscheidet sich die Tokenaustausch-URL.

requestGET https://webchat.botframework.azure.us/api/tokens
Authorization: BotConnector YOUR_SECRET_HERE
Beispielantwort
"IIbSpLnn8sA.dBB.MQBhAFMAZwBXAHoANgBQAGcAZABKAEcAMwB2ADQASABjAFMAegBuAHYANwA.bbguxyOv0gE.cccJjH-TFDs.ruXQyivVZIcgvosGaFs_4jRj1AyPnDt1wk1HMBb5Fuw"
Beispiel-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 – Einbetten des Webchat-Steuerelements in Ihre Website mithilfe des geheimen Schlüssels

Verwenden Sie diese Option, wenn Sie anderen Entwicklern das einfache Einbetten Ihres Bots in ihre Websites ermöglichen möchten.

Warnung

Mit dieser Option wird der geheime Schlüssel des Webchatkanals auf der Clientwebseite verfügbar gemacht. Verwenden Sie diese Option nur zu Entwicklungszwecken und nicht in einer Produktionsumgebung.

Um Ihren Bot in Ihre Website einzubetten, geben Sie das Geheimnis innerhalb des Einbettungscodes an:

  1. Kopieren Sie den Einbettungscode aus dem Webchatkanal innerhalb des Azure-Portals (siehe Abrufen des geheimen Botschlüssels oben).

  2. Ersetzen Sie im Einbettungscode „YOUR_SECRET_HERE“ durch den Wert des geheimen Schlüssels, den Sie von der gleichen Seite kopiert haben.

Option "Produktionseinbettung"

Halten Sie Ihr Geheimnis verborgen, tauschen Sie Ihr Geheimnis gegen ein Token aus, und generieren Sie den Einbettungscode.

Mit dieser Option wird der geheime Schlüssel des Webchatkanals auf der Clientwebseite nicht verfügbar gemacht.

Der Client muss ein Token bereitstellen, um mit dem Bot zu sprechen. Informationen zu den Unterschieden zwischen geheimen Schlüsseln und Token und zum Verständnis der Risiken im Zusammenhang mit der Verwendung von geheimen Schlüsseln finden Sie unter Direct Line-Authentifizierung.

Die folgende Clientwebseite zeigt, wie Sie ein Token mit dem Webchat verwenden. Wenn Sie über einen regionalen oder Azure-Gov-Bot verfügen, passen Sie die URLs von öffentlich zu staatlich an.

<!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:

Zusatzinformation