ボットとのチャネルおよびグループ チャットの会話

重要

このセクションのコード サンプルは、バージョン 4.6 以降のバージョンの Bot Framework SDK に基づいて作成されます。 以前のバージョンのドキュメントを探している場合は、ドキュメントの Resources フォルダーの 「bots - v3 SDK」 セクションを参照してください。

チームまたはグループ チャットMicrosoft Teamsボットをインストールするには、ボットにまたはteams``groupchatスコープを追加します。 これにより、会話のすべてのメンバーがボットと対話できるようになります。 ボットをインストールすると、会話に関するメタデータ (会話メンバーの一覧など) にアクセスできます。 また、チームにインストールすると、ボットは、そのチームに関する詳細とチャネルの完全なリストにアクセスできます。

グループまたはチャネル内のボットは、グループまたはチャネルに関する情報が記載されている場合にのみ@botname。 会話に送信された他のメッセージは受信しません。 ボットは直接 @メンションされる必要があります。 チームまたはチャネルが言及された場合、またはボットからメッセージに返信しても、ボットはメッセージを受信@mentioningされません。

注意

この機能は現在、パブリック開発者 プレビューでのみ利用 できます。

リソース固有の同意 (RSC) を使用して、ボットは、インストールされているチーム内のすべてのチャネル メッセージを受信@mentioned。 詳細については、「 RSC を使用してすべてのチャネル メッセージを受信する」を参照してください

現在、プライベート チャネルへのメッセージまたはアダプティブ カードの投稿はサポートされていません。

デザインのガイドライン

個人用チャットとは異なり、グループ チャットやチャネルでは、ボットが簡単な概要を提供する必要があります。 これらのボットの設計ガイドラインに従う必要があります。 ボットを設計する方法の詳細については、「Teamsチャットでボットの会話を設計する方法」を参照してください

これで、新しい会話スレッドを作成し、チャネル内の異なる会話を簡単に管理できます。

新しいスレッドの作成

ボットがチームにインストールされている場合は、既存のスレッドに返信するのではなく、新しいスレッドを作成する必要があります。 2 つの会話を区別することは困難な場合があります。 スレッド化された会話の場合は、チャネルでさまざまな会話を整理して管理する方が簡単です。 これは、プロアクティブ メッセージング の一形態です

次に、オブジェクトを使用してメンションを entities 取得し、オブジェクトを使用してメッセージにメンションを追加 Mention できます。

メンションを使用する

グループまたはチャネルからボットに送信されるメッセージには、その@mentionメッセージ テキストに名前が含まれているメッセージが含まれる。 ボットは、メッセージに記載されている他のユーザーを取得し、送信するメッセージにメンションを追加することもできます。

また、ボットが受信した@mentionsコンテンツから削除する必要があります。

メンションの取得

メンションはペイロード内の entities オブジェクトに返され、ユーザーの一意の ID と、指定したユーザーの名前の両方が含まれます。 メッセージのテキストには、次のようなメンションも含まれます <at>@John Smith<at>。 ただし、メッセージ内のテキストを使用して、ユーザーに関する情報を取得しない。 メッセージを送信するユーザーがメッセージを変更することができます。 したがって、オブジェクトを使用 entities します。

メッセージ内のすべてのメンションを GetMentions 取得するには、Bot Builder SDK で関数を呼び出し、オブジェクトの配列を返 Mention します。

次のコードは、メンションを取得する例を示しています。

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

メッセージにメンションを追加する

ボットは、チャネルに投稿されたメッセージで他のユーザーに言及できます。

オブジェクト Mention には、次の 2 つのプロパティを使用して設定する必要があります。

  • メッセージ の@username にデータを含める。
  • エンティティ コレクション内にメンション オブジェクトを含める。

Bot Framework SDK には、メンションを作成するヘルパー メソッドとオブジェクトが含まれています。

次のコードは、メッセージにメンションを追加する例を示しています。

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
    };

    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

これで、ボットが最初にインストールまたはグループまたはチームに追加された場合に、概要メッセージを送信できます。

インストール時にメッセージを送信する

ボットが最初にグループまたはチームに追加された場合は、紹介メッセージを送信する必要があります。 メッセージには、ボットの機能とボットの機能の使い方について簡単に説明する必要があります。 eventType を使用してイベント conversationUpdate をサブスクライブする teamMemberAdded 必要があります。 イベントは、新しいチーム メンバーが追加された場合に送信されます。 追加された新しいメンバーがボットか確認します。 詳細については、「ウェルカム メッセージを新しいチーム メンバーに送信する」を参照してください

ボットが追加された場合、各チーム メンバーに個人メッセージを送信します。 これを行うには、チーム名簿を取得し、各ユーザーに直接メッセージを送信します。

次の場合は、メッセージを送信しない。

  • チームは大きい (たとえば、100 人を超えるメンバー) です。 ボットはスパムと見なされ、追加したユーザーは苦情を受け取ることができます。 ウェルカム メッセージを見たすべてのユーザーに、ボットの価値提案を明確に伝える必要があります。
  • ボットは、最初にチームに追加されるのではなく、グループまたはチャネルで最初に言及されます。
  • グループまたはチャネルの名前が変更されます。
  • チーム メンバーがグループまたはチャネルに追加されます。

Teams ボットのサンプル

コード サンプル

機能を示す完全な作業サンプルについては、Bot Framework の次のTeamsサンプルを参照してください。

サンプル 説明 .NET JavaScript Python
Teams 会話ボット メッセージングと会話イベントの処理。 表示 表示 表示
OAuthPrompt を使用した認証 Bot Framework v4 での認証と基本メッセージング。 表示 表示 表示
Teams ファイルのアップロード 1 対 1 の会話でボットとファイルを交換する。 表示 表示 表示
タスク モジュール メッセージ拡張機能のタスク モジュールとその中のカードから値を取得する。 表示 表示 表示
チャネルで新しいスレッドを開始する チャネルに新しいスレッドを作成する。 表示 表示 表示

ステップ バイ ステップのガイド

ステップ バイ ステップ ガイドに従って、会話型ボットTeams作成します。

次の手順

関連項目

コンテキストTeams取得