使用 Bot 連接器 API 將豐富卡片附件新增至訊息
某些通道可讓您的 Bot 將 豐富型卡片 傳送給使用者。 豐富的卡片是包含互動式元素的附件，例如按鈕、文字、影像、音訊、視訊等等。
本文說明如何建立可附加至訊息的豐富型卡片。 如需將附件新增至郵件的特定指示，請參閱如何將 媒體附件新增至 郵件。
複合式資訊卡 (Rich Card) 的類型
複合式資訊卡 (Rich Card) 包含標題、描述、連結和影像。 訊息可包含多個複合式資訊卡 (Rich Card)，並以清單格式或浮動切換格式顯示。 Bot Framework 目前支援八種類型的複合式資訊卡 (Rich Card)：
| 卡片類型 | 描述 |
|---|---|
| AdaptiveCard | 可包含文字、語音、影像、按鈕和輸入欄位之任意組合的可自訂卡片。 請參閱個別頻道支援。 |
| AnimationCard | 可以播放動畫 GIF 或短片的卡片。 |
| AudioCard | 可播放音訊檔案的卡片。 |
| HeroCard | 通常包含單一大型影像、一或多個按鈕和文字的卡片。 |
| ThumbnailCard | 通常包含單一縮圖影像、一或多個按鈕和文字的卡片。 |
| ReceiptCard | 讓 Bot 向使用者提供收據的卡片。 通常包含收據上的項目清單、稅金和總金額資訊，以及其他文字。 |
| SignInCard | 可讓 Bot 要求使用者登入的卡片。 通常包含文字，以及一或多個使用者可以按一下以起始登入程序的按鈕。 |
| VideoCard | 可播放視訊的卡片。 |
提示
如需每個通道支援哪些功能的相關資訊，請參閱 通道參考 文章。
處理複合式資訊卡 (Rich Card) 內的事件
若要處理複合式資訊卡內的事件，請使用 CardAction 物件，指定在使用者按一下按鈕或點選卡片的某區段時應發生的情況。 每個 CardAction 物件都包含下列屬性：
| 屬性 | 類型 | 描述 |
|---|---|---|
| channelData | 字串 | 與此動作相關聯的通道特定資料 |
| displayText | 字串 | 在點選按鈕後要顯示在聊天動態中的文字 |
| text | 字串 | 動作的文字 |
| type | 字串 | 動作的類型 (下表中指定的其中一個值) |
| title | 字串 | 按鈕的標題 |
| image | 字串 | 按鈕的影像 URL |
| value | 字串 | 執行指定動作類型所需的值 |
注意
調適型卡片內的按鈕不會使用 CardAction 物件來建立，而會改用調適型卡片所定義的結構描述來建立。
如需示範如何將按鈕新增至調適型卡片的範例，請參閱將調適型卡片新增至訊息。
若要正確運作，請將動作類型指派給主圖卡片上的每個可點選項目。 下表列出和說明可用的動作類型，以及相關聯的值屬性應有內容。
卡片 messageBack 動作比其他卡片動作更具一般意義。 如需其他卡片動作類型的詳細資訊 messageBack ，請參閱活動架構的卡片動作一節。
| 類型 | 描述 | 值 |
|---|---|---|
| call | 開始撥打電話。 | 以下列格式撥打電話的目的地：tel:123123123123。 |
| downloadFile | 下載檔案。 | 要下載的檔案 URL。 |
| imBack | 將訊息傳送到 Bot，並在聊天中張貼可見的回應。 | 要傳送之訊息的文字。 |
| messageBack | 表示要透過聊天系統傳送的文字回應。 | 要包含在所產生訊息中的選擇性程式設計值。 |
| openUrl | 在內建瀏覽器中開啟 URL。 | 要開啟的 URL。 |
| playAudio | 播放音訊。 | 要播放的音訊 URL。 |
| playVideo | 播放影片。 | 要播放的影片 URL。 |
| postBack | 將訊息傳送到 Bot，但無法在聊天中張貼可見的回應。 | 要傳送之訊息的文字。 |
| showImage | 顯示影像。 | 要顯示的影像 URL。 |
| signin | 起始 OAuth 登入程式。 | 要起始的 OAuth 流程 URL。 |
將主圖卡新增至訊息
若要將豐富卡片附件新增至郵件：
- 建立 物件，此物件表示您要新增至訊息 的卡片類型 。
- 建立 Attachment 物件：
- 將其
contentType屬性設定為卡片的媒體類型。 - 將其
content屬性設定為您建立的物件，以代表卡片。
- 將其
- 將
Attachment物件新增至attachments訊息的陣列。
提示
包含豐富卡片附件的郵件通常不會指定 text 。
某些頻道可讓您將多張複合式資訊卡新增至訊息內的 attachments 陣列。 此功能在您想要為使用者提供多個選項的情況下很有用。 例如，如果您的 Bot 讓使用者能夠預約飯店房間，即可為使用者呈現一份複合式資訊卡清單，以顯示各種類型的可用房間。 每張卡片都會包含一張圖片，以及與房間類型相對應的便利設施清單，而使用者可以藉由點選卡片或按一下按鈕來選取房間類型。
提示
若要以清單格式顯示多張複合式資訊卡，請將 Activity 物件的 attachmentLayout 屬性設定為 "list"。
若要以浮動切換格式顯示多張複合式資訊卡，請將 Activity 物件的 attachmentLayout 屬性設定為 "carousel"。
如果通道不支援浮動切換格式，則會以清單格式顯示豐富的卡片，即使 attachmentLayout 屬性指定 「浮動切換」也一樣。
下列範例顯示包含單一主圖卡片附件的完整訊息。 在此範例要求中，https://smba.trafficmanager.net/teams 表示基底 URI，您的 Bot 所發出之要求的基底 URI 可能和這個不同。 如需設定基底 URI 的詳細資料，請參閱 API 參考。
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "sender's name"
},
"conversation": {
"id": "abcd1234",
"name": "conversation's name"
},
"recipient": {
"id": "1234abcd",
"name": "recipient's name"
},
"attachments": [
{
"contentType": "application/vnd.microsoft.card.hero",
"content": {
"title": "title goes here",
"subtitle": "subtitle goes here",
"text": "descriptive text goes here",
"images": [
{
"url": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"alt": "picture of a duck",
"tap": {
"type": "playAudio",
"value": "url to an audio track of a duck call goes here"
}
}
],
"buttons": [
{
"type": "playAudio",
"title": "Duck Call",
"value": "url to an audio track of a duck call goes here"
},
{
"type": "openUrl",
"title": "Watch Video",
"image": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"value": "url goes here of the duck in flight"
}
]
}
}
],
"replyToId": "5d5cdc723"
}
將調適型卡片新增至訊息
調適型卡片可包含文字、語音、影像、按鈕和輸入欄位的任意組合。 調適型卡片會使用調適型卡片 \(英文\) 中所指定的 JSON 格式來建立，讓您能夠完整控制卡片的內容和格式。
請利用調適型卡片網站中的資訊，來了解調適型卡片的結構描述、探索調適型卡片的元素，並查看可用以建立具有不同組合和複雜度之卡片的 JSON 範例。 此外，您可以使用互動式視覺化檢視，來設計調適型卡片承載及預覽卡片輸出。
下列範例顯示單一調適型卡片附件物件，代表工作分派。 若要將此內容傳送給使用者，您必須在訊息中將其新增為附件。
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Publish Adaptive Card schema",
"weight": "bolder",
"size": "medium"
},
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "Image",
"url": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
"size": "small",
"style": "person"
}
]
},
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "Matt Hidinger",
"weight": "bolder",
"wrap": true
},
{
"type": "TextBlock",
"spacing": "none",
"text": "Created {{DATE(2017-02-14T06:08:39Z, SHORT)}}",
"isSubtle": true,
"wrap": true
}
]
}
]
}
]
},
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
"wrap": true
},
{
"type": "FactSet",
"facts": [
{
"title": "Board:",
"value": "Adaptive Card"
},
{
"title": "List:",
"value": "Backlog"
},
{
"title": "Assigned to:",
"value": "Matt Hidinger"
},
{
"title": "Due date:",
"value": "Not set"
}
]
}
]
}
],
"actions": [
{
"type": "Action.ShowCard",
"title": "Comment",
"card": {
"type": "AdaptiveCard",
"body": [
{
"type": "Input.Text",
"id": "comment",
"isMultiline": true,
"placeholder": "Enter your comment"
}
],
"actions": [
{
"type": "Action.Submit",
"title": "OK"
}
]
}
},
{
"type": "Action.OpenUrl",
"title": "View",
"url": "https://adaptivecards.io"
}
]
}
產生的卡片包含標題、卡片建立者的相關資訊 (其名稱和虛擬人偶)、建立卡片的時間、工作指派的描述，以及指派相關資訊。 您也可以按一下按鈕來批註工作分派或檢視工作分派：
