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 などの既知のメディア タイプに設定します。 リッチ カードの場合、このプロパティを次のベンダー固有タイプのいずれかに設定します。
|
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 | オブジェクト | このカードの補助パラメーター |