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

Note

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

Bot Framework 内では、Bot Connector サービスを使用して、Bot Framework ポータルで構成されているチャネル上のユーザーとメッセージを交換できます。 このサービスでは、HTTPS 経由で業界標準の REST と JSON が使用されます。

基底URI

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

チャネルのサービス URL がまだない場合は、 https://smba.trafficmanager.net/teams/ をサービス URL として使用します。 詳細については、 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..."
}

ヘッダー

リクエストヘッダー

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

Authorization: Bearer ACCESS_TOKEN

ボットのアクセス トークンを取得する方法の詳細については、ボット から Bot Connector サービスへの要求の認証に関するページを参照してください。

応答ヘッダー

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

HTTP 状態コード

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

Note

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

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

Errors

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

会話操作

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

Important

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

たとえば、get conversations エンドポイントをサポートするのは、Direct LineとWeb チャットだけです。

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

会話を作成する

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

POST /v3/conversations
Content Description
リクエスト本文 ConversationParameters オブジェクト
返品 ConversationResourceResponse オブジェクト

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

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

DELETE /v3/conversations/{conversationId}/activities/{activityId}
Content Description
リクエスト本文 n/a
返品 操作の結果を示す HTTP 状態コード。 応答の本文には何も指定されません。

会話メンバーを削除する

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

DELETE /v3/conversations/{conversationId}/members/{memberId}
Content Description
リクエスト本文 n/a
返品 操作の結果を示す HTTP 状態コード。 応答の本文には何も指定されません。

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

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

GET /v3/conversations/{conversationId}/activities/{activityId}/members
Content Description
リクエスト本文 n/a
返品 ChannelAccount オブジェクトの配列

会話を取得する

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

GET /v3/conversations?continuationToken={continuationToken}
Content Description
リクエスト本文 n/a
返品 ConversationsResult オブジェクト

会話メンバーを取得する

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

GET /v3/conversations/{conversationId}/members/{memberId}
Content Description
リクエスト本文 n/a
返品 メンバーの ChannelAccount オブジェクト。

会話メンバーを取得する

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

GET /v3/conversations/{conversationId}/members
Content Description
リクエスト本文 n/a
返品 会話のメンバーの ChannelAccount オブジェクトの配列。

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

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

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}
Content Description
リクエスト本文 n/a
返品 PagedMembersResult オブジェクト

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

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

POST /v3/conversations/{conversationId}/activities/{activityId}
Content Description
リクエスト本文 Activity オブジェクト
返品 ResourceResponse オブジェクト

会話履歴を送信する

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

POST /v3/conversations/{conversationId}/activities/history
Content Description
リクエスト本文 トランスクリプト オブジェクト。
返品 ResourceResponse オブジェクト。

会話に送信する

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

POST /v3/conversations/{conversationId}/activities
Content Description
リクエスト本文 Activity オブジェクト
返品 ResourceResponse オブジェクト

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

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

PUT /v3/conversations/{conversationId}/activities/{activityId}
Content Description
リクエスト本文 Activity オブジェクト
返品 ResourceResponse オブジェクト

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

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

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

添付ファイルの操作

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

Operation Description
添付ファイル情報を取得する ファイル名、ファイルの種類、使用可能なビュー (元のビューやサムネイルなど) など、指定された添付ファイルに関する情報を取得します。
添付ファイルを取得する 指定した添付ファイルの指定したビューをバイナリ コンテンツとして取得します。

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

ファイル名、種類、使用可能なビュー (元のビューやサムネイルなど) など、指定した添付ファイルに関する情報を取得します。

GET /v3/attachments/{attachmentId}
Content Description
リクエスト本文 n/a
返品 AttachmentInfo オブジェクト

添付ファイルを取得する

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

GET /v3/attachments/{attachmentId}/views/{viewId}
Content Description
リクエスト本文 n/a
返品 指定した添付ファイルの指定したビューを表すバイナリ コンテンツ

状態操作 (非推奨)

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

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

Schema

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

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

Activity オブジェクト

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

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

スキーマ テーブルに戻る

AnimationCard オブジェクト

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

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

スキーマ テーブルに戻る

Attachment オブジェクト

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

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

スキーマ テーブルに戻る

AttachmentData オブジェクト

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

財産 タイプ Description
name String 添付ファイルの名前。
originalBase64 String 添付ファイルのコンテンツ。
thumbnailBase64 String 添付ファイルのサムネイル コンテンツ。
type String 添付ファイルのコンテンツ タイプ。

スキーマ テーブルに戻る

AttachmentInfo オブジェクト

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

財産 タイプ Description
name String 添付ファイルの名前。
type String 添付ファイルのコンテンツ タイプ。
views AttachmentView[] 添付ファイルで使用できるビューを表す AttachmentView オブジェクトの配列。

スキーマ テーブルに戻る

AttachmentView オブジェクト

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

財産 タイプ Description
size Number ファイルのサイズ。
viewId String ビュー ID。

スキーマ テーブルに戻る

AudioCard オブジェクト

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

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

スキーマ テーブルに戻る

CardAction オブジェクト

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

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

スキーマ テーブルに戻る

CardImage オブジェクト

カードに表示するイメージを定義します。

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

スキーマ テーブルに戻る

ChannelAccount オブジェクト

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

財産 タイプ Description
aadObjectId String Microsoft Entra ID内のこのアカウントのオブジェクト ID。
id String このチャネルのユーザーまたはボットの一意の ID。
name String ボットまたはユーザーの表示フレンドリ名。
役割 String アカウントの背後にあるエンティティのロール。 ユーザーまたはボット。

スキーマ テーブルに戻る

ConversationAccount オブジェクト

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

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

スキーマ テーブルに戻る

ConversationMembers オブジェクト

会話のメンバーを定義します。

財産 タイプ Description
id String 会話 ID。
members ChannelAccount[] この会話のメンバーの一覧。

スキーマ テーブルに戻る

ConversationParameters オブジェクト

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

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

スキーマ テーブルに戻る

ConversationReference オブジェクト

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

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

スキーマ テーブルに戻る

ConversationResourceResponse オブジェクト

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

財産 タイプ Description
activityId String 送信された場合は、アクティビティの ID。
id String リソースの ID。
サービスURL String 会話に関する操作が行われるサービスエンドポイント。

スキーマ テーブルに戻る

ConversationsResult オブジェクト

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

財産 タイプ Description
conversations ConversationMembers[] 各会話のメンバー。
continuationToken String 後続の Get Conversations の呼び出しで使用できる継続トークン。

スキーマ テーブルに戻る

Entity オブジェクト

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

財産 タイプ Description
type String このエンティティの型 (RFC 3987 IRI)。

スキーマ テーブルに戻る

エラー オブジェクト

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

財産 タイプ Description
code String エラー コード。
innerHttpError InnerHttpError 内部 HTTP エラーを表すオブジェクト。
メッセージ String エラーの説明。

スキーマ テーブルに戻る

ErrorResponse オブジェクト

HTTP API 応答を定義します。

財産 タイプ Description
error エラー エラーに関する情報を含む Error オブジェクト。

スキーマ テーブルに戻る

Fact オブジェクト

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

財産 タイプ Description
キー String ファクトの名前。 たとえば、 チェックインです。 キーは、ファクトの値を表示するときにラベルとして使用されます。
価値 String ファクトの値。 たとえば、 2016 年 10 月 10 日などです。

スキーマ テーブルに戻る

GeoCoordinates オブジェクト

世界測地システム (WSG84) 座標を使用して地理的な場所を定義します。

財産 タイプ Description
昇格 Number 場所の昇格。
latitude Number 場所の緯度。
longitude Number 場所の経度。
name String 場所の名前。
type String このオブジェクトの型。 常に GeoCoordinates に設定します。

スキーマ テーブルに戻る

HeroCard オブジェクト

大きな画像、タイトル、テキスト、アクション ボタンを含むカードを定義します。

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

スキーマ テーブルに戻る

InnerHttpError オブジェクト

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

財産 タイプ Description
statusCode Number 失敗した要求からの HTTP 状態コード。
body Object 失敗した要求の本文。

スキーマ テーブルに戻る

MediaEventValue オブジェクト

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

財産 タイプ Description
cardValue Object このイベントを発生させたメディア カードの 値 フィールドに指定されたコールバック パラメーター。

スキーマ テーブルに戻る

MediaUrl オブジェクト

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

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

スキーマ テーブルに戻る

メンション オブジェクト

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

財産 タイプ Description
メンション ChannelAccount メンションされたユーザーまたはボットを指定する ChannelAccount オブジェクト。 Slack などの一部のチャネルでは、会話ごとに名前が割り当てられるため、ボットのメンションされた名前 (メッセージの 受信者 プロパティ内) が、ボットの 登録時に指定した ハンドルと異なる場合があります。 ただし、両方のアカウント ID は同じになります。
text String 会話に記載されているユーザーまたはボット。 たとえば、メッセージが "新しい色を選択@ColorBot" の場合、このプロパティは @ColorBot に設定されます。 すべてのチャネルでこのプロパティが設定されるわけではありません。
type String このオブジェクトの型。 常に メンションに設定します。

スキーマ テーブルに戻る

MessageReaction オブジェクト

メッセージに対する反応を定義します。

財産 タイプ Description
type String 反応の種類。 like または plusOne のいずれか。

スキーマ テーブルに戻る

PagedMembersResult オブジェクト

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

財産 タイプ Description
continuationToken String 後続の Get Conversation Paged メンバーの呼び出しで使用できる継続トークン。
members ChannelAccount[] 会話メンバーの配列。

スキーマ テーブルに戻る

オブジェクトを配置する

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

財産 タイプ Description
address Object 場所の住所。 このプロパティには、 文字列 または PostalAddress 型の複合オブジェクトを指定できます。
geo GeoCoordinates 場所の地理的座標を指定する GeoCoordinates オブジェクト。
hasMap Object 場所にマップします。 このプロパティには、 文字列 (URL) または Map 型の複合オブジェクトを指定できます。
name String 場所の名前。
type String このオブジェクトの型。 常に [配置] に設定します。

スキーマ テーブルに戻る

ReceiptCard オブジェクト

購入の領収書を含むカードを定義します。

財産 タイプ Description
buttons CardAction[] ユーザーが 1 つ以上のアクションを実行できるようにする CardAction オブジェクトの配列。 チャネルによって、指定できるボタンの数が決まります。
事実 Fact[] 購入に関する情報を指定する Fact オブジェクトの配列。 たとえば、ホテル滞在の領収書のファクトの一覧には、チェックイン日とチェックアウト日が含まれる場合があります。 チャネルによって、指定できるファクトの数が決まります。
項目 ReceiptItem[] 購入したアイテムを指定する ReceiptItem オブジェクトの配列
タップ CardAction ユーザーがカードをタップまたはクリックした場合に実行するアクションを指定する CardAction オブジェクト。 これは、いずれかのボタンまたは別のアクションと同じアクションにすることができます。
税 String 購入に適用される税額を指定する通貨形式の文字列。
タイトル String レシートの上部に表示されるタイトル。
合計 String 適用されるすべての税金を含む、合計購入価格を指定する通貨形式の文字列。
vat String 購入価格に適用される VAT (VAT) の金額を指定する通貨形式の文字列。

スキーマ テーブルに戻る

ReceiptItem オブジェクト

レシート内の明細を定義します。

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

スキーマ テーブルに戻る

ResourceResponse オブジェクト

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

財産 タイプ Description
id String リソースを一意に識別する ID。

スキーマ テーブルに戻る

SemanticAction オブジェクト

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

財産 タイプ Description
entities Object 各プロパティの値が Entity オブジェクトであるオブジェクト。
id String このアクションの ID。
状態 String このアクションの状態。 使用できる値: 開始、 続行、 完了。

スキーマ テーブルに戻る

SignInCard オブジェクト

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

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

スキーマ テーブルに戻る

SuggestedActions オブジェクト

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

財産 タイプ Description
アクション CardAction[] 推奨されるアクションを定義する CardAction オブジェクトの配列。
to 文字列[] 推奨されるアクションを表示する受信者の ID を含む文字列の配列。

スキーマ テーブルに戻る

TextHighlight オブジェクト

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

財産 タイプ Description
occurrence Number 複数のテキストが存在する場合は、参照先のテキスト内でテキスト フィールドが出現します。
text String 強調表示するテキストのスニペットを定義します。

スキーマ テーブルに戻る

ThumbnailCard オブジェクト

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

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

スキーマ テーブルに戻る

ThumbnailUrl オブジェクト

イメージのソースへの URL を定義します。

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

スキーマ テーブルに戻る

Transcript オブジェクト

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

財産 タイプ Description
activities アレイ Activity オブジェクトの配列。 それぞれに一意の ID とタイムスタンプが必要です。

スキーマ テーブルに戻る

VideoCard オブジェクト

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

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

スキーマ テーブルに戻る

  • Last updated on