Conexión de un bot a un Chat en webConnect a bot to Web Chat

se aplica a: SDK V4APPLIES TO: SDK v4

Al crear un bot con framework Bot Service, el canal Chat en web se configura automáticamente.When you create a bot with the Framework Bot Service, the Web Chat channel is automatically configured for you. El Chat en web incluye el control Chat en web, que proporciona la capacidad de que los usuarios interactúen con el bot directamente en una página 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.

Ejemplo de chat en web

El Chat en web en Bot Framework Portal contiene todo lo que necesita para insertar el control Chat en web en una página web.The Web Chat channel in the Bot Framework Portal contains everything you need to embed the Web Chat control in a web page. Lo único que debe hacer para usar el control Chat en web es obtener la clave secreta del bot e insertar el control en una página 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.

Chat en web de seguridadWeb Chat security considerations

Cuando se usa la autenticación de Azure Bot Service con Chat en web hay algunos aspectos de seguridad importantes que debe tener en cuenta.When you use Azure Bot Service authentication with Web Chat there are some important security considerations you must keep in mind. Consulte Consideraciones de seguridad.Please, refer to Security considerations.

Insertar el control Chat en web en una página webEmbed the Web Chat control in a web page

En la imagen siguiente se muestran los componentes implicados al insertar el control Chat en web en una página web.The following picture shows the components involved when embedding the Web Chat control in a web page.

componentes de inserción de bots

Importante

Como implica la imagen anterior, debe usar Direct Line (con autenticación mejorada) para mitigar los riesgos de seguridad al conectarse a un bot mediante el control Chat en web seguridad.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. Para obtener más información, vea Direct Line autenticación mejorada.For more information, see Direct Line enhanced authentication.

Obtener la clave secreta del botGet your bot secret key

  1. Abra el bot en Azure Portal y haga clic en la hoja Canales.Open your bot in the Azure Portal and click Channels blade.

  2. Haga clic en Editar en el canal Chat en web.Click Edit for the Web Chat channel.

    Canal Chat en web

  3. En Claves secretas, haga clic en Mostrar para la primera clave.Under Secret keys, click Show for the first key.

    Clave secreta

  4. Copia la clave secreta y el código para insertar.Copy the Secret key and the Embed code.

  5. Haga clic en Done(Listo).Click Done.

Opciones de inserción de desarrolloDevelopment embedding options

Opción 1: Exchange el secreto de un token y generar la inserciónOption 1 - Exchange your secret for a token, and generate the embed

Use esta opción si puede ejecutar una solicitud de servidor a servidor para intercambiar el secreto de chat en web por un token temporal, y si quiere hacer que sea difícil para otros desarrolladores insertar el bot en sus sitios 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. Aunque el uso de esta opción no impedirá en absoluto que otros desarrolladores inserten el bot en sus sitios web, hace que sea difícil hacerlo.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.

Para intercambiar el secreto por un token y generar la inserción, siga los siguientes pasos:To exchange your secret for a token and generate the embed:

  1. Emita una solicitud GET para https://webchat.botframework.com/api/tokens y transfiera su secreto de chat en web a través del encabezado Authorization.Issue a GET request to https://webchat.botframework.com/api/tokens and pass your web chat secret via the Authorization header. El encabezado Authorization utiliza el esquema BotConnector e incluye el secreto, como se muestra en la siguiente solicitud de ejemplo.The Authorization header uses the BotConnector scheme and includes your secret, as shown in the example request below.

  2. La respuesta a su solicitud GET contendrá el token (entre comillas) que se puede usar para iniciar una conversación al representar el control Chat en web dentro de 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 token es válido solo para una conversación. Para iniciar otra conversación, debe generar un nuevo token.A token is valid for one conversation only; to start another conversation, you must generate a new token.

  3. Dentro del iframeCódigo para insertar que ha copiado del canal WebChat del portal de Bot Framework (como se describe en la sección Obtener la clave secreta del bot anterior), cambie el parámetro s= por t= y reemplace "YOUR_SECRET_HERE" por su 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.

Nota

Los tokens se renovarán automáticamente antes de que expiren.Tokens will automatically be renewed before they expire.

Solicitud de ejemploExample request
requestGET https://webchat.botframework.com/api/tokens
Authorization: BotConnector YOUR_SECRET_HERE

Nota

Tenga en cuenta que, por Azure Government, la dirección URL de intercambio de tokens es diferente.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
Respuesta de ejemploExample response
"IIbSpLnn8sA.dBB.MQBhAFMAZwBXAHoANgBQAGcAZABKAEcAMwB2ADQASABjAFMAegBuAHYANwA.bbguxyOv0gE.cccJjH-TFDs.ruXQyivVZIcgvosGaFs_4jRj1AyPnDt1wk1HMBb5Fuw"
IFrame de ejemplo (con el token)Example iframe (using token)
<iframe src="https://webchat.botframework.com/embed/YOUR_BOT_ID?t=YOUR_TOKEN_HERE"></iframe>

Nota

Tenga en cuenta que, por Azure Government, el iframe de ejemplo tiene un aspecto diferente.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>
Código HTML de ejemploExample 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>

Opción 2: Insertar el control Chat en web en su sitio web mediante el secretoOption 2 - Embed the web chat control in your website using the secret

Use esta opción si quiere permitir que otros desarrolladores inserten fácilmente el bot en sus sitios web.Use this option if you want to allow other developers to easily embed your bot into their websites.

Advertencia

Con esta opción, la clave Chat en web secreto del canal se expone en la página web del cliente.With this option, the Web Chat channel secret key is exposed in the client web page. Use esta opción solo con fines de desarrollo y no en un entorno de producción.Use this option only for development purposes and not in a production environment.

Para insertar el bot en una página web especificando el secreto dentro de la iframe etiqueta, realice los pasos que se describen a continuación.To embed your bot in a web page by specifying the secret within the iframe tag, perform the steps described below.

  1. Copie el Código para insertariframe desde el canal Chat en web en el portal de Bot Framework (como se describe en la sección Obtener la clave secreta del bot anterior).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. En ese Código para insertar, reemplace "YOUR_SECRET_HERE" por la clave secreta que copió de la misma página.Within that Embed code, replace "YOUR_SECRET_HERE" with the Secret key value that you copied from the same page.

IFrame de ejemplo (con el secreto)Example iframe (using secret)
<iframe style="height:480px; width:402px" src="https://webchat.botframework.com/embed/YOUR_BOT_ID?s=YOUR_SECRET_HERE"></iframe>

Nota

Tenga en cuenta que, por Azure Government, el iframe de ejemplo tiene un aspecto diferente.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>

Chat en web cliente

Opción de inserción de producciónProduction embedding option

Mantener el secreto oculto, intercambiar el secreto por un token y generar la inserciónKeep your secret hidden, exchange your secret for a token, and generate the embed

Esta opción no expone la clave secreta Chat en web del canal en la página web del cliente, ya que es necesaria en un entorno de producción.This option does not expose the Web Chat channel secret key in the client web page, as it is required in a production environment.

El cliente debe proporcionar un token para hablar con el bot.The client must provide a token to talk to the bot. Para obtener información sobre las diferencias entre secretos y tokens y para comprender los riesgos asociados al uso de secretos, visite Direct Line autenticación.To learn about the differences between secrets and tokens and to understand the risks associated with using secrets, visit Direct Line authentication.

En la página web de cliente siguiente se muestra cómo usar un token con el Chat en web.The following client web page shows how to use a token with the Web Chat. Si usa Azure Gov, ajuste las direcciones URL de público a gobierno.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>

Para obtener ejemplos sobre cómo generar un token, consulte:For examples on how to generate a token, see:

Recursos adicionalesAdditional resources