Подключение бота к веб-чату

Статья
2025-03-18

ПРИМЕНИМО К: пакет SDK версии 4

При создании бота в Azure канал веб-чата настраивается для вас автоматически. Канал веб-чата включает элемент управления веб-чата, который предоставляет пользователям возможность взаимодействовать с ботом непосредственно на веб-странице.

Канал веб-чата содержит все, что необходимо для внедрения элемента управления веб-чата на веб-странице. Для этого вы получите секретный ключ бота и встраиваете элемент управления на веб-страницу.

Необходимые условия

Учетная запись Azure. Если у вас еще нет учетной записи, создайте бесплатную учетную запись до начала работы.
Существующий бот, опубликованный в Azure.

Вопросы безопасности веб-чата

При использовании проверки подлинности Службы Azure AI Bot с веб-чатом необходимо учитывать некоторые важные аспекты безопасности. Дополнительные сведения см. в статье Вопросы безопасности.

Внедрение элемента управления "Веб-чат" на веб-странице

На следующем рисунке показаны компоненты, связанные с внедрением элемента управления "Веб-чат" на веб-странице.

компоненты управления веб-чата

Важный

Используйте Прямую линию (с расширенной проверкой подлинности), чтобы снизить риски безопасности при подключении к боту с помощью элемента управления Веб-чата. Дополнительные сведения см. в разделе расширенной аутентификации Direct Line .

Получение секретного ключа бота

Перейдите на портал Azure и откройте свой бот.
В разделе "Параметры "выберите каналы. Затем выберите веб-чат.
Откроется страница веб-чата. Выберите сайта по умолчанию в списке сайтов.
Скопируйте первый секретный ключ и код для внедрения .

Опции встраивания для разработки

Вариант 1 - обменяйте свой секрет на токен и сгенерируйте код для внедрения

Это хороший вариант, если:

Вы можете выполнить запрос от сервера к серверу для обмена секретной информацией веб-чата на временный токен.
Вы хотите затруднить внедрение бота в свои веб-сайты для других разработчиков.

Использование этого параметра не полностью препятствует внедрению вашего бота другими разработчиками на своих веб-сайтах, но значительно усложняет для них этот процесс.

Чтобы обменять ваш секрет на токен и создать встраиваемый элемент:

Отправьте GET-запрос на URL-адрес обмена токенами и передайте секрет веб-чата через заголовок Authorization. Заголовок Authorization использует схему BotConnector и содержит ваш секрет.
- Для глобального бота URL-адрес обмена токенами https://webchat.botframework.com/api/tokens.
- Для регионального бота введите следующий URL-адрес в соответствии с выбранным регионом:
Область URL токена обмена

Европа https://europe.webchat.botframework.com/api/tokens

Индия https://india.webchat.botframework.com/api/tokens
Ответ на запрос GET будет содержать маркер (в кавычках), который можно использовать для запуска беседы, чтобы отобразить элемент управления веб-чата. Маркер действителен только для одной беседы; чтобы начать другую беседу, необходимо создать новый маркер.
Внедренного кода , скопированного из канала веб-чата, измените параметр s= на t= и замените "YOUR_SECRET_HERE" на ваш токен.

Область	URL токена обмена
Европа	https://europe.webchat.botframework.com/api/tokens
Индия	https://india.webchat.botframework.com/api/tokens

Заметка

Токены будут автоматически обновляться до истечения срока их действия.

Примеры запросов

Для глобального бота:

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

Для регионального бота:

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

Заметка

Для Azure Government URL-адрес обмена токенами отличается.

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

Пример ответа

"IIbSpLnn8sA.dBB.MQBhAFMAZwBXAHoANgBQAGcAZABKAEcAMwB2ADQASABjAFMAegBuAHYANwA.bbguxyOv0gE.cccJjH-TFDs.ruXQyivVZIcgvosGaFs_4jRj1AyPnDt1wk1HMBb5Fuw"

Пример HTML-кода

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

Вариант 2. Внедрение элемента управления веб-чатом на веб-сайте с помощью секрета

Используйте этот параметр, если вы хотите разрешить другим разработчикам легко внедрять бота в свои веб-сайты.

Предупреждение

С помощью этого параметра секретный ключ канала веб-чата предоставляется на клиентской веб-странице. Используйте этот параметр только для целей разработки, а не в рабочей среде.

Чтобы внедрить бота на веб-страницу, укажите секрет в встраиваемом коде:

Скопируйте внедренный код из канала веб-чата на портале Azure (описано в разделе Получение секретного ключа бота выше).
В этом внедренном кодезамените "YOUR_SECRET_HERE" на значение секретного ключа, которое вы скопировали на той же странице.

Вариант встраивания в продакшн

Храните свой секрет в тайне, обменяйте свой секрет на токен и создайте встроенный элемент.

Этот параметр не предоставляет секретный ключ канала веб-чата на клиентской веб-странице.

Клиент должен предоставить маркер для взаимодействия с ботом. Для ознакомления с различиями между секретами и токенами и понимания рисков, связанных с использованием секретов, см. в разделе аутентификации Direct Line.

На следующей странице клиента показано, как использовать токен с веб-чатом. Если у вас есть региональный бот или бот Azure для государственного использования, измените URL-адреса с общедоступных на правительственные.

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

Примеры создания токена см. здесь: