ボットとのチャネルおよびグループ チャットの会話
重要
このセクションのコード サンプルは、バージョン 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.");
}
}
メッセージにメンションを追加する
メンションには次の 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);
}
これで、ボットが最初にインストールされたとき、またはグループまたはチームに追加されたときに、概要メッセージを送信できるようになりました。
タグメンション
ボットは、チャネルに投稿されたテキスト メッセージとアダプティブ カードにタグをメンションできます。 ボットがチャネル内のタグを @mentions すると、タグが強調表示され、タグに関連付けられているユーザーに通知が届きます。 ユーザーがタグの上にマウス ポインターを合わせると、タグの詳細が表示されたポップアップが表示されます。
注:
タグメンションは、Government Community Cloud (GCC)、GCC-High、および国防総省 (DoD) テナントではサポートされていません。
テキスト メッセージ内のタグをメンションする
mention.properties
オブジェクトで、プロパティ 'type': 'tag'
を追加します。 プロパティ 'type': 'tag'
が追加されていない場合、ボットはメンションをユーザーメンションとして扱います。
例:
type:tag
は ChannelAccount でProperties
として追加されます。
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 会話ボットを作成します。
次の手順
関連項目
Platform Docs