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

[アーティクル]
11/19/2024

重要

このセクションのコードサンプルは、バージョン 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 オブジェクトの配列を返します。

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

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.");
    }
}

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();
});

{
    "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"
}

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 には、メンションを作成するためのヘルパーメソッドとオブジェクトが用意されています。

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

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);
}

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();
});

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"
}

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 会話ボットを作成します。

次の手順

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

次の方法で共有

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

デザインのガイドライン

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

メンションの操作

メンションを取得する

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

ユーザーメンション

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

タグメンション

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

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

クエリパラメーター

エラーコード

制限の調整

制限事項

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

Teams ボットのサンプル

コードサンプル

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

次の手順

関連項目

その他のリソース

次の方法で共有

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

デザインのガイドライン

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

メンションの操作

メンションを取得する

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

ユーザー メンション

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

タグ メンション

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

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

クエリ パラメーター

エラー コード

制限の調整

制限事項

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

Teams ボットのサンプル

コード サンプル

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

次の手順

関連項目

その他のリソース

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

ユーザーメンション

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

タグメンション

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

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

クエリパラメーター

エラーコード

コードサンプル

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