사용자에게 환영 메시지 보내기Send welcome message to users

적용 대상: SDK v4APPLIES TO: SDK v4

봇을 만들 때 가장 중요한 목표는 사용자를 의미 있는 대화에 참여시키는 것입니다.The primary goal when creating any bot is to engage your user in a meaningful conversation. 이 목표를 달성하는 가장 좋은 방법 중 하나는 사용자가 처음 연결하는 순간부터 봇의 주요 목적과 기능, 즉, 봇이 만들어진 이유를 이해하는 것입니다.One of the best ways to achieve this goal is to ensure that from the moment a user first connects, they understand your bot's main purpose and capabilities, the reason your bot was created. 이 문서에서는 봇의 사용자를 환영하는 데 유용한 코드 예제를 제공합니다.This article provides code examples to help you welcome users to your bot.

필수 구성 요소Prerequisites

  • 봇 기본 사항을 이해합니다.Understand bot basics.
  • C# 샘플, JS 샘플,Java 샘플 또는 Python 샘플 중 하나에 있는 Welcome 사용자 샘플의 복사본입니다. A copy of the Welcome user sample in either C# Sample, JS Sample, Java Sample or Python Sample. 샘플의 코드는 환영 메시지를 보내는 방법을 설명하는 데 사용됩니다.The code from the sample is used to explain how to send welcome messages.

이 샘플 코드 정보About this sample code

이 샘플 코드는 새로운 사용자가 봇에 처음 연결되었을 때 이를 감지하고 환영 메시지를 표시하는 방법을 보여줍니다.This sample code shows how to detect and welcome new users when they are initially connected to your bot. 다음 다이어그램은 이 봇의 논리적 흐름을 보여줍니다.The following diagram shows the logic flow for this bot.

봇에서 발생하는 두 가지 주요 이벤트는 다음과 같습니다.The two main events encountered by the bot are:

  • OnMembersAddedAsync - 봇에 새 사용자가 연결될 때마다 호출됩니다.OnMembersAddedAsync which is called whenever a new user is connected to your bot
  • OnMessageActivityAsync - 새 사용자 입력이 수신될 때마다 호출됩니다.OnMessageActivityAsync which is called whenever a new user input is received.

사용자 논리 흐름 시작 csharp 다이어그램

새 사용자가 연결될 때마다 봇이 사용자에게 WelcomeMessage, InfoMessage, PatternMessage를 표시합니다.Whenever a new user is connected, they are provided with a WelcomeMessage, InfoMessage, and PatternMessage by the bot. 새 사용자 입력이 수신되면 봇이 WelcomeUserState의 DidBotWelcomeUsertrue 로 설정되어 있는지 확인합니다.When a new user input is received, WelcomeUserState is checked to see if DidBotWelcomeUser is set to true. 그렇지 않을 경우 초기 사용자 환영 메시지가 사용자에게 반환됩니다.If not, an initial welcome user message is returned to the user.

사용자 상태 만들기Create user state

사용자 상태 개체는 시작 시 만들어지며 종속성이 봇 생성자에 주입됩니다.The user state object is created at startup and dependency injected into the bot constructor.

Startup.cs [!code-csharpdefine state]Startup.cs [!code-csharpdefine state]

Bots\WelcomeUserBot.cs [!code-csharpconsume state]Bots\WelcomeUserBot.cs [!code-csharpconsume state]

속성 접근자 만들기Create property accessors

이제 OnMessageActivityAsync 메서드 내에서 WelcomeUserState에 대한 핸들을 제공하는 속성 접근자를 만듭니다.We now create a property accessor that provides us a handle to WelcomeUserState inside the OnMessageActivityAsync method. 그런 다음, GetAsync 메서드를 호출하여 올바르게 범위가 지정된 키를 가져옵니다.Then call the GetAsync method to get the properly scoped key. 그리고 SaveChangesAsync 메서드를 사용한 각 사용자 입력 반복 후 사용자 상태 데이터를 저장합니다.We then save user state data after each user input iteration using the SaveChangesAsync method.

Bots\WelcomeUserBot.cs [!code-csharpGet state]Bots\WelcomeUserBot.cs [!code-csharpGet state]

// Save any state changes.
await _userState.SaveChangesAsync(turnContext, cancellationToken: cancellationToken);

새로 연결된 사용자 감지 및 인사말 표시Detect and greet newly connected users

WelcomeUserBot 에서 OnMembersAddedAsync()를 통해 활동 업데이트를 확인하여 새 사용자가 대화에 추가되었는지 본 다음, 일련의 초기 환영 메시지 3개(WelcomeMessage, InfoMessage, PatternMessage)를 전송합니다.In WelcomeUserBot, we check for an activity update using OnMembersAddedAsync() to see if a new user has been added to the conversation and then send them a set of three initial welcome messages WelcomeMessage, InfoMessage and PatternMessage. 이 상호 작용의 전체 코드는 다음과 같습니다.Complete code for this interaction is shown below.

Bots\WelcomeUserBot.cs [!code-csharpDefine messages]Bots\WelcomeUserBot.cs [!code-csharpDefine messages]

protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var member in membersAdded)
    {
        if (member.Id != turnContext.Activity.Recipient.Id)
        {
            await turnContext.SendActivityAsync($"Hi there - {member.Name}. {WelcomeMessage}", cancellationToken: cancellationToken);
            await turnContext.SendActivityAsync(InfoMessage, cancellationToken: cancellationToken);
            await turnContext.SendActivityAsync($"{LocaleMessage} Current locale is '{turnContext.Activity.GetLocale()}'.", cancellationToken: cancellationToken);
            await turnContext.SendActivityAsync(PatternMessage, cancellationToken: cancellationToken);
        }
    }
}

새 사용자를 환영하고 초기 입력 무시Welcome new user and discard initial input

사용자 입력에 실제로 유용한 정보가 포함될 수 있는 시점을 고려하는 것도 중요하며, 이 또한 채널별로 다를 수 있습니다.It is also important to consider when your user's input might actually contain useful information, and this may vary for each channel. 사용자가 모든 가능한 채널에 대해 우수한 환경을 갖출 수 있도록 didBotWelcomeUser 상태 플래그를 확인하여 "false"인 경우 이 초기 사용자 입력을 처리하지 않습니다.To ensure your user has a good experience on all possible channels, we check the status flag didBotWelcomeUser and if this is "false", we do not process the initial user input. 대신 사용자에게 초기 환영 메시지를 제공합니다.We instead provide the user with an initial welcome message. 그런 다음, welcomedUserProperty 부울이 "true"로 설정되고, UserState에 저장되며, 이제 코드에서 모든 추가 메시지 작업의 이 사용자 입력을 처리합니다.The bool welcomedUserProperty is then set to "true", stored in UserState and our code will now process this user's input from all additional message activities.

Bots\WelcomeUserBot.cs [!code-csharpDidBotWelcomeUser]Bots\WelcomeUserBot.cs [!code-csharpDidBotWelcomeUser]

// Save any state changes.
await _userState.SaveChangesAsync(turnContext, cancellationToken: cancellationToken);

추가 입력 처리Process additional input

새 사용자에게 환영 메시지가 표시된 후에는 각 메시지 순서의 사용자 입력 정보가 평가되고, 봇이 해당 사용자 입력의 컨텍스트에 따라 응답을 제공합니다.Once a new user has been welcomed, user input information is evaluated for each message turn and the bot provides a response based on the context of that user input. 다음 코드는 해당 응답을 생성하는 데 사용되는 결정 논리를 보여줍니다.The following code shows the decision logic used to generate that response.

'intro' 또는 'help'를 입력하면 SendIntroCardAsync 함수가 호출되고 사용자에게 정보 제공용 영웅 카드가 제공됩니다.An input of 'intro' or 'help' calls the function SendIntroCardAsync to present the user with an informational hero card. 해당 코드는 이 문서의 다음 섹션에 나옵니다.That code is examined in the next section of this article.

Bots\WelcomeUserBot.cs [!code-csharpSwitchOnUtterance]Bots\WelcomeUserBot.cs [!code-csharpSwitchOnUtterance]

영웅 카드 인사말 사용Using hero card greeting

앞서 말했듯이, 일부 사용자 입력은 요청에 대한 응답으로 영웅 카드 를 생성합니다.As mentioned above, some user inputs generate a Hero Card in response to their request. 시작 카드 보내기에서 영웅 카드 인사말에 대해 자세히 알아볼 수 있습니다.You can learn more about hero card greetings here Send an Intro Card. 이 봇의 영웅 카드 응답을 만드는 데 필요한 코드는 다음과 같습니다.Below is the code required to create this bot's hero card response.

Bots\WelcomeUserBot.cs [!code-csharpSendHeroCardGreeting]Bots\WelcomeUserBot.cs [!code-csharpSendHeroCardGreeting]

봇 테스트Test the bot

최신 Bot Framework Emulator를 다운로드하고 설치합니다.Download and install the latest Bot Framework Emulator

  1. 샘플을 머신에서 로컬로 실행합니다.Run the sample locally on your machine. 지침이 필요한 경우 C# 샘플 또는 JS 샘플에 대한 추가 정보 파일을 참조하세요.If you need instructions, refer to the README file for C# Sample or JS Sample.
  2. Emulator를 사용하여 아래와 같이 봇을 테스트합니다.Use the Emulator to test the bot as shown below.

환영 봇 샘플 테스트

영웅 카드 인사말을 테스트합니다.Test hero card greeting.

환영 봇 카드 테스트

추가 리소스Additional Resources

메시지에 미디어 추가에서 다양한 미디어 응답에 대해 자세히 알아봅니다.Learn more about various media responses in Add media to messages.

다음 단계Next steps