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

重要

このセクションのコード サンプルは、バージョン 4.6 以降のバージョンの Bot Framework SDK に基づいています。 以前のバージョンのドキュメントをお探しの場合は、ドキュメントのレガシ SDK フォルダーの ボット - v3 SDK セクションを参照してください。

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

グループまたはチャネル内のボットは、 @botnameメンションされたときにのみメッセージを受信します。 会話に送信された他のメッセージは受信されません。 ボットは直接 @mentioned される必要があります。 チームまたはチャネルがメンションされたとき、または誰かが @mentioning せずにボットからメッセージに返信した場合、ボットはメッセージを受け取りません。

注:

• すべての チャット メッセージの RSC は、 パブリック開発者プレビューでのみ使用できます。
• リソース固有の同意 (RSC) を使用すると、ボットは、 @mentionedされることなく、インストールされているチーム内のすべてのチャネル メッセージを受信できます。 詳細については、「 RSC を使用してすべてのチャネル メッセージを受信する」を参照してください。
• プライベート チャネルへのメッセージまたはアダプティブ カードの投稿はサポートされていません。

ボットとのチャネルチャットとグループ チャットの会話については、次のビデオを参照してください。

デザインのガイドライン

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

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

新しい会話スレッドを作成する

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

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

メンションの操作

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

また、ボットが受け取ったメッセージの内容から @mentions を取り除く必要もあります。

メンションを取得する

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

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

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

C#

• SDK レファレンス

• サンプル コード リファレンス

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Resolves the mentions from the entities activity.
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

TypeScript

SDK レファレンス

this.onMessage(async (turnContext, next) => {
    
    // Resolves the mentions from the entities activity.
    const mentions = TurnContext.getMentions(turnContext.activity);
    if (mentions){
        const firstMention = mentions[0].mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.sendActivity(`Hello ${firstMention.name}.`);
    } else {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.sendActivity(`Aw, no one was mentioned.`);
    }

    await next();
});

JSON

{
    "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": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "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"
}

Python

SDK レファレンス

@staticmethod
// Resolves the mentions from the entities of this activity.
def get_mentions(activity: Activity) -> List[Mention]:
    result: List[Mention] = []
    if activity.entities is not None:
        for entity in activity.entities:
            if entity.type.lower() == "mention":
                    result.append(entity)
     return result

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

メンションには次の 2 種類があります。

• ユーザー メンション
• タグ メンション

注:

ユーザー メンションとタグのメンションは、テキスト メッセージとアダプティブ カードの両方でサポートされています。

ユーザー メンション

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

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

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

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

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

C#

• 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>",
        Type = "mention",
    };

    // Returns a simple text message.
    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

TypeScript

this.onMessage(async (turnContext, next) => {
    const mention = {
        mentioned: turnContext.activity.from,
        text: `<at>${ new TextEncoder().encode(turnContext.activity.from.name) }</at>`,
        type: "mention",
    } as Mention;

    // Returns a simple text message.
    const replyActivity = MessageFactory.text(`Hello ${mention.text}`);
    replyActivity.entities = [mention];

    // Sends a message activity to the sender of the incoming activity.
    await turnContext.sendActivity(replyActivity);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

JSON

entities配列内の オブジェクトの text フィールドは、メッセージ text フィールドの一部と一致する必要があります。 そうでない場合、メンションは無視されます。

{
    "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": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "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"
}

Python

• SDK レファレンス
• サンプル コード リファレンス

async def _mention_activity(self, turn_context: TurnContext):
        mention = Mention(
            mentioned=turn_context.activity.from_property,
            text=f"<at>{turn_context.activity.from_property.name}</at>",
            type="mention"
        )
        // Returns a simple text message.
        reply_activity = MessageFactory.text(f"Hello {mention.text}")
        # Sends a message activity to the sender of the incoming activity.
        reply_activity.entities = [Mention().deserialize(mention.serialize())]
        await turn_context.send_activity(reply_activity)

これで、ボットが最初にインストールされたとき、またはグループまたはチームに追加されたときに、概要メッセージを送信できるようになりました。

ユーザー メンションでのMicrosoft Entra オブジェクト ID と UPN のサポート

ボットは、既存の ID に加えて、Microsoft Entra オブジェクト ID やユーザー プリンシパル名 (UPN) などのユーザー メンション ID をサポートします。 受信 Webhook は、Microsoft Entra オブジェクト ID と UPN を使用してアダプティブ カードのユーザー メンションをサポートし始めます。

次のコード スニペットは、テキスト メッセージで Entra オブジェクト ID と UPN を使用してユーザーをメンションする例を示しています。

var userId = "Adele@microsoft.com"; //User Principle Name
var mention = new ChannelAccount(userId, "Adele"); 
var mentionObj = new Mention 
{
    Mentioned = mention,
    Text = $"<at>{mention.Name}</at>" ,
    Type = "mention"
}; 

// Returns a simple text message.var replyActivity = MessageFactory.Text($"Hello {mentionObj.Text}.");replyActivity.Entities = new List<Entity> { mentionObj };

// Sends an activity to the sender of the incoming activity.await turnContext.SendActivityAsync(replyActivity, cancellationToken); 

次のコード スニペットは、アダプティブ カードで Entra オブジェクト ID と UPN を使用してユーザーをメンションする例を示しています。

{
    "type": "mention",
    "text": "<at>Adele</at>",
    "mentioned": {
            "id": "Adele@microsoft.com" ,// User Principle Name
            "name": "Adele"
    }
} 

タグ メンション

ボットは、テキスト メッセージとチャネルに投稿されたアダプティブ カードのタグをメンションできます。 ボットがチャネル内のタグを @mentions すると、タグが強調表示され、タグに関連付けられているユーザーに通知が届きます。 ユーザーがタグの上にマウス ポインターを合わせると、タグの詳細が表示されたポップアップが表示されます。

テキスト メッセージ内のタグをメンションする

mention.properties オブジェクトで、プロパティ 'type': 'tag'を追加します。 プロパティ 'type': 'tag'が追加されていない場合、ボットはメンションをユーザー メンションとして扱います。

例:

type:tagは ChannelAccount でPropertiesとして追加されます。

SDK レファレンス

​var mention = new ChannelAccount(tagId, "Test Tag"); 
​mention.Properties = JObject.Parse("{'type': 'tag'}"); 
​var mentionObj = new Mention 
​{ 
​    Mentioned = mention, 
​    Text = "<at>Test Tag</at>" 
​}; 

​var replyActivity = MessageFactory.Text("Hello " + mentionObj.Text); 
​replyActivity.Entities = new List<Microsoft.Bot.Schema.Entity> { mentionObj }; 
​await turnContext.SendActivityAsync(replyActivity, cancellationToken); 

アダプティブ カードのタグをメンションする

アダプティブ カード スキーマの mentioned オブジェクトの下に、 "type": "tag" プロパティを追加します。 "type": "tag" プロパティが追加されていない場合、ボットはメンションをユーザー メンションとして扱います。

チャネルで使用可能なタグの一覧は、 list teamworkTags API を使用して取得できます。

例:

​{ 
​    "type": "mention", 
    ​"text": "<at>Test Tag</at>", 
​    "mentioned": { 
            ​"id": "base64 encoded id" ,// tag graph 64 base ID
​            "name": "Test Tag", 
            ​"type": "tag" 
​    } 
​} 

クエリ パラメーター

名前	説明
type	メンションの種類。 サポートされている型は tag。
id	タグの一意識別子。 詳細については、「 teamworkTag」を参照してください。

エラー コード

状態コード	エラー コード	メッセージ値	再試行要求	開発者アクション
400	コード: Bad Request	ID {id string} を持つメンション タグが現在のチームに存在しません タグはチャネルでのみ記述できます タグがチームに存在しないため、メンションされたタグが無効です	いいえ	エラーの要求ペイロードを再評価します。 詳細については、返されたエラー メッセージを確認してください。
502	コード: Bad Gateway	無効なチーム グループ ID タグのテナント ID の形式が正しくありません メンション ID を解決できない	いいえ	手動で再試行します。

制限の調整

スコープ、ウィンドウの種類 (短と長)、メッセージごとのタグ数、その他の要因に応じて、要求を複数の制限に対して評価できます。 最初に到達した上限に達すると、トリガーの調整が行われます。

メッセージ配信の失敗を回避するために、調整の制限を超えないようにします。 たとえば、ボットは 5 秒間のウィンドウでタグがメンションされたメッセージを 2 つだけ送信でき、各メッセージには最大 10 個のタグのみを含めることができます。

次の表に、ボット内のタグメンションの調整制限を示します。

スコープ	ウィンドウの種類	メッセージあたりのタグ数	タイム ウィンドウ (秒)	時間枠あたりのメッセージの最大数
スレッドあたりのボットごと	短い	10	5	2
	長い	10	60	5
スレッドあたりのすべてのボット	短い	10	5	4
	Long	10	60	5

制限事項

• タグメンションは、テキストとアダプティブ カードを使用したボットからクライアント へのメッセージ フローでのみサポートされます。
• タグメンションは、共有チャネルとプライベート チャネルではサポートされていません。
• タグメンションはコネクタではサポートされていません。
• タグメンションでは、ボットの呼び出しフローはサポートされていません。

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

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

ボットが追加されたときに、チームの各メンバーに個人用メッセージを送信できます。 これを行うには、 チーム名簿をフェッチ し、各ユーザーに 直接メッセージを送信します。

注:

ボットによって送信されたメッセージが関連し、最初のメッセージに値を追加し、ユーザーをスパムしないようにします。

次の場合はメッセージを送信しないでください。

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

Teams ボットのサンプル

コード サンプル

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

サンプルの名前	説明	.NET	Node.js	Python	マニフェスト
Teams 会話ボット	このサンプルでは、ボット フレームワーク v4 で使用できるさまざまなボット会話イベントを個人用とチームのスコープに使用する方法を示します。	表示	表示	表示	表示
OAuthPrompt による認証	このサンプルでは、Bot Framework v4 での認証と基本的なメッセージングを示します。	表示	表示	表示	表示
Teams ファイルのアップロード	このサンプルでは、1 対 1 の会話でボットでファイルを使用する方法を示します。	表示	表示	表示	表示
ダイアログ (TeamsJS v1.x のタスク モジュールと呼ばれます)	このサンプルでは、メッセージ拡張機能にダイアログとカードの値を使用する方法を示します。	表示	表示	表示	表示
チャネルで新しいスレッドを開始する	このサンプルでは、ボットを使用してチャネルで新しいスレッドを使用する方法を示します。	表示	表示	表示	表示
Teams アプリのローカライズ	このサンプルでは、ボットとタブを使用して Teams アプリのローカライズを使用する方法を示します。	表示	表示	該当なし	表示

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

詳細なガイドに従って、Teams 会話ボットを作成します。

次の手順

会話イベントにサブスクライブする

関連項目

• Teams のコンテキストを取得する
• ユーザーの代わりにプライベート チャネルを作成する
• ボットをWeb チャット チャネルに接続する