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

  • [アーティクル]

重要

この記事は、v3 Bot Framework SDK に基づいています。 SDK の現在のドキュメント バージョン 4.6 以降をお探しの場合は、「 会話ボット 」セクションを参照してください。

Microsoft Teams でユーザーは、チャネルまたはグループ チャットの会話にボットを参加させることができます。 チームまたはチャットにボットを追加すると、会話のすべてのユーザーがボットの機能を会話内で利用できるようになります。 また、チーム情報や @mentioning ユーザーのクエリなど、ボット内の Teams 固有の機能にアクセスすることもできます。

チャネルでのチャットとグループ チャットは、ユーザーがボットに必要 @mention であるという点で個人用チャットとは異なります。 ボットが個人用、グループ チャット、チャネルなどの複数のスコープで使用されている場合は、ボット メッセージの元のスコープを検出し、それに応じて処理する必要があります。

チャネルまたはグループ用に優れたボットを設計する

チームに追加されたボットは別のチーム メンバーになり、会話の一部として使用 @mentioned できます。 実際、ボットは、 の場合 @mentionedにのみメッセージを受信するため、チャネル上の他の会話はボットに送信されません。

グループまたはチャネル内のボットは、すべてのメンバーに関係する適切な情報を提供する必要があります。 ボットが、エクスペリエンスに関わるどんな情報でも提供できるのは確かですが、それとの会話がすべてのユーザーに表示される点に留意してください。 それで、グループまたはチャネル内の優れたボットは、すべてのユーザーに付加価値を提供するものであり、1 対 1 の会話に向いている情報を誤って共有することがないはずです。

ボットと同様に、より多くの作業を必要とせずに、すべてのスコープで完全に関連している可能性があります。 Teams では、ボットがすべてのスコープで機能するとは思われませんが、サポートするスコープを選択した場合は、ボットがユーザー値を確実に提供するようにする必要があります。

グループまたはチャネルで動作するボットの開発では、個人の会話と同じ機能の多くを使用します。 ペイロード内の追加のイベントとデータで、Teams のグループおよびチャネルの情報を提供します。 それらの相違点、および一般的な機能の主な相違点について、以下のセクションで説明します。

メッセージの作成

チャネルでメッセージを作成するボットの詳細については、「 ボットのプロアクティブ メッセージング」、特に 「チャネル会話の作成」を参照してください。

メッセージの受信

グループまたはチャネル内のボットの場合、通常のメッセージ スキーマに加えて、ボットは次のプロパティも受け取ります。

  • channelData 「Teams チャネル データ」を参照してください。 グループ チャットには、そのチャットに固有の情報が含まれます。
  • conversation.id チャネル ID と、返信チェーン内の最初のメッセージの ID で構成される返信チェーン ID です。
  • conversation.isGroup チャネルまたはグループ チャットでのボット メッセージの場合に true となります。
  • conversation.conversationTypegroupChat または channel のどちらかです。
  • entities 1 つ以上のメンションを含めることができます。 詳細については、「メンション」を参照してください。

メッセージへの返信

既存のメッセージに返信するには、.NET では ReplyToActivity、Node.js では session.send を呼び出します。 Bot Builder SDK で、すべての詳細が処理されます。

REST API を使用する場合は、/conversations/{conversationId}/activities/{activityId} エンドポイントを呼び出すこともできます。

チャネルでは、メッセージへの返信は、開始された返信チェーンへの返信として示されます。 conversation.id には、チャネルと最上位メッセージ ID が含まれます。 Bot Framework によって詳細が処理されますが、必要に応じて、その会話スレッドへの今後の返信のために conversation.id をキャッシュすることができます。

ベスト プラクティス: Teams でのウェルカム メッセージ

ボットを最初にグループまたはチームに追加するときは、ボットを紹介するウェルカム メッセージをすべてのユーザーに送信すると便利です。 ウェルカム メッセージで、ボットの機能と、ユーザーへのメリットについて説明する必要があります。 理想的には、ユーザーがアプリとやり取りするためのコマンドもメッセージに含める必要があります。 これを行うには、channelData オブジェクトで teamsAddMembers eventType を使用して、ボットが conversationUpdate メッセージに応答するようにします。 ユーザーがチームに追加されるときにも同じイベントが送信されるため、必ず、memberAdded ID をボットのアプリ ID そのものにしてください。 詳細については、「 チーム メンバーまたはボットの追加」を参照してください。

ボットが追加されたときに、チームの各メンバーに個人用メッセージを送信することもできます。 これを行うには、チーム名簿を取得し、各ユーザーにダイレクト メッセージを送信することができます。

次の状況では、ボットからウェルカム メッセージを送信しないことをお勧めします。

  • チームは大規模です (100 人を超えるメンバーなど、明らかに主観的です)。 ウェルカム メッセージを見るすべてのユーザーにボットの価値提案を明確に伝えないなら、ボットは "スパム" と見なされ、追加したユーザーに苦情が寄せられる可能性があります。
  • ボットは、チームにまず追加されるのではなく、グループまたはチャネルでまずメンションされる。
  • グループまたはチャネルの名前が変更される。
  • チーム メンバーがグループまたはチャネルに追加される。

@メンション

グループまたはチャネル内のボットはメッセージにメンションされたときにのみ応答するため ("@botname")、グループ チャネル内のボットによって受信されたすべてのメッセージに独自の名前が含まれるため、メッセージ解析でそのメッセージが処理されるようにする必要があります。 さらにボットは、メンションされた他のユーザーを解析したり、メッセージの一部としてユーザーをメンションしたりすることができます。

メンションの取得

メンションは、ペイロードの entities オブジェクトで返され、ユーザーの一意の ID と、ほとんどの場合、メンションされたユーザーの名前を含みます。 メッセージ内のすべてのメンションを取得するには、.NET の場合、Bot Builder SDK で GetMentions 関数を呼び出します。これにより、Mentioned オブジェクトの配列が返されます。

.NET のコード例: メンションを確認して削除@botする

Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}

注:

ボットを含むすべてのメンションを取り出す、Teams 拡張関数 GetTextWithoutMentions を使用することもできます。

コード例 Node.js: メンションをチェックしてストリップ@botする

var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

ボットを含むすべてのメンションを取り出す、Teams 拡張関数 getTextWithoutMentions を使用することもできます。

メンションの作成

ボットは、チャネルに投稿されるメッセージで他のユーザーをメンションできます。 これを行うには、メッセージで次を行う必要があります。

  • メッセージ テキストに <at>@username</at> を含めます。
  • エンティティ コレクション内に mention オブジェクトを含めます。

.NET の例

この例では、Microsoft.Bot.Connector.Teams NuGet パッケージを使用します。

// Create reply activity
Activity replyActivity = activity.CreateReply();

// Construct text of the form @sender Hello
replyActivity.Text = "Hello ";
replyActivity.AddMentionToText(activity.From, MentionTextLocation.AppendText);

// Send the reply activity
await client.Conversations.ReplyToActivityAsync(replyActivity);

Node.js の例

// User to mention
var toMention: builder.IIdentity = {
    name: 'John Doe',
    id: userId
};

// Create a message and add mention to it
var msg = new teams.TeamsMessage(session).text(teams.TeamsMessage.getTenantId(session.message));
var mentionedMsg = msg.addMentionToText(toMention);

// Post the message
var generalMessage = mentionedMsg.routeReplyToGeneralChannel();
session.send(generalMessage);

例: ユーザーがメンションされた送信メッセージ

{
    "type": "message", 
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "28:9e52142b-5e5e-4d7b-bb3e- e82dcf620000",
        "name": "SchemaTestBot"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

groupChat または channel スコープへのアクセス

ボットは、グループおよびチームでのメッセージの送受信以上の操作を行うことができます。 たとえば、プロファイル情報やチャネルの一覧など、メンバーの一覧をフェッチすることもできます。 詳細については、「Microsoft Teams ボットのためにコンテキストを取得する」を参照してください。

関連項目

Bot Framework サンプル。