ユーザーへのウェルカム メッセージの送信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. この目標を達成するための効果的な方法の 1 つは、ユーザーが最初にアクセスした瞬間から、ボットの主な目的と機能 (ボットが作られた理由) をユーザーがわかるようにすることです。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.

ボットの 2 つの主要なイベントを次に示します。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 図

接続された新しいユーザーには必ず、WelcomeMessageInfoMessage、および 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

ここで、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() を使用してアクティビティ更新をチェックし、会話に新しいユーザーが追加されたかどうかを確認して、そのユーザーに最初の 3 つのウェルカム メッセージ WelcomeMessageInfoMessage、および 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. 手順については、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