次の方法で共有

メッセージの送受信

  • [アーティクル]

会話型ボットはメッセージングを通じてユーザーと通信し、シームレスな対話を可能にします。 テキストまたは音声による操作を通じて、ユーザーとの実際の会話をシミュレートできます。 ボットの会話が対話型、動的、アダプティブ、およびユーザー フレンドリであることを確認する必要があります。

メッセージの内容

ボットとユーザー間のメッセージ操作には、次のようなさまざまな種類のメッセージ コンテンツを含めることができます。

コンテンツ タイプ ユーザーからボットへ ボットからユーザーへ
リッチ テキストと絵文字 ✔️ ✔️
画像 ✔️ ✔️
アダプティブ カード ❌ ✔️

リッチ テキスト メッセージと絵文字を使用する

Teams ボットは、リッチ テキストと絵文字を送信できます。 Teams では、U+1F600 のように UTF-16 を介して絵文字がサポートされ、笑う顔に対応しています。

画像メッセージを使用する

ボット メッセージをポップにするために、ユーザーは画像を添付ファイルとして追加できます。

  • 画像は最大 1024 × 1024 ピクセル、PNG、JPEG、GIF 形式では 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).

添付ファイルの詳細については、「メッセージに メディア添付ファイルを追加する」を参照してください。

アダプティブ カードを使用する

会話型ボットには、ビジネス ワークフローを簡略化するアダプティブ カードを含めることができます。 アダプティブ カードは、カスタマイズ可能な豊富なテキスト、音声、画像、ボタン、入力フィールドを提供します。 ボットでアダプティブ カードを作成し、Teams、Web サイトなどの複数のアプリに表示できます。

詳細については、以下を参照してください:

次のコードは、単純なアダプティブ カードを送信する例を示しています。

例: 単純なアダプティブ カードを送信する 
{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
    {
        "items": [
        {
            "size": "large",
            "text": " Simple Adaptivecard Example with a Textbox",
            "type": "TextBlock",
            "weight": "bolder",
            "wrap": true
        },
        ],
        "spacing": "extraLarge",
        "type": "Container",
        "verticalContentAlignment": "center"
    }
    ]
}

メッセージの送受信

メッセージの送受信は、ボットのコア機能です。 これにより、ボットは次のことが可能になります。

チャットでは、各メッセージは messageType: message 型のActivity オブジェクトです。 誰かがメッセージを送信すると、Microsoft Teamsはボットに投稿します。 Teams は JSON オブジェクトをボットのメッセージング エンドポイントに送信し、メッセージングに使用できるエンドポイントは 1 つだけです。 その後、ボットはメッセージをチェックして、その種類を把握し、それに応じて応答します。

基本的な会話は、1 つの REST API である Bot Framework コネクタを介して管理されます。 この API を使用すると、ボットが Teams やその他のチャネルと通信できるようになります。 Bot Builder SDK には、次の機能があります。

  • Bot Framework コネクタに簡単にアクセスできます。
  • 会話フローと状態を管理するためのツール。
  • 自然言語処理 (NLP) などのコグニティブ サービスを追加する簡単な方法。

ボットは、 Text プロパティを使用して Teams からメッセージを取得し、1 つまたは複数の応答をユーザーに送信できます。

詳細については、「 ボット メッセージのユーザー属性」を参照してください。

次の表に、ボットが受け取ってアクションを実行できるアクティビティの一覧を示します。

メッセージの種類 ペイロード オブジェクト 範囲
メッセージ アクティビティを受信する メッセージ アクティビティ すべて
メッセージの編集アクティビティを受信する メッセージ編集アクティビティ すべて
メッセージの削除を取り消すアクティビティを受信する メッセージの削除の取り消しアクティビティ すべて
論理的な削除メッセージ アクティビティを受信する メッセージの論理的な削除アクティビティ すべて

メッセージ アクティビティを受信する

テキスト メッセージを受信するには、Activity オブジェクトの Text プロパティを使用します。 ボットのアクティビティ ハンドラーで、ターン コンテキスト オブジェクトの Activity を使用して、1 つのメッセージ要求を読み取ります。

次のコードは、メッセージ アクティビティを受信する例を示しています。


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}

開封確認メッセージを受信する

Teams の [開封確認] 設定を使用すると、1 対 1 のチャットとグループ チャットで受信者がメッセージを読んだときに、チャット メッセージの送信者に通知を受け取ります。 受信者がメッセージを読み取った後、メッセージの横に [表示 が表示されます。 また、[開封確認] 設定を使用して読み取り受信イベントを受信するようにボット を構成することもできます 。 開封確認イベントは、次の方法でユーザー エクスペリエンスを向上させるのに役立ちます。

  • アプリ ユーザーが個人用チャットでメッセージを読み取っていない場合は、フォローアップ メッセージを送信するようにボットを構成できます。

  • 読み取りレシートを使用してフィードバック ループを作成して、ボットのエクスペリエンスを調整できます。

注:

  • 読み取りレシートは、ユーザーからボットへのチャット シナリオでのみサポートされます。
  • ボットの開封確認は、チーム、チャネル、グループ チャットスコープをサポートしていません。
  • 管理者またはユーザーが [開封確認] 設定を無効にした場合、ボットは開封確認イベントを受け取りません。

ボットの開封確認イベントを受信するには、次のことを確認します。

    
"webApplicationInfo": {
    
     "id": "38f0ca43-1c38-4c39-8097e-47f62c686500",
     "resource": ""
},
"authorization": {
    "permissions": {
    "orgwide": [],
     "resourceSpecific": [
        {
        "name": "ChatMessageReadReceipt.Read.Chat",
        "type": "Application"
        }
        ]
     }
 }

Graph APIを使用して RSC アクセス許可を追加することもできます。 詳細については、consentedPermissionSetを参照してください。

  • メソッド OnTeamsReadReceiptAsync を IsMessageRead ハンドラーでオーバーライドします。

    IsMessageRead ヘルパー メソッドは、メッセージが受信者によって読み取られたかどうかを判断するのに役立ちます。 compareMessageIdがLastReadMessageId以下の場合は、メッセージが読み取られます。 IsMessageRead ヘルパー メソッドを使用して読み取りレシートを受信するには、OnTeamsReadReceiptAsync メソッドをオーバーライドします。

    
protected override async Task OnTeamsReadReceiptAsync(ReadReceiptInfo readReceiptInfo, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken) 
{
    var lastReadMessageId = readReceiptInfo.LastReadMessageId;
   if (IsMessageRead("{id of the message that you care}", LastReadMessageId))
   {
        await turnContext.SendActivityAsync(MessageFactory.Text("User read the bot's message"), cancellationToken);    
    }
}

    次の例は、ボットが受け取る開封確認イベント要求を示しています。

    {
    "name": "application/vnd.microsoft.readReceipt",
    "type": "event",
    "timestamp": "2023-08-16T17:23:11.1366686Z",
    "id": "f:b4783e72-9d7b-2ed9-ccef-ab446c873007",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1-8Iuh70W9pRqV8tQK8o2nVjxz33RRGDKLf4Bh7gKnrzN8s7e4vCyrFwjkPbTCX_Co8c4aXwWvq3RBLr-WkkVMw",
        "aadObjectId": "5b649834-7412-4cce-9e69-176e95a394f5"
    },
    "conversation": {
        "conversationType": "personal",
        "tenantId": "6babcaad-604b-40ac-a9d7-9fd97c0b779f",
        "id": "a:1xlimp68NSUxEqK0ap2rXuwC9ITauHgV2M4RaDPkeRhV8qMaFn-RyilMZ62YiVdqs8pp43yQaRKvv_U2S2gOS5nM-y_pOxVe4BW1qMGPtqD0Bv3pw-nJXF0zhDlZHMZ1Z"
    },
    "recipient": {
        "id": "28:9901a8b6-4fef-428b-80b1-ddb59361adeb",
        "name": "Test Bot"
    },
    "channelData": {
        "tenant": {
            "id": "6babcaad-604b-40ac-a9d7-9fd97c0b779f"
        }
    },
    "value": {
        "lastReadMessageId": "1692206589131"
    }
}

  • ボットが開封確認イベントを受信するためのテナントに対して、開封確認 管理者の設定 または ユーザー設定 が有効になっています。 管理者またはユーザーは、開封確認の設定を有効または無効にする必要があります。

ユーザーからボットへのチャット シナリオでボットが有効になると、ボットは、ユーザーがボットのメッセージを読み取ったときに、読み取り受信イベントをすぐに受信します。 イベントの数をカウントすることでユーザー エンゲージメントを追跡でき、コンテキスト対応メッセージを送信することもできます。

メッセージの編集アクティビティを受信する

メッセージを編集すると、ボットはメッセージの編集アクティビティの通知を受け取ります。

ボットでメッセージ アクティビティの編集通知を取得するには、ハンドラー OnTeamsMessageEditAsync オーバーライドできます。

送信されたメッセージが編集されたときに OnTeamsMessageEditAsync を使用したメッセージの編集アクティビティ通知の例を次に示します。


protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken) 
{ 
var replyActivity = MessageFactory.Text("message is updated"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}

メッセージを送信する

テキスト メッセージを送信するには、アクティビティとして送信する文字列を指定します。 ボットのアクティビティ ハンドラーで、ターン コンテキスト オブジェクトの SendActivityAsync メソッドを使用して、1 つのメッセージ応答を送信します。 オブジェクトの SendActivitiesAsync メソッドを使用して、複数の応答を送信します。

次のコードは、ユーザーが会話に追加されたときにメッセージを送信する例を示しています。


protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}

注:

  • メッセージ分割は、テキスト メッセージと添付ファイルが同じアクティビティ ペイロードで送信されるときに発生します。 Teams では、このアクティビティを 2 つの別々のアクティビティに分割します。1 つはテキスト メッセージで、もう 1 つは添付ファイルを含みます。 アクティビティが分割されると、応答としてメッセージ ID は受信されません。これは、メッセージを事前に 更新または削除 するために使用されます。 メッセージ分割に応じてではなく、個別のアクティビティを送信することをお勧めします。
  • 送信されたメッセージは、パーソナル化を提供するためにローカライズできます。 詳細については、「 アプリのローカライズ」を参照してください。

ユーザーとボットの間で送信されるメッセージには、メッセージ内の内部チャネル データが含まれます。 このデータを使用すると、ボットはそのチャネルで適切に通信できます。 Bot Builder SDK を使用すると、メッセージ構造を変更できます。

メッセージの削除を取り消すアクティビティを受信する

メッセージの削除を取り消すと、ボットは削除解除メッセージ アクティビティの通知を受け取ります。

ボットで削除を取り消すメッセージ アクティビティ通知を取得するには、ハンドラー OnTeamsMessageUndeleteAsync オーバーライドできます。

削除されたメッセージが復元されたときに、 OnTeamsMessageUndeleteAsync を使用してメッセージ アクティビティを元に戻す通知の例を次に示します。


protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{ 
var replyActivity = MessageFactory.Text("message is undeleted"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}

論理的な削除メッセージ アクティビティを受信する

メッセージを論理的に削除すると、ボットは論理的な削除メッセージ アクティビティの通知を受け取ります。

ボットで論理的な削除メッセージ アクティビティ通知を取得するには、ハンドラー OnTeamsMessageSoftDeleteAsync オーバーライドできます。

次の例は、メッセージが論理的に削除されたときに OnTeamsMessageSoftDeleteAsync を使用した論理的な削除メッセージ アクティビティ通知を示しています。


protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken) 
{ 
var replyActivity = MessageFactory.Text("message is soft deleted"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}

ボットから送信されたメッセージを更新および削除する

重要

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

ボットは、メッセージをデータの静的スナップショットとして保持する代わりに、メッセージを送信した後に動的に更新できます。 メッセージは、Bot Framework の DeleteActivity メソッドを使用して削除することもできます。

注:

ボットは、Microsoft Teamsでユーザーによって送信されたメッセージを更新または削除できません。

メッセージを更新する

ポーリングの更新、ボタンを押した後の使用可能なアクションの変更、その他の非同期状態の変更などのシナリオでは、動的メッセージ更新を使用できます。

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

既存のメッセージを更新するには、既存のアクティビティ ID を持つ新しい Activity オブジェクトを TurnContext クラスの UpdateActivityAsync メソッドに渡します。

// Send initial message
var response = await turnContext.SendActivityAsync(MessageFactory.Attachment(card.ToAttachment()), cancellationToken);
var activityId = response.Id; // Fetch activity id.

// MessageFactory.Text(): Specifies the type of text data in a message attachment.
var newActivity = MessageFactory.Text("The new text for the activity");
newActivity.Id = activityId;

// UpdateActivityAsync(): A method that can participate in update activity events for the current turn.
await turnContext.UpdateActivityAsync(newActivity, cancellationToken);

メッセージを更新したので、受信アクティビティのボタン選択時に既存のカードを更新します。

カードを更新する

ボタン選択時に既存のカードを更新するには、着信アクティビティの ReplyToIdを使用できます。

ボタン選択で既存のカードを更新するには、更新されたカードとアクティビティ ID として ReplyToId を含む新しい Activity オブジェクトを TurnContext クラスの UpdateActivityAsync メソッドに渡します。

// Returns a message activity that contains an attachment.
var activity = MessageFactory.Attachment(card.ToAttachment());
activity.Id = turnContext.Activity.ReplyToId;

// A method that can participate in update activity events for the current turn.
await turnContext.UpdateActivityAsync(activity, cancellationToken);

カードを更新したので、Bot Framework を使用してメッセージを削除できます。

メッセージを削除する

Bot Framework では、すべてのメッセージに一意のアクティビティ識別子があります。 メッセージは、Bot Framework の DeleteActivity メソッドを使用して削除できます。

メッセージを削除するには、そのアクティビティの ID を TurnContext クラスの DeleteActivityAsync メソッドに渡します。

foreach (var activityId in _list)
{
    // When overridden in a derived class, deletes an existing activity in the conversation.
    await turnContext.DeleteActivityAsync(activityId, cancellationToken);
}

推奨されるアクションを送信する

推奨されるアクションを使用すると、ボットは、ユーザーが入力を提供するために選択できるボタンを表示できます。 推奨されるアクションは、ユーザーがキーボードで応答を入力するのではなく、質問に回答したり、ボタンを選択したりできるようにすることで、ユーザー エクスペリエンスを向上させます。 ユーザーがボタンを選択すると、リッチ カードでは表示され、アクセス可能なままになりますが、推奨されるアクションにはアクセスできません。 これにより、ユーザーが会話内の古いボタンを選択できなくなります。

推奨されるアクションをメッセージに追加するには、アクティビティ オブジェクトの suggestedActions プロパティを設定して、ユーザーに表示するボタンカード表すアクション オブジェクトの一覧を指定します。 詳細については、sugestedActionsを参照してください。

推奨されるアクションの実装とエクスペリエンスの例を次に示します。

"suggestedActions": {
    "actions": [
      {
        "type": "imBack",
        "title": "Action 1",
        "value": "Action 1"
      },
      {
        "type": "imBack",
        "title": "Action 2",
        "value": "Action 2"
      }
    ],
    "to": [<list of recepientIds>]
  }

次に、推奨されるアクションの例を示します。

ボットが推奨するアクション

注:

  • SuggestedActions は、テキスト ベースのメッセージとアダプティブ カードの両方を持つ 1 対 1 のチャット ボットでのみサポートされます。
  • SuggestedActions は、任意の会話の種類の添付ファイルを含むチャット ボットではサポートされていません。
  • imBack は唯一サポートされているアクションの種類であり、Teams には最大 6 つの推奨アクションが表示されます。

Teams チャネル データでメッセージを送信する

channelData オブジェクトには Teams 固有の情報が含まれており、チーム ID とチャネル ID の決定的なソースです。 必要に応じて、これらの ID をキャッシュし、ローカル ストレージのキーとして使用できます。 SDK の TeamsActivityHandler は、 channelData オブジェクトから重要な情報を取得してアクセスできるようにします。 ただし、 turnContext オブジェクトから元のデータにいつでもアクセスできます。

channelData オブジェクトは、チャネルの外部で行われるので、個人的な会話のメッセージには含まれません。

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

  • eventType: Teams ボットで会話イベントが発生した場合にのみ、 Teams イベントの種類が渡されます。
  • tenant.id: すべてのコンテキストで渡されたテナント ID をMicrosoft Entraします。
  • team: 個人用チャットではなく、チャネル コンテキストでのみ渡されます。
  • 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"
    }
}

Teamsチャネルデータ

channelData オブジェクトには Teams 固有の情報が含まれており、チーム ID とチャネル ID の決定的なソースです。 必要に応じて、これらの ID をキャッシュし、ローカル ストレージのキーとして使用できます。 SDK の TeamsActivityHandler は、 channelData オブジェクトから重要な情報を取得してアクセスできるようにします。 ただし、 turnContext オブジェクトから元のデータにいつでもアクセスできます。

channelData オブジェクトは、チャネルの外部で行われるので、個人的な会話のメッセージには含まれません。

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

  • eventType: チャネル変更イベントの場合にのみ、Teams イベントの種類が渡されます。
  • tenant.id: すべてのコンテキストで渡されたテナント ID をMicrosoft Entraします。
  • team: 個人用チャットではなく、チャネル コンテキストでのみ渡されます。
    • id: チャネルの GUID。
    • name: (how-to/conversations/subscribe-to-conversation-events.md#team-renamed) の場合にのみ渡されたチームの名前。
  • channel: ボットがメンションされたとき、またはボットが追加されるチーム内のチャネルのイベントに対してのみ、チャネル コンテキストで渡されます。
    • id: チャネルの GUID。
    • name: チャネル 変更イベントの場合にのみ渡されるチャネル名。
  • channelData.teamsTeamId：廃止。 このプロパティは、下位互換性のためにのみ含まれています。
  • channelData.teamsChannelId：廃止。 このプロパティは、下位互換性のためにのみ含まれています。

channelData オブジェクトの例

次のコードは、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"
    }
}

ボットの会話型 API からの状態コード

Teams アプリでこれらのエラーを適切に処理してください。 次の表に、エラー コードと、エラーが生成される説明を示します。

状態コード エラー コードとメッセージ値 説明 再試行要求 開発者アクション
400 コード: Bad Argument
メッセージ: *シナリオ固有		 ボットによって提供される要求ペイロードが無効です。 詳細については、「エラー メッセージ」を参照してください。 いいえ エラーの要求ペイロードを再評価します。 詳細については、返されたエラー メッセージを確認してください。
401 コード: BotNotRegistered
メッセージ: このボットの登録が見つかりません。		 このボットの登録が見つかりませんでした。 いいえ ボット ID とパスワードを確認します。 ボット ID (Microsoft Entra ID) が Teams 開発者ポータルに登録されているか、Azure の Azure ボット チャネル登録を介して 、"Teams" チャネルが有効になっていることを確認します。
403 コード: BotDisabledByAdmin
メッセージ: テナント管理者がこのボットを無効にしました		 ユーザーとボット アプリ間の操作がブロック管理。 管理は、アプリ ポリシー内のユーザーのアプリを許可する必要があります。 詳細については、「 アプリ ポリシー」を参照してください。 いいえ ボットとの対話が、ボットがブロックされなくなったことを示す会話内のユーザーによって明示的に開始されるまで、会話への投稿を停止します。
403 コード: BotNotInConversationRoster
メッセージ: ボットは会話名簿の一部ではありません。		 ボットは会話の一部ではありません。 会話でアプリを再インストールする必要があります。 いいえ 別の会話要求を送信する前に、ボットが再度追加されたことを示す installationUpdate イベントを待ちます。
403 コード: ConversationBlockedByUser
メッセージ: ユーザーはボットとの会話をブロックしました。		 ユーザーは、モデレート設定を使用して、個人用チャットまたはチャネルでボットをブロックしました。 いいえ キャッシュから会話を削除します。 ボットとの対話が会話内のユーザーによって明示的に開始され、ボットがブロックされなくなったことを示すまで、会話への投稿を停止します。
403 コード: ForbiddenOperationException
メッセージ: ボットがユーザーの個人用スコープにインストールされていない		 プロアクティブ メッセージは、個人用スコープにインストールされていないボットによって送信されます。 いいえ 別の会話要求を送信する前に、個人用スコープでアプリをインストールします。
403 コード: InvalidBotApiHost
メッセージ: ボット API ホストが無効です。 GCC テナントの場合は、 https://smba.infra.gcc.teams.microsoft.comを呼び出します。		 GCC テナントに属する会話のパブリック API エンドポイントと呼ばれるボット。 いいえ 会話のサービス URL を更新して https://smba.infra.gcc.teams.microsoft.com し、要求を再試行します。
403 コード: NotEnoughPermissions
メッセージ: *シナリオ固有		 ボットには、要求されたアクションを実行するための必要なアクセス許可がありません。 いいえ エラー メッセージから必要なアクションを決定します。
404 コード: ActivityNotFoundInConversation
メッセージ: 会話が見つかりません。		 指定されたメッセージ ID が会話で見つかりませんでした。 メッセージが存在しないか、削除されます。 いいえ 送信されるメッセージ ID が予期される値であるかどうかを確認します。 キャッシュされた場合は、ID を削除します。
404 コード: ConversationNotFound
メッセージ: 会話が見つかりません。		 会話が見つからなかったのは、存在しないか削除されているためです。 いいえ 送信された会話 ID が予期される値であるかどうかを確認します。 キャッシュされた場合は、ID を削除します。
412 コード: PreconditionFailed
メッセージ: 前提条件に失敗しました。もう一度お試しください。		 同じ会話に対する複数の同時操作が原因で、いずれかの依存関係で前提条件が失敗しました。 はい 指数バックオフを使用して再試行します。
413 コード: MessageSizeTooBig
メッセージ: メッセージ サイズが大きすぎます。		 受信要求のサイズが大きすぎます。 詳細については、「 ボット メッセージの書式設定」を参照してください。 いいえ ペイロード サイズを小さくします。
429 コード: Throttled
メッセージ: 要求が多すぎます。 また、後で再試行するタイミングも返します。		 ボットから送信された要求が多すぎます。 詳細については、「 レート制限」を参照してください。 はい Retry-After ヘッダーを使用して、バックオフ時間を確認してください。
500 コード: ServiceError
メッセージ: *各種		 内部サーバー エラー。 いいえ 開発者コミュニティで問題を報告します。
502 コード: ServiceError
メッセージ: *各種		 サービス依存関係の問題。 はい 指数バックオフを使用して再試行します。 問題が解決しない場合は、 開発者コミュニティで問題を報告してください。
503 サービスは使用できません。 はい 指数バックオフを使用して再試行します。 問題が解決しない場合は、 開発者コミュニティで問題を報告してください。
504 ゲートウェイのタイムアウト。 はい 指数バックオフを使用して再試行します。 問題が解決しない場合は、 開発者コミュニティで問題を報告してください。

状態コードの再試行ガイダンス

各状態コードの一般的な再試行ガイダンスを次の表に示します。ボットは、指定されていない状態コードの再試行を避ける必要があります。

状態コード 再試行戦略
403 InvalidBotApiHostの GCC API https://smba.infra.gcc.teams.microsoft.comを呼び出して再試行します。
412 指数バックオフを使用して再試行します。
429 Retry-After ヘッダーを使用して再試行し、要求の間の待機時間 (使用可能な場合) を秒単位で判断します。 それ以外の場合は、可能であれば、スレッド ID で指数バックオフを使用して再試行してください。
502 指数バックオフを使用して再試行します。
503 指数バックオフを使用して再試行します。
504 指数バックオフを使用して再試行します。

ボットのヘッダーをリクエストする

ボットへの現在の送信要求には、ペイロード全体をアンパックせずにボットがトラフィックをルーティングするのに役立つ情報がヘッダーまたは URL に含まれません。 アクティビティは、https://<your_domain>/api/messages のような URL を使用してボットに送信されます。 ヘッダーに会話 ID とテナント ID を表示する要求を受信します。

要求ヘッダー フィールド

非同期フローと同期フローの両方で、ボットに送信されるすべての要求に 2 つの非標準の要求ヘッダー フィールドが追加されます。 次の表に、要求ヘッダー フィールドとその値を示します。

フィールド キー 値
x-ms-conversation-id 該当する場合は要求アクティビティに対応し、確認または検証された会話 ID。
x-ms-tenant-id 要求アクティビティの会話に対応するテナント ID。

テナントまたは会話 ID がアクティビティに存在しない場合、またはサービス側で検証されなかった場合、値は空です。

画像はヘッダー フィールドを示しています。

記載されているメッセージのみを受信する

ボットが @mentionedされているチャネルまたはチャット メッセージのみをボットが取得できるようにするには、メッセージをフィルター処理する必要があります。 次のコード スニペットを使用して、ボットが @mentionedされているメッセージのみを受信できるようにします。

    // When ChannelMessage.Read.Group or ChatMessage.Read.Chat RSC is in the app manifest, this method is called even when bot is not @mentioned.
    // This code snippet allows the bot to ignore all messages that do not @mention the bot.
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
            // Ignore the message if bot was not mentioned. 
            // Remove this if block to process all messages received by the bot.
            if (!turnContext.Activity.GetMentions().Any(mention => mention.Mentioned.Id.Equals(turnContext.Activity.Recipient.Id, StringComparison.OrdinalIgnoreCase)))
            {
                return;
            }
            // Sends an activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync(MessageFactory.Text("Using RSC the bot can receive messages across channels or chats in team without being @mentioned."));
    }

ボットですべてのメッセージを受信する場合は、 @mention メッセージをフィルター処理する必要はありません。

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

Teams 会話ボットを作成するには、 ステップバイステップ ガイドに従います。

次の手順

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

関連項目

Teams ボットの会話イベント