Connecter un bot au canal Discussion WebConnect a bot to Web Chat

Notes

Cette rubrique s’applique à la dernière version du SDK (v4).This topic is for the latest release of the SDK (v4). La documentation de la version antérieure du SDK (v3) est disponible ici.You can find content for the older version of the SDK (v3) here.

Lorsque vous créez un bot avec le service Framework bot, le canal de conversation Web est automatiquement configuré pour vous.When you create a bot with the Framework Bot Service, the Web Chat channel is automatically configured for you. Le canal conversation Web inclut le contrôle conversation Web, qui permet aux utilisateurs d’interagir directement avec le bot dans une page Web.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.

Exemple de discussion web

Le canal de conversation Web dans le portail de l’infrastructure bot contient tout ce dont vous avez besoin pour incorporer le contrôle de conversation Web dans une page Web.The Web Chat channel in the Bot Framework Portal contains everything you need to embed the Web Chat control in a web page. Pour utiliser le contrôle de discussion web, il vous suffit d’obtenir la clé secrète de votre bot et d’incorporer le contrôle dans une page web.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.

Considérations sur la sécurité des conversations WebWeb Chat security considerations

Quand vous utilisez l’authentification Azure Bot Service avec Webchat, gardez à l’esprit certaines considérations de sécurité importantes.When you use Azure Bot Service authentication with Web Chat there are some important security considerations you must keep in mind. Reportez-vous à considérations relativesà la sécurité.Please, refer to Security considerations.

Incorporer le contrôle conversation Web dans une page WebEmbed the Web Chat control in a web page

L’illustration suivante montre les composants impliqués dans l’incorporation du contrôle conversation Web dans une page Web.The following picture shows the components involved when embedding the Web Chat control in a web page.

composants d’incorporation de bot

Notes

Cet article suppose que vous avez déjà déployé un bot dans Azure.This article assumes that you already have a bot deployed in Azure. Pour plus d’informations sur le déploiement, consultez déployer votre robot.For information about deployment, see Deploy your bot.

Obtenir la clé secrète de votre botGet your bot secret key

  1. Ouvrez votre bot dans le Portail Azure et cliquez sur le panneau Canaux.Open your bot in the Azure Portal and click Channels blade.

  2. Cliquez sur Modifier pour le canal Web Chat (Discussion Web).Click Edit for the Web Chat channel.

    Canal Discussion Web

  3. Sous Secret keys (Clés secrètes), cliquez sur Afficher pour la première clé.Under Secret keys, click Show for the first key.

    Clé secrète

  4. Copiez la clé secrète et le code incorporé.Copy the Secret key and the Embed code.

  5. Cliquez sur Done.Click Done.

Options d’incorporation du développementDevelopment embedding options

Option 1 : échange de votre secret pour un jeton et génération de l’incorporationOption 1 - Exchange your secret for a token, and generate the embed

Utilisez cette option si vous pouvez exécuter une requête de serveur à serveur pour échanger votre secret de discussion web contre un jeton temporaire et si vous souhaitez compliquer la tâche des développeurs souhaitant incorporer votre bot dans leurs sites web.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. Bien que cette option n’empêche pas totalement les autres développeurs d’incorporer votre bot dans leurs sites web, elle rend la procédure plus compliquée.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.

Pour échanger votre secret contre un jeton et générer l’incorporation :To exchange your secret for a token and generate the embed:

  1. Émettez une requête GET vers https://webchat.botframework.com/api/tokens et passez votre secret de discussion web par le biais de l’en-tête Authorization.Issue a GET request to https://webchat.botframework.com/api/tokens and pass your web chat secret via the Authorization header. L’en-tête Authorization utilise le schéma BotConnector et inclut votre secret, comme illustré dans les exemples de requêtes ci-dessous.The Authorization header uses the BotConnector scheme and includes your secret, as shown in the example request below.

  2. La réponse à votre requête GET contient le jeton (entre guillemets) qui peut être utilisé pour démarrer une conversation en restituant le contrôle de discussion web au sein d’un iframe.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. Un jeton est valide pour une conversation uniquement. Pour démarrer une autre conversation, vous devez générer un nouveau jeton.A token is valid for one conversation only; to start another conversation, you must generate a new token.

  3. Dans le code incorporé iframe que vous avez copié à partir du canal Web Chat dans le portail Bot Framework (comme décrit à l’étape Obtenir la clé secrète de votre bot ci-dessus), remplacez le paramètre s= par t=, puis remplacez « YOUR_SECRET_HERE » par votre jeton.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.

Notes

Les jetons sont automatiquement renouvelés avant leur expiration.Tokens will automatically be renewed before they expire.

Exemple de requêteExample request
requestGET https://webchat.botframework.com/api/tokens
Authorization: BotConnector YOUR_SECRET_HERE

Notes

Notez que, pour Azure Government, l’URL d’échange de jetons est différente.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
Exemple de réponseExample response
"IIbSpLnn8sA.dBB.MQBhAFMAZwBXAHoANgBQAGcAZABKAEcAMwB2ADQASABjAFMAegBuAHYANwA.bbguxyOv0gE.cccJjH-TFDs.ruXQyivVZIcgvosGaFs_4jRj1AyPnDt1wk1HMBb5Fuw"
Exemple d’Iframe (avec un jeton)Example iframe (using token)
<iframe src="https://webchat.botframework.com/embed/YOUR_BOT_ID?t=YOUR_TOKEN_HERE"></iframe>

Notes

Notez que pour Azure Government, l’exemple d’IFrame semble différent.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>
Exemple de code HTMLExample 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 : incorporer le contrôle de discussion web dans votre site web en utilisant le secretOption 2 - Embed the web chat control in your website using the secret

Utilisez cette option si vous souhaitez permettre aux autres développeurs d’incorporer facilement votre bot dans leurs sites Web.Use this option if you want to allow other developers to easily embed your bot into their websites.

Avertissement

Avec cette option, la clé secrète du canal de conversation Web est exposée dans la page Web du client.With this option, the Web Chat channel secret key is exposed in the client web page. Utilisez cette option uniquement à des fins de développement et non dans un environnement de production.Use this option only for development purposes and not in a production environment.

Pour incorporer votre bot dans une page Web en spécifiant le secret dans la iframe balise, effectuez les étapes décrites ci-dessous.To embed your bot in a web page by specifying the secret within the iframe tag, perform the steps described below.

  1. Copiez le code incorporé iframe issu du canal Web Chat, dans le portail Bot Framework (comme décrit à l’étape Obtenir la clé secrète de votre bot ci-dessus).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. Dans ce code incorporé, remplacez « YOUR_SECRET_HERE » par la valeur de la clé secrète que vous avez copiée sur la même page.Within that Embed code, replace "YOUR_SECRET_HERE" with the Secret key value that you copied from the same page.

Exemple d’Iframe (avec un secret)Example iframe (using secret)
<iframe style="height:480px; width:402px" src="https://webchat.botframework.com/embed/YOUR_BOT_ID?s=YOUR_SECRET_HERE"></iframe>

Notes

Notez que pour Azure Government, l’exemple d’IFrame semble différent.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>

Client de conversation Web

Option d’incorporation de productionProduction embedding option

Gardez votre secret masqué, échangez votre secret pour un jeton et générez l’incorporationKeep your secret hidden, exchange your secret for a token, and generate the embed

Cette option n’expose pas la clé secrète du canal de conversation Web dans la page Web du client, car elle est requise dans un environnement de production.This option does not expose the Web Chat channel secret key in the client web page, as it is required in a production environment.

Le client doit fournir un jeton pour communiquer avec le bot.The client must provide a token to talk to the bot. Pour en savoir plus sur les différences entre les secrets et les jetons et pour comprendre les risques associés à l’utilisation de secrets, consultez authentification directe par ligne.To learn about the differences between secrets and tokens and to understand the risks associated with using secrets, visit Direct Line authentication.

La page Web client suivante montre comment utiliser un jeton avec la conversation Web.The following client web page shows how to use a token with the Web Chat. Si vous utilisez Azure gov, modifiez les URL du public au gouvernement.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>

Pour obtenir des exemples sur la façon de générer un jeton, consultez :For examples on how to generate a token, see:

Ressources supplémentairesAdditional resources