Отправка приветственного сообщения пользователям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

Сведения о примере кода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 и выясняет, имеет ли DidBotWelcomeUser значение true.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

Теперь мы создадим метод доступа к свойству, предоставляющий обработчик WelcomeUserState в методе OnMessageActivityAsync.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(), чтобы узнать, добавлен ли новый пользователь в диалог. Затем мы отправляем ему набор из трех приветственных сообщений: 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. Затем мы присваиваем значение true свойству welcomedUserProperty, которое хранится в 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. Инструкции см. в разделе пример README файла для C# или JS.If you need instructions, refer to the README file for C# Sample or JS Sample.
  2. Примените эмулятор для тестирования бота, как показано ниже.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