웹 채팅에 봇 연결Connect a bot to Web Chat

적용 대상: SDK v4APPLIES TO: SDK v4

Framework Bot Service를 사용 하 여 봇을 만들면 웹 채팅 채널이 자동으로 구성 됩니다.When you create a bot with the Framework Bot Service, the Web Chat channel is automatically configured for you. 웹 채팅 채널에는 사용자가 웹 페이지에서 직접 봇과 상호 작용할 수 있는 기능을 제공 하는 웹 채팅 컨트롤이포함 되어 있습니다.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.

웹 채팅 샘플

Bot Framework 포털의 웹 채팅 채널에는 웹 페이지에 웹 채팅 컨트롤을 포함 하는 데 필요한 모든 항목이 포함 되어 있습니다.The Web Chat channel in the Bot Framework Portal contains everything you need to embed the Web Chat control in a web page. 웹 채팅 컨트롤을 사용하기 위해서는 봇의 비밀 키를 가져오고 웹 페이지에 컨트롤을 포함하기만 하면 됩니다.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 Chat security considerations

웹 채팅에서 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.

웹 페이지에 웹 채팅 컨트롤 포함Embed the Web Chat control in a web page

다음 그림에서는 웹 채팅 컨트롤을 웹 페이지에 포함할 때 수반 되는 구성 요소를 보여 줍니다.The following picture shows the components involved when embedding the Web Chat control in a web page.

bot 구성 요소 포함

중요

이전 그림에 표시 된 것 처럼 웹 채팅 컨트롤을 사용 하 여 봇에 연결할 때 보안 위험을 완화 하려면 Direct Line (고급 인증 사용)을 사용 해야 합니다.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. 자세한 내용은 직접 줄 고급 인증을 참조 하세요.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. 웹 채팅 채널에 대해 편집 을 클릭합니다.Click Edit for the Web Chat channel.

    웹 채팅 채널

  3. 비밀 키 아래에서 첫 번째 키에 대해 표시 를 클릭합니다.Under Secret keys, click Show for the first key.

    비밀 키

  4. 비밀 키Embed 태그 를 복사합니다.Copy the Secret key and the Embed code.

  5. Done 을 클릭합니다.Click Done.

개발 포함 옵션Development embedding options

옵션 1-토큰의 암호를 Exchange 하 고 embed를 생성 합니다.Option 1 - Exchange your secret for a token, and generate the embed

서버 간 요청을 실행하여 웹 채팅 암호를 임시 토큰으로 바꿀 수 있고, 다른 개발자가 해당 웹 사이트에 사용자의 봇을 포함하기 어렵게 만들려면 이 옵션을 사용합니다.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. 이 옵션을 사용한다고 해서 다른 개발자가 웹 사이트에 사용자의 봇을 포함하는 것을 완전히 방지하지는 못하지만 어렵게 만들 수는 있습니다.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.

암호를 토큰으로 바꾸고, embed를 생성하려면To exchange your secret for a token and generate the embed:

  1. https://webchat.botframework.com/api/tokens에 대한 GET 요청을 실행하고 Authorization 헤더를 통해 웹 채팅 비밀을 전달합니다.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 내에서 웹 채팅 컨트롤을 렌더링하여 대화를 시작하는 데 사용할 수 있는 토큰(따옴표로 묶음)이 포함됩니다.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. 토큰은 하나의 대화에서만 유효하므로 다른 대화를 시작하려면 새 토큰을 생성해야 합니다.A token is valid for one conversation only; to start another conversation, you must generate a new token.

  3. Bot Framework 포털 내의 웹 채팅 채널에서 복사한 iframeEmbed 코드 내에서(위의 봇 비밀 키 가져오기에서 설명한 대로) 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 - 암호를 사용하여 웹 사이트에 웹 채팅 컨트롤 포함Option 2 - Embed the web chat control in your website using the secret

다른 개발자가 웹 사이트 봇을 쉽게 포함할 수 있도록 하려는 경우 이 옵션을 사용합니다.Use this option if you want to allow other developers to easily embed your bot into their websites.

경고

이 옵션을 사용 하면 웹 채팅 채널 비밀 키가 클라이언트 웹 페이지에서 노출 됩니다.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.

태그 내에서 암호를 지정 하 여 웹 페이지에 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 포털 내의 웹 채팅 채널에서 iframeEmbed 코드 를 복사합니다(위의 봇 비밀 키 가져오기에 설명한 대로).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. 해당 Embed 태그 내에서 "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>

웹 채팅 클라이언트

프로덕션 포함 옵션Production embedding option

비밀을 숨겨진 상태로 유지 하 고, 토큰에 대 한 비밀을 교환 하 고, embed를 생성 합니다.Keep your secret hidden, exchange your secret for a token, and generate the embed

이 옵션은 프로덕션 환경에서 필요 하므로 클라이언트 웹 페이지의 웹 채팅 채널 비밀 키를 노출 하지 않습니다.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. 암호와 토큰 간의 차이점에 대해 알아보고 비밀 사용과 관련 된 위험을 이해 하려면 직접 회선 인증을 방문 하세요.To learn about the differences between secrets and tokens and to understand the risks associated with using secrets, visit Direct Line authentication.

다음 클라이언트 웹 페이지에서는 웹 채팅에서 토큰을 사용 하는 방법을 보여 줍니다.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