Bot Framework 連線or 服務的 API 參考

  • 發行項

注意

REST API 不等於 SDK。 提供 REST API 以允許標準 REST 通訊，但與 Bot Framework 互動的慣用方法是 SDK。

在 Bot Framework 中，Bot 連線or 服務可讓您的 Bot 在 Bot Framework 入口網站中設定的通道上，與使用者交換訊息。 此服務會透過 HTTPS 使用業界標準的 REST 和 JSON。

基底 URI

當使用者將訊息傳送至 Bot 時，傳入要求會 包含 Activity 物件，其中包含 serviceUrl 屬性，指定 Bot 應該傳送其回應的端點。 若要存取 Bot 連線or 服務，請使用 serviceUrl 值作為 API 要求的基底 URI。

當您還沒有通道的服務 URL 時，請使用 https://smba.trafficmanager.net/teams/ 作為服務 URL。 如需詳細資訊，請參閱 如何在 Teams 中建立交談和主動式訊息。

例如，假設當使用者傳送訊息給 Bot 時，Bot 會收到下列活動。

{
    "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 訊息內的 屬性工作表示 Bot 應該將回應傳送至端點 https://smba.trafficmanager.net/teams/ 。 服務 URL 將是 Bot 在此交談內容中發出之任何後續要求的基底 URI。 如果您的 Bot 需要傳送主動式訊息給使用者，請務必儲存 的值 serviceUrl 。

下列範例顯示 Bot 發出回應使用者訊息的要求。

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 標頭，以指定用來驗證 Bot 的存取權杖。 使用此格式指定 Authorization 標頭：

Authorization: Bearer ACCESS_TOKEN

如需如何取得 Bot 存取權杖的詳細資訊，請參閱 驗證 Bot 對 Bot 連線or 服務 的要求。

回應標頭

除了標準 HTTP 回應標頭之外，每個回應都會包含標頭 X-Correlating-OperationId 。 此標頭的值是對應至 Bot Framework 記錄專案的識別碼，其中包含要求的詳細資料。 當您收到錯誤回應時，應該擷取此標頭的值。 如果您無法獨立解決問題，請在回報問題時提供給支援小組的資訊中包含此值。

HTTP 狀態碼

每個回應所傳回的 HTTP 狀態碼 會指出對應要求的結果。

注意

下表描述最常見的 HTTP 狀態碼。 通道會產生某些錯誤。 如需詳細資訊，您可能需要閱讀通道的開發人員檔。

HTTP 狀態碼 意義
200 要求成功。
201 要求成功。
202 要求已接受進行處理。
204 要求成功，但未傳回任何內容。
400 要求的格式不正確或不正確。
401 Bot 尚未通過驗證。
403 Bot 未獲授權執行要求的作業。
404 找不到要求的資源。
405 通道不支援要求的作業。
500 發生內部伺服器錯誤。
503 服務暫時無法使用。

錯誤

任何指定 4xx 範圍或 5xx 範圍中 HTTP 狀態碼的回應，都會在 提供錯誤相關資訊的回應主體中包含 ErrorResponse 物件。 如果您在 4xx 範圍內收到錯誤回應，請檢查 ErrorResponse 物件以識別錯誤的原因，並在重新提交要求之前解決您的問題。

交談作業

使用這些作業來建立交談、傳送訊息（活動），以及管理交談的內容。

重要

並非所有通道都支援所有端點。 不過，所有通道都應該支援對活動 端點的 回復。

例如，只有 Direct Line 和 網路聊天支援 取得交談 端點。

作業 描述
建立交談 建立新的交談。
刪除活動 刪除現有的活動。
刪除交談成員 從交談中移除成員。
取得活動成員 取得指定交談中指定活動的成員。
取得交談成員 取得交談成員的詳細資料。
取得交談成員 取得指定交談的成員。
取得交談分頁成員 取得指定交談的成員一次一頁。
取得交談 取得 Bot 參與的交談清單。
回復活動 將活動 （message） 傳送至指定的交談，以回復指定的活動。
傳送交談歷程記錄 將過去活動的文字記錄上傳至交談。
傳送至交談 將活動 （message） 傳送至指定交談的結尾。
更新活動 更新現有的活動。
將附件上傳至頻道 將附件直接上傳至通道的 Blob 儲存體。

建立交談

建立新的交談。

POST /v3/conversations
Content 描述
要求本文 ConversationParameters 物件
傳回 ConversationResourceResponse 物件

刪除活動

某些通道可讓您刪除現有的活動。 如果成功，這項作業會從指定的交談中移除指定的活動。

DELETE /v3/conversations/{conversationId}/activities/{activityId}
Content 描述
要求本文 n/a
傳回 指出作業結果的 HTTP 狀態碼。 回應主體中未指定任何專案。

刪除交談成員

從交談中移除成員。 如果該成員是交談的最後一個成員，也會刪除交談。

DELETE /v3/conversations/{conversationId}/members/{memberId}
Content 描述
要求本文 n/a
傳回 指出作業結果的 HTTP 狀態碼。 回應主體中未指定任何專案。

取得活動成員

取得指定交談中指定活動的成員。

GET /v3/conversations/{conversationId}/activities/{activityId}/members
Content 描述
要求本文 n/a
傳回 ChannelAccount 物件的陣列

取得交談

取得 Bot 參與的交談清單。

GET /v3/conversations?continuationToken={continuationToken}
Content 描述
要求本文 n/a
傳回 ConversationsResult 物件

取得交談成員

取得特定交談特定成員的詳細資料。

GET /v3/conversations/{conversationId}/members/{memberId}
Content 描述
要求本文 n/a
傳回 成員的 ChannelAccount 物件。

取得交談成員

取得指定交談的成員。

GET /v3/conversations/{conversationId}/members
Content 描述
要求本文 n/a
傳回 交談成員的 ChannelAccount 物件陣列。

取得交談分頁成員

取得指定交談的成員一次一頁。

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}
Content 描述
要求本文 n/a
傳回 PagedMembersResult 物件

回復活動

將活動 （message） 傳送至指定的交談，以回復指定的活動。 如果通道支援活動，活動將會新增為另一個活動的回復。 如果通道不支援巢狀回復，則此作業的行為會像傳送至交談 一樣 。

POST /v3/conversations/{conversationId}/activities/{activityId}
Content 描述
要求本文 Activity 物件
傳回 ResourceResponse 物件

傳送交談歷程記錄

將過去的活動文字記錄上傳至交談，讓用戶端可以轉譯它們。

POST /v3/conversations/{conversationId}/activities/history
Content 描述
要求本文 文字記錄 物件。
傳回 ResourceResponse 物件。

傳送至交談

將活動 （message） 傳送至指定的交談。 活動會根據通道的時間戳記或語意，附加至交談結尾。 若要回復交談內的特定訊息，請改用 回復活動 。

POST /v3/conversations/{conversationId}/activities
Content 描述
要求本文 Activity 物件
傳回 ResourceResponse 物件

更新活動

某些通道可讓您編輯現有的活動，以反映 Bot 交談的新狀態。 例如，在使用者按一下其中一個按鈕之後，您可能會從交談中的訊息中移除按鈕。 如果成功，這項作業會更新指定交談內的指定活動。

PUT /v3/conversations/{conversationId}/activities/{activityId}
Content 描述
要求本文 Activity 物件
傳回 ResourceResponse 物件

將附件上傳至頻道

將指定交談的附件直接上傳至通道的 Blob 儲存體。 這可讓您將資料儲存在相容的存放區中。

POST /v3/conversations/{conversationId}/attachments
Content 描述
要求本文 AttachmentData 物件。
傳回 ResourceResponse 物件。 id 屬性會指定可與取得附件資訊 作業和 取得附件 作業搭配 使用的附件識別碼。

附件作業

使用這些作業來擷取附件的相關資訊，以及檔案本身的二進位資料。

作業 描述
取得附件資訊 取得指定附件的相關資訊，包括檔案名、檔案類型和可用的檢視表（例如，原始或縮圖）。
取得附件 取得指定附件的指定檢視做為二進位內容。

取得附件資訊

取得指定附件的相關資訊，包括檔案名、類型和可用的檢視表（例如，原始或縮圖）。

GET /v3/attachments/{attachmentId}
Content 描述
要求本文 n/a
傳回 AttachmentInfo 物件

取得附件

取得指定附件的指定檢視做為二進位內容。

GET /v3/attachments/{attachmentId}/views/{viewId}
Content 描述
要求本文 n/a
傳回 二進位內容，表示指定附件的指定檢視

狀態作業（已淘汰）

自 2018 年 3 月 30 日起，Microsoft Bot Framework State 服務已淘汰。 先前，建置在 Azure AI Bot Service 或 Bot Builder SDK 上的 Bot 已預設連線至 Microsoft 所裝載的此服務，以儲存 Bot 狀態資料。 Bot 必須更新，才能使用自己的狀態儲存體。

作業 描述
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 架構會定義 Bot 可用來與使用者通訊的物件及其屬性。

Object 描述
Activity 物件 定義 Bot 與使用者之間交換的訊息。
AnimationCard 物件 定義可以播放動畫 GIF 或短片的卡片。
Attachment 物件 定義要包含在訊息中的其他資訊。 附件可能是媒體檔案（例如音訊、視訊、影像、檔案）或豐富卡片。
AttachmentData 物件 描述附件資料。
AttachmentInfo 物件 描述附件。
AttachmentView 物件 定義 物件，此物件表示附件的可用檢視。
AudioCard 物件 定義可以播放音訊檔案的卡片。
CardAction 物件 定義要執行的動作。
CardImage 物件 定義要顯示在卡片上的影像。
ChannelAccount 物件 定義通道上的 Bot 或使用者帳戶。
ConversationAccount 物件 定義通道中的交談。
ConversationMembers 物件 定義交談的成員。
ConversationParameters 物件 定義用來建立新交談的參數
ConversationReference 物件 定義交談中的特定點。
ConversationResourceResponse 物件 定義建立交談 的 回應。
ConversationsResult 物件 定義呼叫 取得交談 的結果。
Entity 物件 定義實體物件。
Error 物件 定義錯誤。
ErrorResponse 物件 定義 HTTP API 回應。
Fact 物件 定義包含事實的索引鍵/值組。
GeoCoordinates 物件 使用 World Geodetic System （WSG84） 座標來定義地理位置。
HeroCard 物件 定義具有大型影像、標題、文字和動作按鈕的卡片。
InnerHttpError 物件 物件，表示內部 HTTP 錯誤。
MediaEventValue 物件 媒體事件的補充參數。
MediaUrl 物件 定義媒體檔案來源的 URL。
Mention 物件 定義交談中提及的使用者或 Bot。
MessageReaction 物件 定義訊息的反應。
PagedMembersResult 物件 取得交談分頁成員 所 傳回的成員頁面。
放置物件 定義交談中提及的位置。
ReceiptCard 物件 定義包含購買收據的卡片。
ReceiptItem 物件 定義收據內的明細專案。
ResourceResponse 物件 定義資源。
SemanticAction 物件 定義程式設計動作的參考。
SignInCard 物件 定義可讓使用者登入服務的卡片。
SuggestedActions 物件 定義使用者可以從中選擇的選項。
TextHighlight 物件 是指另一個欄位內內容的子字串。
ThumbnailCard 物件 使用縮圖影像、標題、文字和動作按鈕來定義卡片。
ThumbnailUrl 物件 定義影像來源的 URL。
文字記錄物件 要使用傳送交談記錄 上傳 的活動集合。
VideoCard 物件 定義可以播放影片的卡片。

Activity 物件

定義 Bot 與使用者之間交換的訊息。

屬性 類型​ 描述
action String 要套用或已套用的動作。 使用 type 屬性來判斷動作的內容。 例如，如果類型為 contactRelationUpdate ，如果使用者將 Bot 新增至其連絡人清單，則動作 屬性的值 將會 新增 ，或者 如果使用者從連絡人清單中移除 Bot，則會將其移除 。
attachmentLayout String 郵件所包含的豐富卡片 附件 配置。 下列其中一個值： 浮動切換 、 清單 。 如需豐富卡片附件的詳細資訊，請參閱 將豐富卡片附件新增至訊息 。
附件 Attachment [] Attachment 物件的陣列，定義要包含在訊息中的其他資訊。 每個附件可能是檔案（例如音訊、視訊、影像）或豐富卡片。
callerId String 字串，包含識別 Bot 呼叫端的 IRI。 此欄位並非要透過網路傳輸，而是由 Bot 和用戶端根據可密碼編譯驗證的資料填入，以判斷呼叫者身分識別（例如權杖） 的身分識別為基礎。
channelData Object 物件，包含通道特定內容。 某些通道提供的功能需要無法使用附件架構表示的其他資訊。 針對這些情況，請將此屬性設定為通道特定的內容，如通道檔中所定義。 如需詳細資訊，請參閱 實作通道特定功能 。
channelId String 可唯一識別通道的識別碼。 由通道設定。
code String 指出交談結束原因的程式碼。
談話 ConversationAccount ConversationAccount 物件，定義活動所屬的交談。
deliveryMode String 傳送提示，以向收件者發出活動替代傳遞路徑的訊號。 下列其中一個值： 一般 、 通知 。
實體 object[] 物件陣列，表示訊息中所提及的實體。 這個陣列中的物件可以是任何 Schema.org 物件。 例如，陣列可能包含 Mention 物件，可識別交談中提及的人員，以及 識別交談中所提及位置的 Place 物件。
到期 String 活動應該視為「已過期」的時間，且不應該向收件者呈現。
from ChannelAccount 指定訊息寄件者的 ChannelAccount 物件。
historyDisclosed 布林值 指出是否要披露歷程記錄的旗標。 預設值為 false。
id String 可唯一識別通道上活動的識別碼。
重要性 String 定義活動的重要性。 下列其中一個值： 低 、 正常 、 高 。
inputHint String 值，指出您的 Bot 在訊息傳遞至用戶端之後是否接受、預期或忽略使用者輸入。 下列其中一個值：acceptingInput、expectingInput 、 ignoringInput 。
label String 活動的描述性標籤。
listenFor String[] 語音和語言準備系統應該接聽的片語和參考清單。
地區設定 String 語言的地區設定，應該用來在訊息內顯示文字，格式為 <language>-<country> 。 通道會使用這個屬性來指出使用者的語言，讓 Bot 可以指定該語言中的顯示字串。 預設值為 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 [] 從交談中移除之回應的集合。
收件者 ChannelAccount 指定郵件收件者的 ChannelAccount 物件。
relatesTo ConversationReference ConversationReference 物件，定義交談中的特定點。
replyToId String 此訊息所回復之訊息的識別碼。 若要回復使用者傳送的訊息，請將此屬性設定為使用者訊息的識別碼。 並非所有通道都支援執行緒回復。 在這些情況下，通道會忽略這個屬性，並使用時間排序的語意（timestamp）將訊息附加至交談。
semanticAction SemanticAction SemanticAction 物件，表示程式設計動作的參考。
serviceUrl String 指定通道服務端點的 URL。 由通道設定。
說 String Bot 在啟用語音的通道上要說出的文字。 若要控制 Bot 語音的各種特性，例如語音、速率、音量、發音和音調，請在語音合成標記語言 （SSML） 格式中 指定此屬性。
suggestedActions SuggestedActions SuggestedActions 物件，定義使用者可以從中選擇的選項。
summary String 訊息包含之資訊的摘要。 例如，對於在電子郵件通道上傳送的訊息，這個屬性可能會指定電子郵件訊息的前 50 個字元。
text String 從使用者傳送至 Bot 或 Bot 給使用者的訊息文字。 如需此屬性內容的限制，請參閱通道的檔。
textFormat String 訊息 文字 的格式。 下列其中一個值： Markdown 、 plain 、 xml 。 如需文字格式的詳細資訊，請參閱 建立訊息 。
textHighlights TextHighlight [] 活動包含 replyToId 值時要反白顯示的文字片段集合。
timestamp String 訊息以 UTC 時區傳送的日期和時間，以 ISO-8601 格式表示。
topicName String 活動所屬交談的主題。
type String 活動類型。 下列其中一個值：message、contactRelationUpdate、conversationUpdate 、 輸入 、 endOfConversation 、 event 、 invoke 、 deleteUserData 、 messageUpdate、messageDelete 、installationUpdate 、messageReaction 、 suggestion 、trace 、 handoff。 如需活動類型的詳細資訊，請參閱 活動概觀 。
value Object 開放式值。
valueType String 活動值物件的型別。

回到架構資料表

AnimationCard 物件

定義可以播放動畫 GIF 或短片的卡片。

屬性 類型​ 描述
方面 布林值 縮圖/媒體預留位置的外觀比例。 允許的值為 「16：9」 和 「4：3」。
autoloop 布林值 旗標，指出是否要在最後一個結束時重新執行動畫 GIF 清單。 將此屬性設定為 true 以自動重新執行動畫， 否則為 false 。 預設值為 true。
autostart 布林值 旗標，指出是否要在顯示卡片時自動播放動畫。 將此屬性設定為 true 以自動播放動畫， 否則為 false 。 預設值為 true。
按鈕 CardAction [] CardAction 物件的陣列，可讓使用者執行一或多個動作。 通道會決定您可以指定的按鈕數目。
duration String 以 ISO 8601 持續時間格式 的媒體內容 長度。
image ThumbnailUrl ThumbnailUrl 物件，指定要顯示在卡片上的影像。
media MediaUrl [] MediaUrl 物件的陣列。 當此欄位包含多個 URL 時，每個 URL 都是相同內容的替代格式。
共用 布林值 指出動畫是否可與其他人共用的旗標。 如果可以共用動畫，請將此屬性設定為 true ; 否則為 false 。 預設值為 true。
字幕 String 要顯示在卡片標題下的子標題。
text String 在卡片標題或副標題下顯示的描述或提示。
title String 卡片的標題。
value Object 此卡片的增補參數。

回到架構資料表

Attachment 物件

定義要包含在訊息中的其他資訊。 附件可能是檔案（例如影像、音訊或視訊）或豐富卡片。

屬性 類型​ 描述
內容 Object 附件的內容。 如果附件是豐富卡片，請將此屬性設定為 rich card 物件。 此屬性和 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：主圖 卡片。 將 內容 屬性設定為 HeroCard 物件。
  • application/vnd.microsoft.card.receipt：收據 卡。 將 content 屬性設定為 ReceiptCard 物件。
  • application/vnd.microsoft.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、檔案和資料。
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 附件的內容類型。
視圖 AttachmentView [] AttachmentView 物件的陣列，代表附件的可用檢視。

回到架構資料表

AttachmentView 物件

定義 物件，此物件表示附件的可用檢視。

屬性 類型​ 描述
size 數值 檔案的大小。
viewId String 檢視識別碼。

回到架構資料表

AudioCard 物件

定義可以播放音訊檔案的卡片。

屬性 類型​ 描述
方面 String 影像 屬性中指定的 縮圖外觀比例。 有效值為 16：9 和 4：3 。
autoloop 布林值 旗標，指出是否要在最後一個結束時重新執行音訊檔案清單。 將此屬性設定為 true 以自動重新執行音訊檔案， 否則為 false 。 預設值為 true。
autostart 布林值 旗標，指出是否要在顯示卡片時自動播放音訊。 將此屬性設定為 true 以自動播放音訊， 否則為 false 。 預設值為 true。
按鈕 CardAction [] CardAction 物件的陣列，可讓使用者執行一或多個動作。 通道會決定您可以指定的按鈕數目。
duration String 以 ISO 8601 持續時間格式 的媒體內容 長度。
image ThumbnailUrl ThumbnailUrl 物件，指定要顯示在卡片上的影像。
media MediaUrl [] MediaUrl 物件的陣列。 當此欄位包含多個 URL 時，每個 URL 都是相同內容的替代格式。
共用 布林值 指出音訊檔案是否可與其他人共用的旗標。 如果可以共用音訊，請將此屬性設定為 true ; 否則為 false 。 預設值為 true。
字幕 String 要顯示在卡片標題下的子標題。
text String 在卡片標題或副標題下顯示的描述或提示。
title String 卡片的標題。
value Object 此卡片的增補參數。

回到架構資料表

CardAction 物件

使用按鈕定義可點選的動作。

屬性 類型​ 描述
channelData String 與此動作相關聯的通道特定資料。
displayText String 按一下按鈕時，要顯示在聊天摘要中的文字。
image String 會出現在文字標籤旁按鈕上的影像 URL。
text String 動作的文字。
title String 出現在按鈕上的文字描述。
type String 要執行的動作類型。 如需有效值的清單，請參閱 將豐富卡片附件新增至郵件 。
value Object 動作的增補參數。 此屬性的行為會根據動作 類型 而有所不同。 如需詳細資訊，請參閱 將豐富卡片附件新增至訊息 。

回到架構資料表

CardImage 物件

定義要顯示在卡片上的影像。

屬性 類型​ 描述
Alt String 影像的描述。 您應該包含支援協助工具的描述。
水龍頭 CardAction CardAction 物件，指定要在使用者點選或按一下影像時要執行的動作。
url String 影像來源的 URL 或影像的 base64 二進位檔 （例如 ， data:image/png;base64,iVBORw0KGgo... ）。

回到架構資料表

ChannelAccount 物件

定義通道上的 Bot 或使用者帳戶。

屬性 類型​ 描述
aadObjectId String 此帳戶的物件識別碼位於 Microsoft Entra ID 內。
id String 此通道上使用者或 Bot 的唯一識別碼。
name String Bot 或使用者的顯示易記名稱。
作用 String 帳戶後方的實體角色。 使用者 或 Bot 。

回到架構資料表

ConversationAccount 物件

定義通道中的交談。

屬性 類型​ 描述
aadObjectId String 此帳戶的物件識別碼位於 Microsoft Entra ID 內。
conversationType String 指出通道中區分交談類型（例如群組或個人）的交談類型。
id String 識別交談的識別碼。 每個通道的識別碼是唯一的。 如果通道啟動交談，則會設定此識別碼;否則，Bot 會將此屬性設定為啟動交談時，它會在回應中傳回的識別碼（請參閱 建立交談 ）。
isGroup 布林值 旗標，指出對話在產生活動時是否包含兩個以上的參與者。 如果這是群組交談，則設定為 true ;否則為 false 。 預設值為 false。
name String 可用來識別交談的顯示名稱。
作用 String 帳戶後方的實體角色。 使用者 或 Bot 。
tenantId String 此交談的租使用者識別碼。

回到架構資料表

ConversationMembers 物件

定義交談的成員。

屬性 類型​ 描述
id String 交談識別碼。
成員 ChannelAccount [] 此交談中的成員清單。

回到架構資料表

ConversationParameters 物件

定義用來建立新交談的參數。

屬性 類型​ 描述
活動 Activity 建立交談時要傳送至交談的初始訊息。
Bot ChannelAccount 將訊息路由傳送至 Bot 所需的通道帳戶資訊。
channelData Object 用來建立交談的通道特定承載。
isGroup 布林值 指出這是否為群組交談。
成員 ChannelAccount [] 將訊息路由傳送給每個使用者所需的通道帳戶資訊。
tenantId String 應在其中建立交談的租使用者識別碼。
topicName String 交談的主題。 只有當通道支援此屬性時，才會使用這個屬性。

回到架構資料表

ConversationReference 物件

定義交談中的特定點。

屬性 類型​ 描述:
activityId String 可唯一識別這個物件參考之活動的識別碼。
Bot ChannelAccount ChannelAccount 物件，識別此物件所參考交談中的 Bot。
channelId String 可唯一識別此物件所參考交談中通道的識別碼。
談話 ConversationAccount ConversationAccount 物件，定義這個物件所參考的交談。
serviceUrl String URL，指定這個物件所參考之交談中的通道服務端點。
user ChannelAccount ChannelAccount 物件，識別此物件所參考之交談中的使用者。

回到架構資料表

ConversationResourceResponse 物件

定義建立交談 的 回應。

屬性 類型​ 描述:
activityId String 如果已傳送，則為活動的識別碼。
id String 資源的識別碼。
serviceUrl String 執行交談相關作業的服務端點。

回到架構資料表

ConversationsResult 物件

定義取得交談 的結果 。

屬性 類型​ 描述
對話 ConversationMembers [] 每個交談中的成員。
continuationToken String 接續權杖，可用於後續呼叫取得 交談 。

回到架構資料表

Entity 物件

與活動相關的中繼資料物件。

屬性 類型​ 描述
type String 此實體的類型（RFC 3987 IRI）。

回到架構資料表

Error 物件

代表錯誤資訊的物件。

屬性 類型​ 描述
code String 錯誤碼。
innerHttpError InnerHttpError 物件，表示內部 HTTP 錯誤。
message String 一個錯誤描述。

回到架構資料表

ErrorResponse 物件

定義 HTTP API 回應。

屬性 類型​ 描述
錯誤 錯誤 Error 物件，其中包含錯誤的相關資訊。

回到架構資料表

Fact 物件

定義包含事實的索引鍵/值組。

屬性 類型​ 描述
key String 事實的名稱。 例如， 簽入 。 當顯示事實的值時，索引鍵會當做標籤使用。
value String 事實的值。 例如， 2016 年 10 月 10 日。

回到架構資料表

GeoCoordinates 物件

使用 World Geodetic System （WSG84） 座標來定義地理位置。

屬性 類型​ 描述
海拔 數值 位置的提高許可權。
緯度 數值 位置的緯度。
經度 數值 位置的經度。
name String 位置的名稱。
type String 這個 物件的類型。 一律設定為 GeoCoordinates 。

回到架構資料表

HeroCard 物件

定義具有大型影像、標題、文字和動作按鈕的卡片。

屬性 類型​ 描述
按鈕 CardAction [] CardAction 物件的陣列，可讓使用者執行一或多個動作。 通道會決定您可以指定的按鈕數目。
images CardImage [] CardImage 物件的陣列，指定要顯示在卡片上的影像。 主圖卡片只包含一個影像。
字幕 String 要顯示在卡片標題下的子標題。
水龍頭 CardAction CardAction 物件，指定要在使用者點選或按一下卡片時要執行的動作。 這可以是與其中一個按鈕或不同動作相同的動作。
text String 在卡片標題或副標題下顯示的描述或提示。
title String 卡片的標題。

回到架構資料表

InnerHttpError 物件

物件，表示內部 HTTP 錯誤。

屬性 類型​ 描述
statusCode 數值 來自失敗要求的 HTTP 狀態碼。
身體 Object 失敗要求中的本文。

回到架構資料表

MediaEventValue 物件

媒體事件的補充參數。

屬性 類型​ 描述
cardValue Object 在產生此事件之媒體卡的值 欄位中指定的 回呼參數。

回到架構資料表

MediaUrl 物件

定義媒體檔案來源的 URL。

屬性 類型​ 描述
profile String 描述媒體內容的提示。
url String 媒體檔案來源的 URL。

回到架構資料表

Mention 物件

定義交談中提及的使用者或 Bot。

屬性 類型​ 描述
提到 ChannelAccount ChannelAccount 物件，指定所提及的使用者或 Bot。 某些通道，例如 Slack，會為每個交談指派名稱，因此您的 Bot 提及的名稱（在郵件的 收件者 屬性中）可能與您註冊 Bot 時 指定的控制碼不同。 不過，這兩者的帳戶識別碼會相同。
text String 交談中所述的使用者或 Bot。 例如，如果訊息為「@ColorBot挑選我新的色彩」，則此屬性會設定為 @ColorBot 。 並非所有通道都會設定此屬性。
type String 這個物件的類型。 一律設定為 [ 提及 ]。

回到架構資料表

MessageReaction 物件

定義訊息的反應。

屬性 類型​ 描述
type String 反應的類型。 例如 或 plusOne 。

回到架構資料表

PagedMembersResult 物件

取得交談分頁成員 所 傳回的成員頁面。

屬性 類型​ 描述
continuationToken String 接續權杖，可用於後續呼叫取得 交談分頁成員 。
成員 ChannelAccount [] 交談成員的陣列。

回到架構資料表

放置物件

定義交談中提及的位置。

屬性 類型​ 描述
address Object 地點的位址。 此屬性可以是 PostalAddress 類型的 字串 或複雜物件。
地理 GeoCoordinates 指定位置地理座標的 GeoCoordinates 物件。
hasMap Object 對應至位置。 此屬性可以是 String （URL） 或 Map 類型的 複雜物件。
name String 地點的名稱。
type String 這個物件的類型。 一律設定為 Place 。

回到架構資料表

ReceiptCard 物件

定義包含購買收據的卡片。

屬性 類型​ 描述
按鈕 CardAction [] CardAction 物件的陣列，可讓使用者執行一或多個動作。 通道會決定您可以指定的按鈕數目。
事實 Fact [] 指定購買相關資訊的 Fact 物件陣列。 例如，旅館住宿收據的事實清單可能包含簽入日期和簽出日期。 通道會決定您可以指定的事實數目。
專案 ReceiptItem [] 指定已購買專案的 ReceiptItem 物件陣列
水龍頭 CardAction CardAction 物件，指定要在使用者點選或按一下卡片時要執行的動作。 這可以是與其中一個按鈕或不同動作相同的動作。
稅 String 貨幣格式字串，指定套用至購買的稅額。
title String 顯示在收據頂端的標題。
總計 String 指定購買價格總計的貨幣格式字串，包括所有適用的稅金。
加值稅 String 貨幣格式字串，指定套用至購買價格的加值稅（加值稅）金額。

回到架構資料表

ReceiptItem 物件

定義收據內的明細專案。

屬性 類型​ 描述
image CardImage CardImage 物件，指定要顯示在明細專案旁的縮圖影像。
價格 String 貨幣格式字串，指定所有購買單位的總價格。
數量 String 指定購買單位數目的數值字串。
字幕 String 要顯示在明細專案標題下的子標題。
水龍頭 CardAction CardAction 物件，指定使用者點選或按一下明細專案時要執行的動作。
text String 明細專案的描述。
title String 明細專案的標題。

回到架構資料表

ResourceResponse 物件

定義包含資源識別碼的回應。

屬性 類型​ 描述
id String 可唯一識別資源的識別碼。

回到架構資料表

SemanticAction 物件

定義程式設計動作的參考。

屬性 類型​ 描述
實體 Object 物件，其中每個屬性的值都是 Entity 物件。
id String 此動作的識別碼。
state String 此動作的狀態。 允許的值： start 、 continue 、 done 。

回到架構資料表

SignInCard 物件

定義可讓使用者登入服務的卡片。

屬性 類型​ 描述
按鈕 CardAction [] CardAction 物件的陣列，可讓使用者登入服務。 通道會決定您可以指定的按鈕數目。
text String 登入卡片上要包含的描述或提示。

回到架構資料表

SuggestedActions 物件

定義使用者可以從中選擇的選項。

屬性 類型​ 描述
actions CardAction [] 定義建議動作的 CardAction 物件陣列。
to String[] 字串陣列，其中包含應顯示建議動作之收件者的識別碼。

回到架構資料表

TextHighlight 物件

是指另一個欄位內內容的子字串。

屬性 類型​ 描述
occurrence 數值 如果有多個存在，則出現在參考文字內的文字欄位。
text String 定義要反白顯示的文字片段。

回到架構資料表

ThumbnailCard 物件

使用縮圖影像、標題、文字和動作按鈕來定義卡片。

屬性 類型​ 描述
按鈕 CardAction [] CardAction 物件的陣列，可讓使用者執行一或多個動作。 通道會決定您可以指定的按鈕數目。
images CardImage [] CardImage 物件的陣列，指定要顯示在卡片上的縮圖影像。 通道會決定您可以指定的縮圖影像數目。
字幕 String 要顯示在卡片標題下的子標題。
水龍頭 CardAction CardAction 物件，指定要在使用者點選或按一下卡片時要執行的動作。 這可以是與其中一個按鈕或不同動作相同的動作。
text String 在卡片標題或副標題下顯示的描述或提示。
title String 卡片的標題。

回到架構資料表

ThumbnailUrl 物件

定義影像來源的 URL。

屬性 類型​ 描述
Alt String 影像的描述。 您應該包含支援協助工具的描述。
url String 影像來源的 URL 或影像的 base64 二進位檔 （例如 ， data:image/png;base64,iVBORw0KGgo... ）。

回到架構資料表

文字記錄物件

要使用傳送交談記錄 上傳 的活動集合。

屬性 類型​ 描述
活動 陣列 Activity 物件的陣列 。 它們應該各有唯一的識別碼和時間戳記。

回到架構資料表

VideoCard 物件

定義可以播放影片的卡片。

屬性 類型​ 描述
方面 String 影片的外觀比例。 16：9 或 4：3 。
autoloop 布林值 旗標，指出是否要在最後一個影片結束時重新執行影片清單。 將此屬性設定為 true 以自動重新執行影片， 否則為 false 。 預設值為 true。
autostart 布林值 旗標，指出是否要在顯示卡片時自動播放影片。 將此屬性設定為 true 以自動播放影片， 否則為 false 。 預設值為 true。
按鈕 CardAction [] CardAction 物件的陣列，可讓使用者執行一或多個動作。 通道會決定您可以指定的按鈕數目。
duration String 以 ISO 8601 持續時間格式 的媒體內容 長度。
image ThumbnailUrl ThumbnailUrl 物件，指定要顯示在卡片上的影像。
media MediaUrl [] MediaUrl 的 陣列。 當此欄位包含多個 URL 時，每個 URL 都是相同內容的替代格式。
共用 布林值 指出影片是否可與其他人共用的旗標。 如果影片可以共用，請將此屬性設定為 true ; 否則為 false 。 預設值為 true。
字幕 String 要顯示在卡片標題下的子標題。
text String 在卡片標題或副標題下顯示的描述或提示。
title String 卡片的標題。
value Object 此卡片的增補參數

回到架構資料表