Microsoft Teams ボットと会話する

重要

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

会話は、ボットと 1 人以上のユーザーの間で送信される一連のメッセージです。 Teams には、次の 3 種類の会話 (スコープとも呼ばれます) があります。

teams チャネルの会話とも呼ばれ、チャネルのすべてのメンバーに表示されます。
personal ボットと 1 人のユーザーの間の会話。
groupChatボットと 2 人以上のユーザーの間でChat。

ボットは、関与している会話の種類によって若干異なる動作をします。

チャネルおよびグループチャット会話のボットでは、ユーザーがボットを @mention してチャネル内で呼び出す必要があります。
単一ユーザー会話のボットでは、 @mention は必要ありません。ユーザーは入力するだけです。

ボットが特定のスコープで動作するためには、そのスコープをサポートするものとしてマニフェストで一覧表示する必要があります。スコープの定義と説明については、マニフェストリファレンスで詳しく説明します。

プロアクティブメッセージ

ボットは会話に参加したり、会話を開始したりすることができます。ほとんどの通信は、別のメッセージへの応答です。ボットが会話を開始した場合、それは プロアクティブメッセージと呼ばれます。たとえば、次のようなものがあります。

ウェルカムメッセージ
イベント通知
ポーリングメッセージ

会話の基本

各メッセージは、タイプ messageType: message の Activity オブジェクトです。ユーザーがメッセージを送信すると、Teams はメッセージをボットに投稿します。具体的には、JSON オブジェクトをボットのメッセージングエンドポイントに送信します。ボットはメッセージを調べて、その種類を判断し、それに応じて応答します。

ボットは、イベントスタイルのメッセージもサポートします。詳細については、「 Microsoft Teams でボットイベントを処理する」を参照してください。音声認識はサポートされていません。

通常、メッセージはすべてのスコープで同じですが、UI でのボットへのアクセス方法とバックグラウンドの違いには違いがあり、それを知っておく必要があります。

基本的な会話は、ボットが Teams やその他のチャネルと通信できるようにする単一の REST API である Bot Framework Connector を通じて処理されます。 Bot Builder SDK を使用すると、この API に簡単にアクセスでき、会話のフローと状態を管理するための追加機能や、自然言語処理 (NLP) などの認知サービスを簡単に組み込むことができます。

メッセージの内容

ボットは、リッチテキスト、画像、カードを送信できます。ユーザーはボットにリッチテキストと画像を送信できます。ボットが処理できるコンテンツの種類は、ボットの Microsoft Teams 設定ページで指定できます。

書式設定	ユーザーからボットへ	ボットからユーザーへ	メモ
リッチテキスト	✔	✔
写真	✔	✔	最大 1024×1024 MB、PNG、JPEG、GIF 形式で 1 MB。アニメーション GIF はサポートされていません。
カード	✖	✔	サポートされているカードについては、「 Teams カードリファレンス」を参照してください。
絵文字	✖	✔	Teams では、UTF-16 を介した絵文字 (ニヤリと笑う顔用の U+1F600 など) がサポートされています。

Teams のボットが基としている Bot Framework でサポートされているボット対話の種類の詳細については、Bot Builder SDK for .NET および Bot Builder SDK for Node.jsのドキュメントの、会話フローおよび関連する概念に関する Bot Framework ドキュメントを参照してください。

メッセージのフォーマット

messageの省略可能な TextFormat プロパティを設定して、メッセージのテキストコンテンツのレンダリング方法を制御できます。ボットメッセージでサポートされている書式設定の詳細については、「メッセージの書式設定」を参照してください。省略可能な TextFormat プロパティを設定して、メッセージのテキストコンテンツのレンダリング方法を制御できます。

Teams がチームでのテキストの書式設定をサポートする方法の詳細については、「ボットメッセージのテキストの書式設定」を参照してください。

メッセージ内のカードの書式設定の詳細については、「カードの書式設定」を参照してください。

画像メッセージ

画像は、メッセージに添付ファイルを追加して送信されます。添付ファイルの詳細については、 Bot Framework ドキュメントを参照してください。

画像は、PNG、JPEG、または GIF 形式で最大 1024×1024 MB および 1 MB にすることができます。アニメーション GIF はサポートされていません。

XML を使用して、各画像の高さと幅を指定することをお勧めします。 Markdown を使用する場合、画像サイズは既定で 256×256 になります。次に例を示します。

用途 <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
使用しないでください ![Duck on a rock](http://aka.ms/Fo983c)

メッセージの受信

宣言されているスコープに応じて、ボットは次のコンテキストでメッセージを受信できます。

個人用チャット ユーザーは、チャット履歴で追加されたボットを選択するか、新しいチャットの [宛先] ボックスにボットの名前またはアプリ ID を入力することで、ボットとのプライベートな会話で対話できます。
チャネル ボットがチームに追加されている場合、チャネルでボット ("@botname") にメンションできます。チャネル内のボットへの追加の応答には、ボットについてメンションする必要があることに注意してください。言及されていない返信には応答しません。

受信メッセージの場合、ボットは型 messageType: message のアクティビティオブジェクトを受け取ります。 Activity オブジェクトには、ボットに送信されるチャネルの更新など、他の種類の情報を含めることができますが、messageの種類はボットとユーザーの間の通信を表します。

ボットは、ユーザーメッセージ Text と、ユーザー、メッセージのソース、および Teams 情報に関するその他の情報を含むペイロードを受信します。注意事項:

timestamp メッセージの日付と時刻 (協定世界時 (UTC)。
localTimestamp 送信者のタイムゾーンでのメッセージの日付と時刻。
channelId 常に "msteams" です。これは、Teams チャネルではなく、ボットフレームワークチャネルを参照します。
from.id ボットのそのユーザーの一意で暗号化された ID。アプリでユーザーデータを格納する必要がある場合のキーとして適しています。これはボットに固有のものであり、ボットインスタンスの外部で意味のある方法でそのユーザーを識別するために直接使用することはできません。
channelData.tenant.id ユーザーのテナント ID。

注

from.id はボットに固有のものであり、ボットインスタンスの外部で意味のある方法でそのユーザーを識別するために直接使用することはできません。

ボットとのチャネルおよびプライベートな対話の組み合わせ

チャネルで対話するとき、ボットは、ユーザーとの特定の会話をオフラインにすることを賢くする必要があります。たとえば、ユーザーが一連のチームメンバーとのスケジュール設定など、複雑なタスクを調整しようとしているとします。対話のシーケンス全体をチャネルに表示するのではなく、ユーザーに個人用チャットメッセージを送信することを検討してください。ボットは、状態を失うことなく、個人用会話とチャネル会話の間でユーザーを簡単に移行できる必要があります。

注

対話が完了したら、他のチームメンバーに通知するためにチャネルを更新することを忘れないでください。

完全な受信スキーマの例

{
    "type": "message",
    "id": "1485983408511",
    "timestamp": "2017-02-01T21:10:07.437Z",
    "localTimestamp": "2017-02-01T14:10:07.437-07:00",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "channelId": "msteams",
    "from": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB39ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen",
        "aadObjectId": "7faf8ab2-3d56-4244-b585-20c8a42ed2b8"
    },
    "conversation": {
        "conversationType": "personal",
        "id": "a:17I0kl9EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-"
    },
    "recipient": {
        "id": "28:c9e8c047-2a74-40a2-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "textFormat": "plain",
    "text": "Hello Teams TestBot",
    "entities": [
      { 
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo"
      }
    ],
    "channelData": {
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "locale": "en-US"
}

注

受信メッセージのテキストフィールドには、メンションが含まれる場合があります。必ず適切にチェックして剥がしてください。詳細については、「メンション」を参照してください。

Teams チャネルデータ

channelData オブジェクトには、チーム固有の情報が含まれており、チーム ID とチャネル ID の決定的な情報源です。これらの ID をキャッシュして、ローカルストレージのキーとして使用する必要があります。

ボットに送信されるアクティビティの一般的な channelData オブジェクトには、次の情報が含まれています。

eventType Teams イベントの種類。チャネル変更イベントの場合にのみ渡されます。
tenant.idMicrosoft Entra テナント ID。すべてのコンテキストで渡されます。
team 個人用チャットではなく、チャネルコンテキストでのみ渡されます。
- id チャネルの GUID。
- name チームの名前。チームの名前変更イベントの場合にのみ渡されます。
channel ボットがメンションされたときにチャネルコンテキストで渡されるか、ボットが追加されたチーム内のチャネル内のイベントに対してのみ渡されます。
- id チャネルの GUID。
- name チャンネル名チャネル変更イベントの場合にのみ渡されます。
channelData.teamsTeamId 非推奨です。このプロパティは下位互換性のためだけに含まれます。
channelData.teamsChannelId 非推奨です。このプロパティは下位互換性のためだけに含まれます。

channelData オブジェクトの例 (channelCreated イベント)

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

.NET の例

Microsoft.Bot.Connector.Teams NuGet パッケージには、Teams 固有の情報にアクセスするためのプロパティを公開する特殊な TeamsChannelData オブジェクトが用意されています。

TeamsChannelData channelData = activity.GetChannelData<TeamsChannelData>();
string tenantId = channelData.Tenant.Id;

メッセージへの返信の送信

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

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

メッセージコンテンツ自体には、単純なテキストや、Bot Framework が提供するカードとカードアクションの一部を含めることができます。

送信スキーマでは、受信したものと同じ serviceUrl を常に使用する必要があることに注意してください。 serviceUrl の値は安定している傾向がありますが、変化する可能性があります。新しいメッセージが届いたら、ボットは格納されている値の serviceUrl を確認する必要があります。

メッセージの更新

メッセージをデータの静的なスナップショットにするのではなく、ボットはメッセージを送信後にインラインで動的に更新できます。動的メッセージ更新は、ポーリングの更新、ボタン押下後に使用可能なアクションの変更、その他の非同期状態変更などのシナリオに使用できます。

新しいメッセージは、元のメッセージの種類と一致する必要はありません。たとえば、元のメッセージに添付ファイルが含まれていた場合、新しいメッセージはテキストメッセージになることができます。

注

1 つの添付ファイルのメッセージとカルーセルレイアウトで送信されたコンテンツのみを更新できます。リストレイアウトで複数の添付ファイルを含むメッセージに更新情報を投稿することはサポートされていません。

REST API

メッセージ更新プログラムを発行するには、指定されたアクティビティ ID を使用して、 /v3/conversations/<conversationId>/activities/<activityId>/ エンドポイントに対して PUT 要求を実行します。このシナリオを完了するには、元の POST 呼び出しによって返されたアクティビティ ID をキャッシュする必要があります。

PUT /v3/conversations/19%3Aja0cu120i1jod12j%40skype.net/activities/012ujdo0128
{
    "type": "message",
    "text": "This message has been updated"
}

.NET の例

Bot Builder SDK の UpdateActivityAsync メソッドを使用して、既存のメッセージを更新できます。

public async Task<HttpResponseMessage> Post([FromBody]Activity activity)
{
  if (activity.Type == ActivityTypes.Message)
  {
    ConnectorClient connector = new ConnectorClient(new Uri(activity.ServiceUrl));
    Activity reply = activity.CreateReply($"You sent {activity.Text} which was {activity.Text.Length} characters");
    var msgToUpdate = await connector.Conversations.ReplyToActivityAsync(reply);
    Activity updatedReply = activity.CreateReply($"This is an updated message");
    await connector.Conversations.UpdateActivityAsync(reply.Conversation.Id, msgToUpdate.Id, updatedReply);
  }
}

Node.js 例

Bot Builder SDK の session.connector.update メソッドを使用して、既存のメッセージを更新できます。

function sendCardUpdate(bot, session, originalMessage, address) {

  var origAttachment = originalMessage.data.attachments[0];
  origAttachment.content.subtitle = 'Assigned to Larry Jin';

  var updatedMsg = new builder.Message()
    .address(address)
    .textFormat(builder.TextFormat.markdown)
    .addAttachment(origAttachment)
    .toMessage();

  session.connector.update(updatedMsg, function(err, addresses) {
    if (err) {
      console.log(`Could not update the message`);
    }
  });
}

会話を開始する (プロアクティブメッセージング)

ユーザーとの個人的な会話を作成したり、チームボットのチャネルで新しい返信チェーンを開始したりすることができます。これにより、ユーザーが最初にボットと接触することなく、ユーザーにメッセージを送信できます。詳細については、次の記事を参照してください。

ボットによって開始された会話の詳細については、「ボットのプロアクティブメッセージング」を参照してください。

メッセージを削除する

メッセージは、BotBuilder SDK の connector.delete() メソッドを使用して削除できます。

bot.dialog('BotDeleteMessage', function (session: builder.Session) {
  var msg = new teams.TeamsMessage(session).text("Bot will delete this message in 5 sec.")
  bot.send(msg, function (err, response) {
    if (err) {
      console.log(err);
      session.endDialog();
    }

    console.log('Proactive message response:');
    console.log(response);
    console.log('---------------------------------------------------')
    setTimeout(function () {
      var activityId: string = null;
      var messageAddress: builder.IChatConnectorAddress = null;
      if (response[0]){
        messageAddress = response[0];
        activityId = messageAddress.id;
      }

      if (activityId == null)
      {
        console.log('Message failed to send.');
        session.endDialog();
        return;
      }

      // Bot delete message
      let address: builder.IChatConnectorAddress  = {
        channelId: 'msteams',
        user: messageAddress.user,
        bot: messageAddress.bot,
        id : activityId,
        serviceUrl : (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
        conversation: {
          id: session.message.address.conversation.id
        }
      };

      connector.delete(address, function (err) {
        if (err)
        {
          console.log(err);
        }
        else
        {
          console.log("Message: " + activityId + " deleted successfully.");
        }

        // Try editing deleted message would fail
        var newMsg = new builder.Message().address(address).text("To edit message.");
        connector.update(newMsg.toMessage(), function (err, address) {
          if (err)
          {
            console.log(err);
            console.log('Deleted message can not be edited.');
          }
          else
          {
            console.log("There is something wrong. Message: " + activityId + " edited successfully.");
            console.log(address);
          }

          session.endDialog();
        });
      });
    }, 5000);
  });
})

フィードバック

このページはお役に立ちましたか?

Last updated on 2023-04-02

Microsoft Teams ボットと会話する

プロアクティブ メッセージ

会話の基本

メッセージの内容

メッセージのフォーマット

画像メッセージ

メッセージの受信

ボットとのチャネルおよびプライベートな対話の組み合わせ

完全な受信スキーマの例

Teams チャネル データ

channelData オブジェクトの例 (channelCreated イベント)

.NET の例

メッセージへの返信の送信

メッセージの更新

REST API

.NET の例

Node.js 例

会話を開始する (プロアクティブ メッセージング)

メッセージを削除する

フィードバック

その他のリソース

プロアクティブメッセージ

Teams チャネルデータ

会話を開始する (プロアクティブメッセージング)