빠른 시작: 채팅 앱에 봇 추가

아티클
03/20/2024

Azure Bot Service에서 사용할 수 있는 Azure Communication Services 채팅 메시징 채널을 사용하여 채팅 애플리케이션에서 대화형 AI 환경을 빌드하는 방법을 알아봅니다. 이 빠른 시작에서는 BotFramework SDK를 사용하여 봇을 만듭니다. 그런 다음, Communication Services 채팅 SDK를 사용하여 만든 채팅 애플리케이션에 봇을 통합합니다.

이 빠른 시작에서 다음을 수행하는 방법을 알아봅니다.

Azure에서 봇 만들기 및 배포
Communication Services 리소스 가져오기
봇에 대해 Communication Services 채팅 채널 사용
채팅 앱을 만들고 봇을 참가자로 추가
봇에 대한 추가 기능 살펴보기

필수 조건

Azure 계정 및 활성 구독. 무료로 계정을 만듭니다.
Visual Studio 2019 이상
최신 버전의 .NET Core. 이 빠른 시작에서는 .NET Core 3.1을 사용합니다. Visual Studio의 인스턴스(32비트 또는 64비트)에 해당하는 버전을 설치해야 합니다.
Bot 프레임워크 SDK

Azure에서 봇 만들기 및 배포

Azure Communication Services 채팅을 Azure Bot Service의 채널로 사용하려면 먼저 봇을 배포합니다. 봇을 배포하려면 다음 단계를 완료합니다.

Azure Bot Service 리소스 만들기
봇의 앱 ID 및 암호 가져오기
봇 논리를 저장할 웹앱 만들기
봇에 대한 메시징 엔드포인트 만들기

Azure Bot Service 리소스 만들기

먼저 Azure Portal을 사용하여 Azure Bot Service 리소스를 만듭니다. Communication Services 채팅 채널은 단일 테넌트 봇, 관리 ID 봇 및 다중 테넌트 봇을 지원합니다. 이 빠른 시작에서는 다중 테넌트 봇을 사용합니다.

단일 테넌트 또는 관리 ID 봇을 설정하려면 봇 ID 정보를 검토합니다.

관리 ID 봇의 경우 봇 서비스 ID를 업데이트해야 할 수 있습니다.

봇의 앱 ID 및 앱 암호 가져오기

다음으로, 배포될 때 봇에 할당된 Microsoft 앱 ID 및 암호를 가져옵니다. 이러한 값은 이후 구성에 사용합니다.

봇 논리를 저장할 웹앱 만들기

봇에 대한 웹앱을 만들려면 시나리오에 맞게 Bot Builder 샘플을 수정하거나 Bot Builder SDK를 사용하여 웹앱을 만들 수 있습니다. 가장 간단한 샘플 중 하나는 Echo Bot입니다.

Azure Bot Service는 일반적으로 봇 애플리케이션 웹앱 컨트롤러가 /api/messages 형식의 엔드포인트를 노출해야 합니다. 엔드포인트는 봇에 전송되는 모든 메시지를 처리합니다.

봇 앱을 만들려면 Azure CLI를 사용하여 Azure App Service 리소스를 만들거나 Azure Portal에서 앱을 만듭니다.

Azure Portal 사용하여 봇 웹앱을 만들려면 다음을 수행합니다.

포털에서 리소스 만들기를 선택합니다. 검색 상자에 웹앱을 입력합니다. 웹앱 타일을 선택합니다.
웹앱 만들기에서 앱을 배포할 지역을 포함하여 앱에 대한 세부 정보를 선택하거나 입력합니다.
검토 + 만들기를 선택하여 배포의 유효성을 검사하고 배포 세부 정보를 검토합니다. 그런 다음 만들기를 선택합니다.
웹앱 리소스를 만들 때 리소스 세부 정보에 표시된 호스트 이름 URL을 복사합니다. URL은 웹앱용으로 만드는 엔드포인트의 일부입니다.

봇에 대한 메시징 엔드포인트 만들기

다음으로, 봇 리소스에서 웹앱 메시징 엔드포인트를 만듭니다.

Azure Portal에서 Azure Bot 리소스로 이동합니다. 리소스 메뉴에서 구성을 선택합니다.
구성에서 메시징 엔드포인트에 대해 이전 섹션에서 복사한 웹앱의 호스트 이름 URL을 붙여넣습니다. /api/messages로 URL을 추가합니다.
저장을 선택합니다.

웹앱 배포

봇을 만드는 마지막 단계는 웹앱을 배포하는 것입니다. 이 빠른 시작에서는 Echo Bot 샘플을 사용합니다. Echo Bot 기능은 사용자 입력을 에코하는 것으로 제한됩니다. Azure에서 웹앱에 배포하는 방법은 다음과 같습니다.

Git을 사용하여 이 GitHub 리포지토리를 복제합니다.

git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

Visual Studio에서 Echo Bot 프로젝트를 엽니다.
Visual Studio 프로젝트에서 Appsettings.json 파일을 엽니다. 이전에 복사한 Microsoft 앱 ID 및 앱 암호를 붙여넣습니다.
```
   {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }
```
다음으로, C# 봇용 Visual Studio를 사용하여 봇을 배포합니다.

명령 프롬프트 창을 사용하여 Azure 봇을 배포할 수도 있습니다.
Visual Studio의 솔루션 탐색기에서 EchoBot 프로젝트를 마우스 오른쪽 단추로 클릭하고 게시를 선택합니다.
새로 만들기를 선택하여 새 게시 프로필을 만듭니다. 대상에서 Azure를 선택합니다.

특정 대상에 대해 Azure App Service를 선택합니다.
배포 구성에서 Azure 계정에 로그인한 후 표시되는 결과에서 웹앱을 선택합니다. 프로필을 완료하려면 마침을 선택한 다음, 게시를 선택하여 배포를 시작합니다.

Communication Services 리소스 가져오기

이제 봇을 만들고 배포했으므로 Communication Services 채널을 설정하는 데 사용할 Communication Services 리소스를 만듭니다.

Communication Services 리소스를 만드는 단계를 완료합니다.
Communication Services 사용자를 만들고 사용자 액세스 토큰을 발급합니다. 범위를 채팅으로 설정해야 합니다. 토큰 문자열 및 사용자 ID 문자열을 복사합니다.

Communication Services 채팅 채널 사용

Communication Services 리소스가 있는 경우 봇 리소스에서 Communication Services 채널을 설정할 수 있습니다. 이 프로세스에서는 봇에 대한 사용자 ID가 생성됩니다.

Azure Portal에서 Azure Bot 리소스로 이동합니다. 리소스 메뉴에서 채널을 선택합니다. 사용 가능한 채널 목록에서 Azure Communications Services - 채팅을 선택합니다.
연결을 선택하여 구독에서 사용할 수 있는 Communication Services 리소스 목록을 확인합니다.
새 연결 창에서 Communication Services 채팅 리소스를 선택한 다음, 적용을 선택합니다.
리소스 세부 정보가 확인되면 봇 ID가 Bot Azure Communication Services ID 열에 표시됩니다. Communication Services Chat AddParticipant API를 통해 봇 ID를 사용하여 채팅 스레드에서 봇을 나타낼 수 있습니다. 봇을 참가자로 채팅에 추가하면 봇이 채팅 관련 활동을 받기 시작하고 채팅 스레드에서 응답할 수 있습니다.

채팅 앱을 만들고 봇을 참가자로 추가

이제 봇의 Communication Services ID가 있으므로 봇을 참가자로 사용하여 채팅 스레드를 만들 수 있습니다.

새 C# 애플리케이션 만들기

다음 명령을 실행하여 C# 애플리케이션을 만듭니다.
```
dotnet new console -o ChatQuickstart
```
디렉터리를 새 앱 폴더로 변경하고 dotnet build 명령을 사용하여 애플리케이션을 컴파일합니다.
```
cd ChatQuickstart
dotnet build
```

패키지 설치

.NET용 Communication Services 채팅 SDK를 설치합니다.

dotnet add package Azure.Communication.Chat

채팅 클라이언트 만들기

채팅 클라이언트를 만들려면 Communications Service 엔드포인트와 이전에 생성한 사용자 액세스 토큰을 사용합니다. ID SDK의 CommunicationIdentityClient 클래스를 사용하여 사용자를 만들고 토큰을 발급하여 채팅 클라이언트에 전달할 수 있습니다. 다음 지침을 사용하여 포털에서 액세스 토큰을 생성할 수 있습니다.

다음 코드를 복사하여 Program.cs 원본 파일에 붙여넣습니다.

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

봇과 채팅 스레드 시작

chatClient에서 createChatThread 메서드를 사용하여 채팅 스레드를 만듭니다. ID를 봇의 Communication Services ID로 바꿉니다.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

채팅 스레드 클라이언트 가져오기

GetChatThreadClient 메서드는 이미 존재하는 스레드에 대한 스레드 클라이언트를 반환합니다.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

채팅 스레드에 메시지 보내기

SendMessage를 사용하여 스레드에 메시지를 보내려면 다음을 수행합니다.

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

채팅 스레드에서 채팅 메시지 받기

설정된 간격으로 채팅 스레드 클라이언트에서 GetMessages 메서드를 폴링하여 채팅 메시지를 가져올 수 있습니다.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

"Hello World"에 대한 봇의 에코 응답에 대한 메시지 목록을 확인합니다.

JavaScript 또는 Azure 모바일 SDK를 사용하여 들어오는 메시지 알림을 구독할 수 있습니다.

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

채팅 스레드 정리

채팅 스레드 사용을 마쳤으면 스레드를 삭제합니다.

chatClient.DeleteChatThread(threadId);

C# 채팅 애플리케이션 배포

채팅 애플리케이션을 배포하려면 다음을 수행합니다.

Visual Studio에서 채팅 프로젝트를 엽니다.
ChatQuickstart 프로젝트를 마우스 오른쪽 단추로 클릭하고 게시를 선택합니다.
솔루션을 게시한 후 솔루션을 실행하고 Echobot이 명령 프롬프트에서 사용자 메시지를 에코하는지 확인합니다. 이제 솔루션이 있으므로 해결해야 하는 비즈니스 시나리오에 필요한 다양한 활동을 계속 진행할 수 있습니다.

봇으로 수행할 수 있는 더 많은 작업

봇은 Communications Services 채팅 채널의 사용자로부터 일반 텍스트 메시지 이상을 받을 수 있습니다. 봇이 사용자로부터 받을 수 있는 활동 중 일부는 다음과 같습니다.

대화 업데이트
메시지 업데이트
메시지 삭제
입력 표시기
이벤트 활동
적응형 카드를 비롯한 다양한 첨부 파일
봇 채널 데이터

다음 섹션에서는 이러한 기능을 설명하는 몇 가지 샘플을 보여 줍니다.

새 사용자가 스레드에 추가되면 시작 메시지 보내기

현재 Echo Bot 논리는 사용자의 입력을 수락하고 다시 에코합니다. 참가자가 추가한 Communication Services 이벤트에 응답하는 등 더 많은 논리를 추가하려면 다음 코드를 복사하여 EchoBot.cs 원본 파일에 붙여넣습니다.

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

적응형 카드 보내기

참고 항목

적응형 카드는 모든 채팅 참가자가 Azure Communication Services 사용자이고 Teams 상호 운용성 사용 사례가 아닌 Azure Communication Services 사용 사례 내에서만 지원됩니다.

적응형 카드를 채팅 스레드에 보내 참여와 효율성을 높일 수 있습니다. 적응형 카드는 다양한 방법으로 사용자와 통신할 수 있도록 도와줍니다. 카드 봇 활동 첨부 파일로 추가하여 봇에서 적응형 카드를 보낼 수 있습니다.

적응형 카드를 보내는 방법의 예는 다음과 같습니다.

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

샘플 및 템플릿에서 적응형 카드에 대한 샘플 페이로드를 가져옵니다.

채팅 사용자의 경우 Communication Services 채팅 채널은 메시지에 첨부 파일이 있음을 나타내는 필드를 메시지 메타데이터에 추가합니다. 메타데이터에서 microsoft.azure.communication.chat.bot.contenttype 속성은 azurebotservice.adaptivecard로 설정됩니다.

적응형 카드가 연결된 채팅 메시지의 예는 다음과 같습니다.

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

사용자에서 봇으로 메시지 보내기

다른 사용자에게 문자 메시지를 보내는 것과 동일한 방식으로 사용자의 기본 문자 메시지를 봇으로 보낼 수 있습니다.

그러나 사용자의 첨부 파일이 있는 메시지를 봇으로 보내는 경우 Communication Services 채팅 메타데이터에 이 플래그를 추가합니다.

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

사용자의 이벤트 활동을 봇으로 보내려면 Communication Services 채팅 메타데이터에 다음 플래그를 추가합니다.

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

다음 섹션에서는 사용자가 봇에 보내는 채팅 메시지의 샘플 형식을 보여 줍니다.

간단한 문자 메시지

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

첨부 파일이 있는 메시지

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

이벤트 활동이 있는 메시지

이벤트 페이로드에는 Name을 제외한 메시지 콘텐츠의 모든 JSON 필드가 포함됩니다. Name 필드에는 이벤트의 이름이 포함됩니다.

다음 예제에서는 페이로드 "{field1":"value1", "field2": { "nestedField":"nestedValue" }}가 있는 이벤트 이름 endOfConversation이 봇으로 전송됩니다.

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

메타데이터 필드 microsoft.azure.communication.chat.bot.contenttype은 사용자에서 봇으로 전송되는 메시지에만 필요합니다.

지원되는 봇 활동 필드

다음 섹션에서는 봇-사용자 흐름 및 사용자-봇 흐름에 대해 지원되는 봇 활동 필드에 대해 설명합니다.

봇-사용자 흐름

다음 봇 활동 필드는 봇-사용자 흐름에 대해 지원됩니다.

활동

메시지
Typing

메시지 활동 필드

Text
Attachments
AttachmentLayout
SuggestedActions
From.Name (Communication Services로 변환됩니다SenderDisplayName.)
ChannelData (Communication Services로 변환됩니다Chat Metadata. ChannelData 매핑 값이 개체인 경우 JSON 형식으로 직렬화되고 문자열로 전송됩니다.)

사용자-봇 흐름

이러한 봇 활동 필드는 사용자-봇 흐름에 대해 지원됩니다.

활동 및 필드

메시지
- Id(Communication Services 채팅 메시지 ID)
- TimeStamp
- Text
- Attachments
대화 업데이트
- MembersAdded
- MembersRemoved
- TopicName
메시지 업데이트
- Id(업데이트된 Communication Services 채팅 메시지 ID)
- Text
- Attachments
메시지 삭제
- Id(삭제된 Communication Services 채팅 메시지 ID)
이벤트
- Name
- Value
Typing

기타 일반 필드

Recipient.Id 및 Recipient.Name(Communication Services 채팅 사용자 ID 및 표시 이름)
From.Id 및 From.Name(Communication Services 채팅 사용자 ID 및 표시 이름)
Conversation.Id(Communication Services 채팅 스레드 ID)
ChannelId(비어 있는 경우 Communication Services 채팅)
ChannelData(Communication Services 채팅 메시지 메타데이터터)

봇 핸드오프 패턴

봇이 질문을 이해하지 못하거나 질문에 대답할 수 없는 경우가 있습니다. 고객은 채팅에서 사용자 에이전트에 연결하도록 요청할 수 있습니다. 이러한 시나리오에서 채팅 스레드는 봇에서 인간 에이전트로 전달되어야 합니다. 대화를 봇에서 인간으로 전환하도록 애플리케이션을 디자인할 수 있습니다.

봇 간 통신 처리

일부 사용 사례에서는 서로 다른 서비스를 제공하려면 동일한 채팅 스레드에 두 개의 봇을 추가해야 합니다. 이 시나리오에서는 봇이 다른 봇의 메시지에 자동화된 회신을 보내지 않도록 해야 할 수 있습니다. 제대로 처리되지 않으면 봇 간의 자동화된 상호 작용으로 인해 메시지 루프가 무한히 발생할 수 있습니다.

활동의 From.Id 속성에서 메시지 보낸 사람의 Communication Services 사용자 ID를 확인할 수 있습니다. 다른 봇에 속하는지 확인합니다. 그런 다음, 봇 간 통신 흐름을 방지하기 위해 필요한 조치를 취합니다. 이러한 유형의 시나리오로 인해 통화량이 많은 경우 Communication Services 채팅 채널은 요청을 제한하고 봇은 메시지를 보내고 받을 수 없습니다.

제한 한도에 대해 자세히 알아봅니다.

문제 해결

다음 섹션에서는 일반적인 시나리오의 문제를 해결하는 방법을 설명합니다.

채팅 채널을 추가할 수 없습니다.

Microsoft Bot Framework 개발자 포털에서 구성>봇 메시징으로 이동하여 엔드포인트가 올바르게 설정되었는지 확인합니다.

봇이 메시지에 회신하는 동안 금지된 예외를 가져옵니다.

봇의 Microsoft 앱 ID 및 암호가 웹앱에 업로드하는 봇 구성 파일에 올바르게 저장되었는지 확인합니다.

봇을 참가자로 추가할 수 없습니다.

채팅 스레드에 봇을 추가하라는 요청을 보낼 때 봇의 Communication Services ID가 올바르게 사용되는지 확인합니다.

다음 단계

BotFramework WebChat UI 구성 요소를 통해 채팅 사용자와 봇 간의 1:1 채팅을 위한 챗봇 데모 앱을 사용해 보세요.

Share via