ボットを Web チャットに接続するConnect a bot to Web Chat

適用対象: SDK v4APPLIES TO: SDK v4

フレームワークボットサービスを使用して bot を作成 すると、Web チャットチャネルが自動的に構成されます。When you create a bot with the Framework Bot Service, the Web Chat channel is automatically configured for you. Web チャットチャネルには、ユーザーが web ページで bot と直接対話できる 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.

Web チャットのサンプル

Bot Framework ポータルの Web チャットチャネルには、web ページに Web チャットコントロールを埋め込むために必要なすべてのものが含まれています。The Web Chat channel in the Bot Framework Portal contains everything you need to embed the Web Chat control in a web page. Web チャット コントロールを使用するために必要なのは、ボットの秘密鍵を取得し、コントロールを 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.

Web チャットのセキュリティに関する考慮事項Web Chat security considerations

Web チャットで Azure Bot Service 認証を使用する場合、注意する必要がある重要なセキュリティの考慮事項がいくつかあります。When you use Azure Bot Service authentication with Web Chat there are some important security considerations you must keep in mind. セキュリティに関する考慮事項」を参照してください。Please, refer to Security considerations.

Web ページに Web チャットコントロールを埋め込むEmbed the Web Chat control in a web page

次の図は、web ページに Web チャットコントロールを埋め込む場合に関係するコンポーネントを示しています。The following picture shows the components involved when embedding the Web Chat control in a web page.

bot 埋め込みコンポーネント

重要

前の図に示すように、Web チャットコントロールを使用して bot に接続する場合、セキュリティ上のリスクを軽減するために (高度な認証を使用した) ダイレクトラインを使用する必要があります。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. 詳細については、「 Direct Line enhanced authentication」を参照してください。For more information, see Direct Line enhanced authentication.

ボットの秘密鍵を取得するGet your bot secret key

  1. Azure portal でボットを開き、 [チャンネル] ブレードをクリックします。Open your bot in the Azure Portal and click Channels blade.

  2. [Web チャット] チャンネルの [編集] をクリックします。Click Edit for the Web Chat channel.

    Web チャット チャンネル

  3. [Secret keys](秘密鍵) で、最初の鍵の [表示] をクリックします。Under Secret keys, click Show for the first key.

    秘密鍵

  4. 秘密鍵埋め込みコード をコピーします。Copy the Secret key and the Embed code.

  5. [Done] をクリックします。Click Done.

開発用埋め込みオプションDevelopment embedding options

オプション 1-トークンのシークレットを交換し、埋め込みを生成するOption 1 - Exchange your secret for a token, and generate the embed

サーバー間の要求を実行して Web チャット シークレットを一時トークンと交換できる場合や、自分のボットを他の開発者が 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. この方法を使用しても、自分のボットを他の開発者が Web サイトに埋め込むことを完全に防ぐことができるわけではありませんが、これを行うことが難しくなります。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.

シークレットをトークンと交換し、埋め込みを生成するには、次の手順に従います。To exchange your secret for a token and generate the embed:

  1. https://webchat.botframework.com/api/tokens に対して GET 要求を発行し、Authorization ヘッダーを使用して Web チャット シークレットを渡します。Issue a GET request to https://webchat.botframework.com/api/tokens and pass your web chat secret via the Authorization header. 下記の要求の例に示すように、Authorization ヘッダーでは BotConnector スキームを使用し、シークレットが含まれています。The Authorization header uses the BotConnector scheme and includes your secret, as shown in the example request below.

  2. GET 要求への応答には、iframe 内で Web チャット コントロールをレンダリングして会話を開始する際に使用できるトークンが含まれています (トークンは引用符で囲まれています)。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. トークンは 1 つの会話でのみ有効です。別の会話を開始するには、新しいトークンを生成する必要があります。A token is valid for one conversation only; to start another conversation, you must generate a new token.

  3. Bot Framework ポータル内の Web チャット チャンネルからコピーした iframe 埋め込みコード 内で (上の「ボットの秘密鍵を取得する」を参照)、s= パラメーターを t= に変更し、"YOUR_SECRET_HERE" をトークンに置き換えます。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.

注意

トークンは、有効期限が切れる前に自動的に更新されます。Tokens will automatically be renewed before they expire.

要求の例Example request
requestGET https://webchat.botframework.com/api/tokens
Authorization: BotConnector YOUR_SECRET_HERE

注意

Azure Government の場合、トークン交換 URL が異なることに注意してください。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
応答の例Example response
"IIbSpLnn8sA.dBB.MQBhAFMAZwBXAHoANgBQAGcAZABKAEcAMwB2ADQASABjAFMAegBuAHYANwA.bbguxyOv0gE.cccJjH-TFDs.ruXQyivVZIcgvosGaFs_4jRj1AyPnDt1wk1HMBb5Fuw"
iframe の例 (トークンを使用)Example iframe (using token)
<iframe src="https://webchat.botframework.com/embed/YOUR_BOT_ID?t=YOUR_TOKEN_HERE"></iframe>

注意

Azure Government の場合、iframe の例は異なることに注意してください。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>
html コードの例Example 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>

方法 2 - シークレットを使用して、Web チャット コントロールを Web サイトに埋め込むOption 2 - Embed the web chat control in your website using the secret

自分のボットを他の開発者が Web サイトに簡単に埋め込むことができるようにする場合は、この方法を使用します。Use this option if you want to allow other developers to easily embed your bot into their websites.

警告

このオプションを使用すると、Web チャットチャネルの秘密キーがクライアント web ページに公開されます。With this option, the Web Chat channel secret key is exposed in the client web page. このオプションは、運用環境ではなく、開発目的でのみ使用してください。Use this option only for development purposes and not in a production environment.

タグ内にシークレットを指定して web ページに bot を埋め込むには iframe 、以下で説明する手順を実行します。To embed your bot in a web page by specifying the secret within the iframe tag, perform the steps described below.

  1. Bot Framework ポータル内の Web チャット チャンネルから iframe 埋め込みコード をコピーします (上の「ボットの秘密鍵を取得する」を参照)。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. その 埋め込みコード 内で、"YOUR_SECRET_HERE" を、同じページからコピーした 秘密鍵 の値に置き換えます。Within that Embed code, replace "YOUR_SECRET_HERE" with the Secret key value that you copied from the same page.

iframe の例 (シークレットを使用)Example iframe (using secret)
<iframe style="height:480px; width:402px" src="https://webchat.botframework.com/embed/YOUR_BOT_ID?s=YOUR_SECRET_HERE"></iframe>

注意

Azure Government の場合、iframe の例は異なることに注意してください。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>

Web チャットクライアント

運用環境への埋め込みオプションProduction embedding option

シークレットを非表示にし、シークレットをトークンと交換して埋め込みを生成するKeep your secret hidden, exchange your secret for a token, and generate the embed

このオプションは、Web チャット環境で必要な場合、クライアント Web ページでチャネル シークレット キーを公開する必要はありません。This option does not expose the Web Chat channel secret key in the client web page, as it is required in a production environment.

クライアントは、ボットと話すトークンを提供する必要があります。The client must provide a token to talk to the bot. シークレットとトークンの違いについて学習し、シークレットの使用に関連するリスクを理解するには、認証に関するページ Direct LineしてくださいTo learn about the differences between secrets and tokens and to understand the risks associated with using secrets, visit Direct Line authentication.

次のクライアント Web ページは、トークンとトークンを使用する方法をWeb チャット。The following client web page shows how to use a token with the Web Chat. Azure Gov を使用する場合は、パブリックから政府機関への URL を調整してください。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>

トークンを生成する方法の例については、次を参照してください。For examples on how to generate a token, see:

その他のリソースAdditional resources