Bot Framework Connector サービスの API リファレンス

  • [アーティクル]

Note

REST API は SDK に相当するものではありません。 REST API は標準の REST 通信を可能にするために提供されていますが、Bot Framework との好ましい対話方法は SDK です。

Bot Framework 内で Bot Connector サービスを使用することにより、ボットは、Bot Framework Portal に構成されているチャネルでユーザーとメッセージを交換できます。 このサービスでは、HTTPS で業界標準の REST および JSON が使用されます。

基本 URI

ユーザーがボットにメッセージを送信すると、受信要求には、ボットが応答を送信するエンドポイントを指定する serviceUrl プロパティを持つ Activity オブジェクトが含まれています。 Bot Connector サービスにアクセスするには、serviceUrl 値を API 要求のベース URI として使用します。

チャンネルのサービス URL がまだない場合は、サービス URL として https://smba.trafficmanager.net/teams/ を使用します。 詳細については、「Teams で会話とプロアクティブなメッセージを作成する方法」を参照してください。

たとえば、ユーザーがボットにメッセージを送信したときに、ボットが次のアクティビティを受け取るとします。

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams/",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

ユーザーのメッセージ内の serviceUrl プロパティは、ボットがエンドポイント https://smba.trafficmanager.net/teams/ に応答を送信する必要があることを示します。 サービス URL は、この会話のコンテキストでボットが発行する後続の要求のベース URI になります。 ボットがユーザーに事前対応型のメッセージを送信する必要がある場合は、必ず serviceUrl の値を保存してください。

次の例は、ユーザーのメッセージに応答するためにボットが発行する要求を示しています。

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de...
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have several times available on Saturday!",
    "replyToId": "bf3cc9a2f5de..."
}

ヘッダー

要求ヘッダー

発行するすべての API 要求には、標準の HTTP 要求ヘッダーに加えて、ボットを認証するためのアクセス トークンを指定する Authorization ヘッダーが含まれている必要があります。 Authorization ヘッダーは次の形式を使用して指定します。

Authorization: Bearer ACCESS_TOKEN

ボットのアクセス トークンを取得する方法の詳細については、「Authenticate requests from your bot to the Bot Connector service」(ボットからの要求を Bot Connector サービスに認証する) を参照してください。

応答ヘッダー

標準の HTTP 応答ヘッダーに加えて、すべての応答には X-Correlating-OperationId ヘッダーが含まれます。 このヘッダーの値は、要求の詳細を含む Bot Framework のログ エントリに対応する ID です。 エラー応答を受け取るたびに、このヘッダーの値をキャプチャしてください。 自力で問題を解決できない場合は、問題を報告するときにサポート チームに提供する情報にこの値を含めてください。

HTTP 状態コード

各応答で返される HTTP 状態コード は、対応する要求の結果を示しています。

Note

次の表で、より一般的な HTTP 状態コードのいくつかについて説明します。 一部のエラーはチャンネルによって生成されます。 詳細については、チャンネルの開発者向けドキュメントを読む必要がある場合があります。

HTTP 状態コード 意味
200 要求は成功しました。
201 要求は成功しました。
202 要求の処理が受け入れられました。
204 要求は成功しましたが、返されたコンテンツはありませんでした。
400 要求の形式その他が正しくありませんでした。
401 ボットはまだ認証されていません。
403 要求された操作を実行する権限がボットに許可されていません。
404 要求されたリソースが見つかりませんでした。
405 このチャンネルは、要求された操作をサポートしていません。
500 内部サーバー エラーが発生しました。
503 サービスは一時的に利用できません。

エラー

4xx 範囲または 5xx 範囲の HTTP 状態コードを指定する応答では、エラーの情報を提供する ErrorResponse オブジェクトが応答の本文に含まれます。 4xx 範囲のエラー応答を受け取った場合、要求を再送信する前に、ErrorResponse オブジェクトを検査してエラーの原因を識別し、問題を解決してください。

会話操作

これらの操作を使用して、会話を作成し、メッセージ (アクティビティ) を送信し、会話の内容を管理します。

重要

すべてのチャンネルですべてのエンドポイントがサポートされているわけではありません。 ただし、すべてのチャンネルがアクティビティへの応答エンドポイントをサポートする必要があります。

たとえば、会話の取得エンドポイントをサポートしているのは、Direct Line と Web チャットのみです。

操作 説明
会話を作成する 新しい会話を作成します。
アクティビティを削除する 既存のアクティビティを削除します。
会話のメンバーを削除する 会話からメンバーを削除します。
アクティビティのメンバーを取得する 指定された会話内の指定されたアクティビティのメンバーを取得します。
会話のメンバーを取得する 会話のメンバーに関する詳細を取得します。
会話のメンバーを取得する 指定された会話のメンバーを取得します。
会話のページングされたメンバーを取得する 指定された会話のメンバーを一度に 1 ページずつ取得します。
会話を取得する ボットが参加した会話のリストを取得します。
アクティビティに返信する 指定されたアクティビティへの返信として、指定された会話にアクティビティ (メッセージ) を送信します。
会話履歴を送信する 過去のアクティビティのトランスクリプトを会話にアップロードします。
会話に送信する 指定された会話の最後にアクティビティ (メッセージ) を送信します。
アクティビティを更新する 既存のアクティビティを更新します。
添付ファイルをチャンネルにアップロードする 添付ファイルをチャネルの BLOB ストレージに直接アップロードします。

会話を作成する

新しい会話を作成します。

POST /v3/conversations
コンテンツ 説明
要求本文 ConversationParameters オブジェクト
返品 ConversationResourceResponse オブジェクト

アクティビティを削除する

一部のチャネルでは、既存のアクティビティを削除できます。 成功すると、この操作は指定されたアクティビティを指定された会話から削除します。

DELETE /v3/conversations/{conversationId}/activities/{activityId}
コンテンツ 説明
要求本文 該当なし
返品 操作の結果を示す HTTP 状態コード。 応答の本文では何も指定されません。

会話のメンバーを削除する

会話からメンバーを削除します。 そのメンバーが会話の最後のメンバーだった場合は、会話も削除されます。

DELETE /v3/conversations/{conversationId}/members/{memberId}
コンテンツ 説明
要求本文 該当なし
返品 操作の結果を示す HTTP 状態コード。 応答の本文では何も指定されません。

アクティビティのメンバーを取得する

指定された会話内の指定されたアクティビティのメンバーを取得します。

GET /v3/conversations/{conversationId}/activities/{activityId}/members
コンテンツ 説明
要求本文 該当なし
返品 ChannelAccount オブジェクトの配列

会話を取得する

ボットが参加した会話のリストを取得します。

GET /v3/conversations?continuationToken={continuationToken}
コンテンツ 説明
要求本文 該当なし
返品 ConversationsResult オブジェクト

会話のメンバーを取得する

特定の会話の特定のメンバーに関する詳細を取得します。

GET /v3/conversations/{conversationId}/members/{memberId}
コンテンツ 説明
要求本文 該当なし
返品 メンバーの ChannelAccount オブジェクト。

会話のメンバーを取得する

指定された会話のメンバーを取得します。

GET /v3/conversations/{conversationId}/members
コンテンツ 説明
要求本文 該当なし
返品 会話のメンバーの ChannelAccount オブジェクトの配列。

会話のページングされたメンバーを取得する

指定された会話のメンバーを一度に 1 ページずつ取得します。

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}
コンテンツ 説明
要求本文 該当なし
返品 PagedMembersResult オブジェクト

アクティビティに返信する

指定されたアクティビティへの返信として、指定された会話にアクティビティ (メッセージ) を送信します。 チャネルがサポートしている場合、アクティビティは別のアクティビティへの返信として追加されます。 ネストした応答をチャンネルがサポートしていない場合、この操作は会話に送信すると同様に動作します。

POST /v3/conversations/{conversationId}/activities/{activityId}
コンテンツ 説明
要求本文 Activity オブジェクト
返品 ResourceResponse オブジェクト

会話履歴を送信する

クライアントが過去のアクティビティのトランスクリプトをレンダリングできるように、それらを会話にアップロードします。

POST /v3/conversations/{conversationId}/activities/history
コンテンツ 説明
要求本文 Transcript オブジェクト。
返品 ResourceResponse オブジェクト。

会話に送信する

指定された会話にアクティビティ (メッセージ) を送信します。 アクティビティは、タイムスタンプまたはチャネルのセマンティクスに従って会話の最後に追加されます。 会話内の特定のメッセージに返信するには、代わりにアクティビティに返信するを使用します。

POST /v3/conversations/{conversationId}/activities
コンテンツ 説明
要求本文 Activity オブジェクト
返品 ResourceResponse オブジェクト

アクティビティを更新する

一部のチャネルでは、既存のアクティビティを編集してボットの会話の新しい状態を反映させることができます。 たとえば、いずれかのボタンをユーザーがクリックした後、会話内のメッセージからボタンを削除することができます。 成功すると、この操作は指定された会話内の指定されたアクティビティを更新します。

PUT /v3/conversations/{conversationId}/activities/{activityId}
コンテンツ 説明
要求本文 Activity オブジェクト
返品 ResourceResponse オブジェクト

添付ファイルをチャンネルにアップロードする

指定された会話の添付ファイルをチャネルの BLOB ストレージに直接アップロードします。 これにより、準拠したストアにデータを保存できます。

POST /v3/conversations/{conversationId}/attachments
コンテンツ 説明
要求本文 AttachmentData オブジェクト。
返品 ResourceResponse オブジェクト。 id プロパティは、添付ファイル情報を取得する操作と添付ファイルを取得する操作で使用できる添付ファイル ID を指定します。

添付ファイル操作

これらの操作を使用して、添付ファイルの情報とファイル自体のバイナリ データを取得します。

操作 説明
添付ファイル情報を取得する ファイル名、ファイルの種類、使用可能なビュー (例: オリジナルまたはサムネイル) など、指定された添付ファイルの情報を取得します。
添付ファイルを取得する 指定された添付ファイルの指定されたビューをバイナリ コンテンツとして取得します。

添付ファイル情報を取得する

ファイル名、ファイルの種類、使用可能なビュー (例: オリジナルまたはサムネイル) など、指定された添付ファイルの情報を取得します。

GET /v3/attachments/{attachmentId}
コンテンツ 説明
要求本文 該当なし
返品 AttachmentInfo オブジェクト

添付ファイルの取得

指定された添付ファイルの指定されたビューをバイナリ コンテンツとして取得します。

GET /v3/attachments/{attachmentId}/views/{viewId}
コンテンツ 説明
要求本文 該当なし
返品 指定された添付ファイルの指定されたビューを表すバイナリ コンテンツ

状態操作 (非推奨)

Microsoft Bot Framework State サービスは 2018 年 3 月 30 日時点で廃止されています。 以前は、Azure AI Bot Service または Bot Builder SDK で構築されたボットには、ボットの状態データを格納するために Microsoft によってホストされたこのサービスへの既定の接続がありました。 ボットは、独自の状態ストレージを使用するように更新する必要があります。

操作 説明
Set User Data チャネルの特定のユーザーの状態データを保存します。
Set Conversation Data チャネルの特定の会話の状態データを保存します。
Set Private Conversation Data チャネルの特定の会話のコンテキスト内で特定のユーザーの状態データを保存します。
Get User Data チャネルのすべての会話で以前に保存した特定のユーザーの状態データを取得します。
Get Conversation Data チャネルの特定の会話で以前に保存した状態データを取得します。
Get Private Conversation Data チャネルの特定の会話のコンテキスト内で以前に保存した特定のユーザーの状態データを取得します。
Delete State For User ユーザーのために以前に格納された状態データを削除します。

[スキーマ]

Bot Framework スキーマには、ボットがユーザーとの通信に使用できるオブジェクトとそれらのプロパティが定義されています。

オブジェクト 説明
Activity オブジェクト ボットとユーザーの間で交換されるメッセージを定義します。
AnimationCard オブジェクト アニメーション GIF または短いビデオを再生できるカードを定義します。
Attachment オブジェクト メッセージに含める追加の情報を定義します。 メディア ファイル (例: オーディオ、ビデオ、画像、ファイル) またはリッチ カードを添付ファイルにすることができます。
AttachmentData オブジェクト 添付ファイルのデータについて説明します。
AttachmentInfo オブジェクト 添付ファイルについて説明します。
AttachmentView オブジェクト 添付ファイルで使用できるビューを表すオブジェクトを定義します。
AudioCard オブジェクト オーディオ ファイルを再生できるカードを定義します。
CardAction オブジェクト 実行するアクションを定義します。
CardImage オブジェクト カードに表示する画像を定義します。
ChannelAccount オブジェクト チャネルのボットまたはユーザー アカウントを定義します。
ConversationAccount オブジェクト チャネルでの会話を定義します。
ConversationMembers オブジェクト 会話のメンバーを取得します。
ConversationParameters オブジェクト 新しい会話を作成するためのパラメーターを定義します
ConversationReference オブジェクト 会話内の特定のポイントを定義します。
ConversationResourceResponse オブジェクト 会話を作成するへの応答を定義します。
ConversationsResult オブジェクト 会話を取得するの呼び出し結果を定義します。
Entity オブジェクト エンティティ オブジェクトを定義します。
Error オブジェクト エラーを定義します。
ErrorResponse オブジェクト HTTP API 応答を定義します。
Fact オブジェクト ファクトを含むキーと値のペアを定義します。
GeoCoordinates オブジェクト World Geodetic System (WSG84) 座標を使用して地理的な場所を定義します。
HeroCard オブジェクト 大きい画像、タイトル、テキスト、アクションの各ボタンを持つカードを定義します。
InnerHttpError オブジェクト 内部 HTTP エラーを示すオブジェクト。
MediaEventValue オブジェクト メディア イベントの補助パラメーター。
MediaUrl オブジェクト メディア ファイルのソース URL を定義します。
Mention オブジェクト 会話でメンションされたユーザーまたはボットを定義します。
MessageReaction オブジェクト メッセージへの反応を定義します。
PagedMembersResult オブジェクト 会話のページングされたメンバーを取得するによって返されるメンバーのページ。
Place オブジェクト 会話でメンションされた場所を定義します。
ReceiptCard オブジェクト 購入のレシートを含むカードを定義します。
ReceiptItem オブジェクト レシート内の品目を定義します。
ResourceResponse オブジェクト リソースを定義します。
SemanticAction オブジェクト プログラムによるアクションへの参照を定義します。
SignInCard オブジェクト ユーザーがサービスにサインインできるようにするカードを定義します。
SuggestedActions オブジェクト ユーザーが選択できるオプションを定義します。
TextHighlight オブジェクト 別のフィールド内のコンテンツの部分文字列を参照します。
ThumbnailCard オブジェクト サムネイル画像、タイトル、テキスト、アクションの各ボタンを持つカードを定義します。
ThumbnailUrl オブジェクト 画像のソース URL を定義します。
Transcript オブジェクト 会話履歴を送信するを使用してアップロードされるアクティビティのコレクション。
VideoCard オブジェクト ビデオを再生できるカードを定義します。

Activity オブジェクト

ボットとユーザーの間で交換されるメッセージを定義します。

プロパティ タイプ 説明
action String 適用する、または適用されたアクション。 アクションのコンテキストを決定するには、type プロパティを使用します。 たとえば、type が contactRelationUpdate の場合、action プロパティの値は、ユーザーがボットを連絡先リストに追加した場合は add になり、ユーザーがボットを連絡先リストから削除した場合は remove になります。
attachmentLayout String メッセージに含まれるリッチ カード添付ファイルのレイアウト。 次の値のいずれか: carousel、list。 リッチ カード添付ファイルの詳細については、「メッセージへのリッチ カード添付ファイルの追加」を参照してください。
attachments Attachment[] メッセージに含める追加の情報を定義する Attachment オブジェクトの配列。 各添付ファイルは、ファイル (例: オーディオ、ビデオ、画像) またはリッチ カードのどちらかにすることができます。
callerId String ボットの呼び出し元を識別する IRI を含む文字列。 このフィールドは、ネットワーク経由で送信されるものではありません。その代わりに、呼び出し元 (トークンなど) の ID をアサートする暗号的に検証可能なデータに基づいて、ボットとクライアントによって設定されます。
channelData オブジェクト チャネル固有のコンテンツを格納するオブジェクト。 一部のチャンネルには、添付ファイル スキーマでは表現できない追加情報を必要とする機能があります。 そのような場合は、このプロパティを、チャネルのドキュメントで定義されているチャネル固有のコンテンツに設定します。 詳細については、「チャネル固有の機能の実装」を参照してください。
channelId String チャネルを一意に識別する ID。 チャネルによって設定されます。
code String 会話が終了した理由を示すコード。
conversation ConversationAccount アクティビティが属する会話を定義する ConversationAccount オブジェクト。
deliveryMode String アクティビティの受信者の代替配信パスに通知する配信ヒント。 値は、normal、notification のいずれかです。
entities object[] メッセージでメンションされたエンティティを表すオブジェクトの配列。 この配列内のオブジェクトは任意の Schema.org オブジェクトです。 たとえば、会話でメンションされた人物を識別する Mention オブジェクトや、会話でメンションされた場所を識別する Place オブジェクトを配列に含めることができます。
expiration String アクティビティを "期限切れ" と見なす時刻です。これは受信者に表示すべきではありません。
from ChannelAccount メッセージの送信者を指定する ChannelAccount オブジェクト。
historyDisclosed Boolean 履歴が公開されているかどうかを示すフラグ。 既定値は false です。
id String チャネルでのアクティビティを一意に識別する ID。
importance String アクティビティの重要度を定義します。 次の値のいずれか: low、normal、high。
inputHint String メッセージがクライアントに配信された後、ボットがユーザー入力を受け付けるか、期待するか、または無視するかを示す値。 次の値のいずれか: acceptingInput、expectingInput、ignoringInput。
label String アクティビティの説明ラベル。
listenFor String[] 音声および言語の認識システムで聞き取る必要がある語句と参照の一覧。
locale String メッセージ内のテキストの表示に使用する言語のロケールで、<language>-<country> の形式。 ボットがその言語の表示文字列を指定できるよう、チャネルはこのプロパティを使用してユーザーの言語を指示します。 既定値は en-US です。
localTimestamp String ローカル タイム ゾーンでメッセージが送信された日時を ISO-8601 形式で表したもの。
localTimezone String IANA タイム ゾーン データベース形式で表される、メッセージのローカル タイムゾーンの名前が格納されます。 例: America/Los_Angeles。
membersAdded ChannelAccount[] 会話に参加したユーザーのリストを表す ChannelAccount オブジェクトの配列。 アクティビティの type が "conversationUpdate" で、ユーザーが会話に参加した場合にのみ存在します。
membersRemoved ChannelAccount[] 会話から退出したユーザーのリストを表す ChannelAccount オブジェクトの配列。 アクティビティの type が "conversationUpdate" で、ユーザーが会話から退出した場合にのみ存在します。
name String 呼び出す操作の名前またはイベントの名前。
reactionsAdded MessageReaction[] 会話に追加された反応のコレクション。
reactionsRemoved MessageReaction[] 会話から削除された反応のコレクション。
recipient ChannelAccount メッセージの受信者を指定する ChannelAccount オブジェクト。
relatesTo ConversationReference 会話内の特定のポイントを定義する ConversationReference オブジェクト。
replyToId String このメッセージの返信先メッセージの ID。 ユーザーが送信したメッセージに返信するには、このプロパティをユーザーのメッセージの ID に設定します。 すべてのチャネルがスレッド返信をサポートするわけではありません。 このような場合、チャネルはこのプロパティを無視し、時間順のセマンティクス (タイムスタンプ) を使用してメッセージを会話に追加します。
semanticAction SemanticAction プログラムによるアクションへの参照を表す SemanticAction オブジェクト。
serviceUrl String チャネルのサービス エンドポイントを指定する URL。 チャネルによって設定されます。
speak String 音声対応チャネルでボットが話すテキスト。 音声、速度、音量、発音、ピッチなど、ボットの音声のさまざまな特性を制御するには、音声合成マークアップ言語 (SSML) 形式でこのプロパティを指定します。
suggestedActions SuggestedActions ユーザーが選択できるオプションを定義する SuggestedActions オブジェクト。
summary String メッセージに含まれる情報の要約。 たとえば、電子メール チャネルで送信されるメッセージの場合、このプロパティで電子メール メッセージの最初の 50 文字を指定できます。
text String ユーザーからボットに、またはボットからユーザーに送信されるメッセージのテキスト。 このプロパティの内容に課される制限については、チャネルのドキュメントを参照してください。
textFormat String メッセージの text の形式。 次の値のいずれか: markdown、plain、xml。 テキスト形式の詳細については、「Create messages」(メッセージの作成) を参照してください。
textHighlights TextHighlight[] アクティビティに replyToId 値が含まれている場合に、強調表示するテキスト フラグメントのコレクション。
timestamp String UTC タイム ゾーンでメッセージが送信された日時を ISO-8601 形式で表したもの。
topicName String アクティビティが属する会話のトピック。
type String 活動の種類です。 次のいずれかの値: message、contactRelationUpdate、conversationUpdate、typing、endOfConversation、event、invoke、deleteUserData、messageUpdate、messageDelete、installationUpdate、messageReaction、suggestion、trace、handoff。 アクティビティの種類の詳細については、「Activities overview」(アクティビティの概要) を参照してください。
value オブジェクト 拡張可能な値。
valueType String アクティビティの値オブジェクトの型。

スキーマの表に戻る

AnimationCard オブジェクト

アニメーション GIF または短いビデオを再生できるカードを定義します。

プロパティ タイプ 説明
aspect Boolean サムネイル/メディア プレースホルダーの縦横比。 使用できる値は "16:9" と "4:3" です。
autoloop Boolean 最後の項目が終了したときにアニメーション GIF のリストをリプレイするかどうかを示すフラグ。 アニメーションを自動的にリプレイするには、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
autostart Boolean カードが表示されたときにアニメーションを自動的に再生するかどうかを示すフラグ。 アニメーションを自動的に再生するには、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
buttons CardAction[] ユーザーが 1 つ以上のアクションを実行できるようにする CardAction オブジェクトの配列。 指定できるボタンの数はチャネルが決定します。
duration String メディア コンテンツの長さ (ISO 8601 の期間の形式)。
image ThumbnailUrl カードに表示する画像を指定する ThumbnailUrl オブジェクト。
media MediaUrl[] Mediaurl オブジェクトの配列。 このフィールドに複数の URL が含まれている場合、各 URL は同じコンテンツの代替形式です。
shareable Boolean アニメーションを他のユーザーと共有できるかどうかを示すフラグ。 アニメーションを共有できる場合、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
subtitle String カードのタイトルの下に表示するサブタイトル。
text String カードのタイトルまたはサブタイトルの下に表示する説明またはプロンプト。
title String カードのタイトル。
value オブジェクト このカードの補助パラメーター。

スキーマの表に戻る

Attachment オブジェクト

メッセージに含める追加の情報を定義します。 ファイル (画像、オーディオ、ビデオなど) またはリッチ カードを添付ファイルにすることができます。

プロパティ タイプ 説明
content オブジェクト 添付ファイルのコンテンツ。 添付ファイルがリッチ カードの場合、このプロパティをリッチ カード オブジェクトに設定します。 このプロパティと contentUrl プロパティは相互に排他的です。
contentType String 添付ファイル内のコンテンツのメディアの種類。 メディア ファイルの場合、このプロパティを image/png、audio/wav、video/mp4 などの既知のメディア タイプに設定します。 リッチ カードの場合、このプロパティを次のベンダー固有タイプのいずれかに設定します。
  • application/vnd.microsoft.card.adaptive: テキスト、音声、画像、ボタン、入力フィールドの任意の組み合わせを含めることができるリッチ カード。 content プロパティを AdaptiveCard オブジェクトに設定します。
  • application/vnd.microsoft.card.animation: アニメーションを再生するリッチ カード。 content プロパティを AnimationCard オブジェクトに設定します。
  • application/vnd.microsoft.card.audio: オーディオ ファイルを再生するリッチ カード。 content プロパティを AudioCard オブジェクトに設定します。
  • application/vnd.microsoft.card.hero: ヒーロー カード。 content プロパティを HeroCard オブジェクトに設定します。
  • application/vnd.microsoft.com.card.receipt: レシート カード。 content プロパティを ReceiptCard オブジェクトに設定します。
  • application/vnd.microsoft.com.card.signin: ユーザー サインイン カード。 content プロパティを SignInCard オブジェクトに設定します。
  • application/vnd.microsoft.card.thumbnail: サムネイル カード。 content プロパティを ThumbnailCard オブジェクトに設定します。
  • application/vnd.microsoft.card.video: ビデオを再生するリッチ カード。 content プロパティを VideoCard オブジェクトに設定します。
contentUrl String 添付ファイルのコンテンツの URL。 たとえば、添付ファイルが画像の場合、contentUrl を画像の場所を表す URL に設定できます。 サポートされているプロトコルは HTTP、HTTPS、File、および Data です。
name String 添付ファイルの名前。
thumbnailUrl String より小さな形式の代替 content または contentUrl の使用をチャネルがサポートしている場合にチャネルが使用できるサムネイル画像の URL。 たとえば、contentType を application/word に設定し、contentUrl を Word 文書の場所に設定する場合、文書を表すサムネイル画像を含めることができます。 チャネルは文書の代わりにサムネイル画像を表示できます。 ユーザーが画像をクリックすると、チャネルは文書を開きます。

スキーマの表に戻る

AttachmentData オブジェクト

添付ファイルのデータについて説明します。

プロパティ タイプ 説明
name String 添付ファイルの名前。
originalBase64 String 添付ファイルの内容。
thumbnailBase64 String 添付ファイルのサムネイル コンテンツ。
type String 添付ファイルのコンテンツの種類。

スキーマの表に戻る

AttachmentInfo オブジェクト

添付ファイルのメタデータ。

プロパティ タイプ 説明
name String 添付ファイルの名前。
type String 添付ファイルのコンテンツの種類。
views AttachmentView[] 添付ファイルの利用可能なビューを表す AttachmentView オブジェクトの配列。

スキーマの表に戻る

AttachmentView オブジェクト

添付ファイルで使用できるビューを表すオブジェクトを定義します。

プロパティ タイプ 説明
size 番号 ファイルのサイズ。
viewId String ビュー ID。

スキーマの表に戻る

AudioCard オブジェクト

オーディオ ファイルを再生できるカードを定義します。

プロパティ タイプ 説明
aspect String image プロパティで指定されたサムネイルの縦横比。 有効な値は 16:9 と 4:3 です。
autoloop Boolean 最後の項目が終了したときにオーディオ ファイルのリストをリプレイするかどうかを示すフラグ。 オーディオ ファイルを自動的にリプレイするには、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
autostart Boolean カードが表示されたときにオーディオを自動的に再生するかどうかを示すフラグ。 オーディオを自動的に再生するには、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
buttons CardAction[] ユーザーが 1 つ以上のアクションを実行できるようにする CardAction オブジェクトの配列。 指定できるボタンの数はチャネルが決定します。
duration String メディア コンテンツの長さ (ISO 8601 の期間の形式)。
image ThumbnailUrl カードに表示する画像を指定する ThumbnailUrl オブジェクト。
media MediaUrl[] Mediaurl オブジェクトの配列。 このフィールドに複数の URL が含まれている場合、各 URL は同じコンテンツの代替形式です。
shareable Boolean オーディオ ファイルを他のユーザーと共有できるかどうかを示すフラグ。 オーディオを共有できる場合、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
subtitle String カードのタイトルの下に表示するサブタイトル。
text String カードのタイトルまたはサブタイトルの下に表示する説明またはプロンプト。
title String カードのタイトル。
value オブジェクト このカードの補助パラメーター。

スキーマの表に戻る

CardAction オブジェクト

ボタンを使用してクリック可能なアクションを定義します。

プロパティ タイプ 説明
channelData String このアクションに関連付けられているチャネル固有のデータ。
displayText String ボタンがクリックされた場合にチャット フィードに表示するテキスト。
image String テキスト ラベルの横にあるボタンに表示される画像の URL。
text String アクションのテキスト。
title String ボタンに表示されるテキスト説明です。
type String 実行するアクションの種類。 有効な値の一覧については、「メッセージへのリッチ カード添付ファイルの追加」を参照してください。
value オブジェクト アクションの補助パラメーター。 このプロパティの動作は、アクションの type によって異なります。 詳細については、「メッセージへのリッチ カード添付ファイルの追加」を参照してください。

スキーマの表に戻る

CardImage オブジェクト

カードに表示する画像を定義します。

プロパティ タイプ 説明
alt String 画像の説明。 アクセシビリティをサポートするには、説明を含める必要があります。
tap CardAction ユーザーが画像をタップまたはクリックした場合に実行するアクションを指定する CardAction オブジェクト。
url String 画像または画像の base64 バイナリのソース URL (例: data:image/png;base64,iVBORw0KGgo...)。

スキーマの表に戻る

ChannelAccount オブジェクト

チャネルのボットまたはユーザー アカウントを定義します。

プロパティ タイプ 説明
aadObjectId String Microsoft Entra ID 内のこのアカウントのオブジェクト ID。
id String このチャネルのユーザーまたはボットの一意の ID。
name String ボットまたはユーザーの表示用の名前。
role String このアカウントの背後にあるエンティティのロール。 user または bot のいずれかです。

スキーマの表に戻る

ConversationAccount オブジェクト

チャネルでの会話を定義します。

プロパティ タイプ 説明
aadObjectId String Microsoft Entra ID 内のこのアカウントのオブジェクト ID。
conversationType String 会話の種類 (グループ、個人など) を区別するチャンネルでの会話の種類を示します。
id String 会話を識別する ID。 ID はチャネルごとに一意です。 チャネルが会話を開始する場合、チャネルがこの ID を設定します。それ以外の場合、このプロパティはボットによって、ボットが会話を開始するときに応答で取得する ID に設定されます (「会話を作成する」を参照)。
isGroup Boolean アクティビティが生成された時点で会話に 2 人より多い参加者が含まれているかどうかを示すフラグ。 これがグループ会話の場合は true に設定します。それ以外の場合、false に設定します。 既定値は false です。
name String 会話を識別するために使用できる表示名。
role String このアカウントの背後にあるエンティティのロール。 user または bot のいずれかです。
tenantId String この会話のテナント ID。

スキーマの表に戻る

ConversationMembers オブジェクト

会話のメンバーを取得します。

プロパティ タイプ 説明
id String 会話 ID。
members ChannelAccount[] この会話のメンバーの一覧。

スキーマの表に戻る

ConversationParameters オブジェクト

新しい会話を作成するためのパラメーターを定義します。

プロパティ タイプ 説明
activity アクティビティ 会話の作成時にその会話に送信される初期メッセージ。
bot ChannelAccount ボットにメッセージをルーティングするために必要なチャネル アカウント情報。
channelData オブジェクト 会話を作成するためのチャネル固有のペイロード。
isGroup Boolean これがグループ会話かどうかを示します。
members ChannelAccount[] 各ユーザーにメッセージをルーティングするために必要なチャネル アカウント情報。
tenantId String 会話が作成されるテナントの ID。
topicName String 会話のトピック。 このプロパティは、チャネルがサポートしている場合にのみ使用されます。

スキーマの表に戻る

ConversationReference オブジェクト

会話内の特定のポイントを定義します。

プロパティ タイプ 説明
activityId String このオブジェクトが参照するアクティビティを一意に識別する ID。
bot ChannelAccount このオブジェクトが参照する会話でボットを識別する ChannelAccount オブジェクト。
channelId String このオブジェクトが参照する会話でチャネルを一意に識別する ID。
conversation ConversationAccount このオブジェクトが参照する会話を定義する ConversationAccount オブジェクト。
serviceUrl String このオブジェクトが参照する会話でチャネルのサービス エンドポイントを指定する URL。
ユーザー ChannelAccount このオブジェクトが参照する会話でユーザーを識別する ChannelAccount オブジェクト。

スキーマの表に戻る

ConversationResourceResponse オブジェクト

会話を作成するへの応答を定義します。

プロパティ タイプ 説明
activityId String アクティビティの ID (送信された場合)。
id String リソースの ID。
serviceUrl String 会話に関する操作を実行できるサービス エンドポイント。

スキーマの表に戻る

ConversationsResult オブジェクト

会話を取得するの結果を定義します。

プロパティ タイプ 説明
会話 ConversationMembers[] 各会話のメンバー。
continuationToken String その後の会話を取得するの呼び出しで使用できる継続トークン。

スキーマの表に戻る

Entity オブジェクト

アクティビティに関連するメタデータ オブジェクト。

プロパティ タイプ 説明
type String このエンティティの型 (RFC 3987 IRI)。

スキーマの表に戻る

Error オブジェクト

エラー情報を示すオブジェクト。

プロパティ タイプ 説明
code String エラー コードです。
innerHttpError InnerHttpError 内部 HTTP エラーを示すオブジェクト。
message String エラーの説明。

スキーマの表に戻る

ErrorResponse オブジェクト

HTTP API 応答を定義します。

プロパティ タイプ 説明
error エラー エラーに関する情報を含む Error オブジェクト。

スキーマの表に戻る

Fact オブジェクト

ファクトを含むキーと値のペアを定義します。

プロパティ タイプ 説明
キー String ファクトの名前。 例: Check-in。 キーは、ファクトの値を表示するときにラベルとして使用されます。
value String ファクトの値。 例: 10 October 2016。

スキーマの表に戻る

GeoCoordinates オブジェクト

World Geodetic System (WSG84) 座標を使用して地理的な場所を定義します。

プロパティ タイプ 説明
elevation 番号 場所の標高。
latitude 番号 場所の緯度。
longitude 番号 場所の経度。
name String 場所の名前。
type String このオブジェクトの種類。 常に GeoCoordinates に設定します。

スキーマの表に戻る

HeroCard オブジェクト

大きい画像、タイトル、テキスト、アクションの各ボタンを持つカードを定義します。

プロパティ タイプ 説明
buttons CardAction[] ユーザーが 1 つ以上のアクションを実行できるようにする CardAction オブジェクトの配列。 指定できるボタンの数はチャネルが決定します。
images CardImage[] カードに表示する画像を指定する CardImage オブジェクトの配列。 ヒーロー カードには 1 つの画像のみが含まれます。
subtitle String カードのタイトルの下に表示するサブタイトル。
tap CardAction ユーザーがカードをタップまたはクリックした場合に実行するアクションを指定する CardAction オブジェクト。 いずれかのボタンと同じアクションまたは別のアクションを指定できます。
text String カードのタイトルまたはサブタイトルの下に表示する説明またはプロンプト。
title String カードのタイトル。

スキーマの表に戻る

InnerHttpError オブジェクト

内部 HTTP エラーを示すオブジェクト。

プロパティ タイプ 説明
statusCode 数 失敗した要求の HTTP 状態コード。
body オブジェクト 失敗した要求の本文。

スキーマの表に戻る

MediaEventValue オブジェクト

メディア イベントの補助パラメーター。

プロパティ タイプ 説明
cardValue オブジェクト このイベントを発生させたメディア カードの value フィールドに指定されたコールバック パラメーター。

スキーマの表に戻る

MediaUrl オブジェクト

メディア ファイルのソース URL を定義します。

プロパティ タイプ 説明
profile String メディアのコンテンツを説明するヒント。
url String メディア ファイルのソース URL。

スキーマの表に戻る

Mention オブジェクト

会話でメンションされたユーザーまたはボットを定義します。

プロパティ タイプ 説明
mentioned ChannelAccount メンションされたユーザーまたはボットを指定する ChannelAccount オブジェクト。 Slack などの一部のチャンネルでは会話ごとに名前を割り当てるため、(メッセージの recipient プロパティで) メンションされたボットの名前は、ボットの登録時に指定したハンドルとは異なる可能性があることに注意してください。 ただし、両方のアカウント ID は同じになります。
text String 会話でメンションされたユーザーまたはボット。 たとえば、メッセージが「@ColorBot pick me a new color」の場合、このプロパティは @ColorBot に設定されます。 すべてのチャネルがこのプロパティを設定するわけではありません。
type String このオブジェクトの種類。 常に Mention に設定します。

スキーマの表に戻る

MessageReaction オブジェクト

メッセージへの反応を定義します。

プロパティ タイプ 説明
type String 反応の種類。 like または plusOne のいずれかです。

スキーマの表に戻る

PagedMembersResult オブジェクト

会話のページングされたメンバーを取得するによって返されるメンバーのページ。

プロパティ タイプ 説明
continuationToken String 後続の会話のページングされたメンバーを取得するの呼び出しで使用できる継続トークン。
members ChannelAccount[] 会話のメンバーの配列です。

スキーマの表に戻る

Place オブジェクト

会話でメンションされた場所を定義します。

プロパティ タイプ 説明
address オブジェクト 場所の所在地。 このプロパティは string、または PostalAddress 型の複合オブジェクトです。
geo GeoCoordinates 場所の地理的座標を指定する GeoCoordinates オブジェクト。
hasMap オブジェクト 場所の地図。 このプロパティは string (URL)、または Map 型の複合オブジェクトです。
name String 場所の名前。
type String このオブジェクトの種類。 常に Place に設定します。

スキーマの表に戻る

ReceiptCard オブジェクト

購入のレシートを含むカードを定義します。

プロパティ タイプ 説明
buttons CardAction[] ユーザーが 1 つ以上のアクションを実行できるようにする CardAction オブジェクトの配列。 指定できるボタンの数はチャネルが決定します。
facts Fact[] 購入に関する情報を指定する Fact オブジェクトの配列。 たとえば、ホテル宿泊レシートのファクトのリストには、チェックイン日とチェックアウト日が含まれる場合があります。 指定できるファクトの数はチャネルが決定します。
品目 ReceiptItem[] 購入したアイテムを指定する ReceiptItem オブジェクトの配列
tap CardAction ユーザーがカードをタップまたはクリックした場合に実行するアクションを指定する CardAction オブジェクト。 いずれかのボタンと同じアクションまたは別のアクションを指定できます。
tax String 購入に適用される税額を指定する通貨形式の文字列。
title String レシートの上部に表示されるタイトル。
total String 適用されるすべての税金を含めた合計購入価格を指定する通貨形式の文字列。
vat String 購入価格に適用される付加価値税 (VAT) の額を指定する通貨形式の文字列。

スキーマの表に戻る

ReceiptItem オブジェクト

レシート内の品目を定義します。

プロパティ タイプ 説明
image CardImage 品目の隣に表示するサムネイル画像を指定する CardImage オブジェクト。
Price String すべての購入単位の合計価格を指定する通貨形式の文字列。
quantity String 購入単位数を指定する数値の文字列。
subtitle String 品目のタイトルの下に表示されるサブタイトル。
tap CardAction ユーザーが品目をタップまたはクリックした場合に実行するアクションを指定する CardAction オブジェクト。
text String 品目の説明。
title String 品目のタイトル。

スキーマの表に戻る

ResourceResponse オブジェクト

リソース ID を含む応答を定義します。

プロパティ タイプ 説明
id String リソースを一意に識別する ID。

スキーマの表に戻る

SemanticAction オブジェクト

プログラムによるアクションへの参照を定義します。

プロパティ タイプ 説明
entities オブジェクト 各プロパティの値が Entity オブジェクトであるオブジェクト。
id String このアクションの ID。
状態 String このアクションの状態。 使用できる値: start、continue、done。

スキーマの表に戻る

SignInCard オブジェクト

ユーザーがサービスにサインインできるようにするカードを定義します。

プロパティ タイプ 説明
buttons CardAction[] ユーザーがサービスにサインインできるようにする CardAction オブジェクトの配列。 指定できるボタンの数はチャネルが決定します。
text String サインイン カードに含める説明またはプロンプト。

スキーマの表に戻る

SuggestedActions オブジェクト

ユーザーが選択できるオプションを定義します。

プロパティ タイプ 説明
actions CardAction[] 推奨されるアクションを定義する CardAction オブジェクトの配列。
to String[] 推奨されるアクションの表示先である受信者の ID を含む文字列の配列。

スキーマの表に戻る

TextHighlight オブジェクト

別のフィールド内のコンテンツの部分文字列を参照します。

プロパティ タイプ 説明
occurrence 番号 参照されるテキスト内でのテキスト フィールドの出現数 (複数存在する場合)。
text String 強調表示するテキストのスニペットを定義します。

スキーマの表に戻る

ThumbnailCard オブジェクト

サムネイル画像、タイトル、テキスト、アクションの各ボタンを持つカードを定義します。

プロパティ タイプ 説明
buttons CardAction[] ユーザーが 1 つ以上のアクションを実行できるようにする CardAction オブジェクトの配列。 指定できるボタンの数はチャネルが決定します。
images CardImage[] カードに表示するサムネイル画像を指定する CardImage オブジェクトの配列。 指定できるサムネイル画像の数はチャネルが決定します。
subtitle String カードのタイトルの下に表示するサブタイトル。
tap CardAction ユーザーがカードをタップまたはクリックした場合に実行するアクションを指定する CardAction オブジェクト。 いずれかのボタンと同じアクションまたは別のアクションを指定できます。
text String カードのタイトルまたはサブタイトルの下に表示する説明またはプロンプト。
title String カードのタイトル。

スキーマの表に戻る

ThumbnailUrl オブジェクト

画像のソース URL を定義します。

プロパティ タイプ 説明
alt String 画像の説明。 アクセシビリティをサポートするには、説明を含める必要があります。
url String 画像または画像の base64 バイナリのソース URL (例: data:image/png;base64,iVBORw0KGgo...)。

スキーマの表に戻る

Transcript オブジェクト

会話履歴を送信するを使用してアップロードされるアクティビティのコレクション。

プロパティ タイプ 説明
activities 配列 Activity オブジェクトの配列です。 それぞれが一意の ID とタイムスタンプを持つ必要があります。

スキーマの表に戻る

VideoCard オブジェクト

ビデオを再生できるカードを定義します。

プロパティ タイプ 説明
aspect String ビデオの縦横比。 16:9 または 4:3 のいずれかです。
autoloop Boolean 最後の項目が終了したときにビデオのリストをリプレイするかどうかを示すフラグ。 ビデオを自動的にリプレイするには、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
autostart Boolean カードが表示されたときにビデオを自動的に再生するかどうかを示すフラグ。 ビデオを自動的に再生するには、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
buttons CardAction[] ユーザーが 1 つ以上のアクションを実行できるようにする CardAction オブジェクトの配列。 指定できるボタンの数はチャネルが決定します。
duration String メディア コンテンツの長さ (ISO 8601 の期間の形式)。
image ThumbnailUrl カードに表示する画像を指定する ThumbnailUrl オブジェクト。
media MediaUrl[] MediaUrl の配列。 このフィールドに複数の URL が含まれている場合、各 URL は同じコンテンツの代替形式です。
shareable Boolean ビデオを他のユーザーと共有できるかどうかを示すフラグ。 ビデオを共有できる場合、このプロパティを true に設定します。それ以外の場合、false に設定します。 既定値は true です。
subtitle String カードのタイトルの下に表示するサブタイトル。
text String カードのタイトルまたはサブタイトルの下に表示する説明またはプロンプト。
title String カードのタイトル。
value オブジェクト このカードの補助パラメーター

スキーマの表に戻る