使用 Bot 連接器 API 將媒體附件新增至訊息

發行項
10/07/2023

Bot 和頻道通常會交換文字字串，但某些頻道也支援交換附件，讓您的 Bot 可將更豐富的訊息傳送給使用者。例如，您的 Bot 可以傳送媒體附件 (，例如影像、視訊、音訊、檔案) 和豐富卡。本文描述如何使用 Bot 連接器服務，將媒體附件新增至訊息。

提示

如需每個通道支援哪些功能的相關資訊，請參閱通道參考文章。

新增媒體附件

若要將媒體附件新增至訊息，請建立 Attachment 物件、設定屬性、將屬性設定 namecontentUrl 為媒體檔案的 URL，並將屬性設定 contentType 為適當的媒體類型 (，例如 image/jpg、 audio/wav、 video/mp4) 。然後，在代表訊息的 Activity 物件中，於 attachments 陣列內指定您的 Attachment 物件。

下列範例所顯示的要求會傳送包含文字和單一影像附件的訊息。在此範例要求中，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"
    },
    "text": "Here's a picture of the duck I was telling you about.",
    "attachments": [
        {
            "contentType": "image/jpg",
            "contentUrl": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

對於支援映射內嵌二進位檔的通道，您可以將的 Attachment 屬性設定 contentUrl 為映射的 base64 二進位檔 (，例如data：image/jpg;base64，iVBORw0KGgo...) 。通道會顯示訊息文字字串旁邊的影像或影像 URL。

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "text": "Here's a picture of the duck I was telling you about.",
    "attachments": [
        {
            "contentType": "image/jpg",
            "contentUrl": "data:image/jpg;base64,iVBORw0KGgo...",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

您可以使用與影像檔上述處理相同的處理序，將影片檔或音訊檔附加到訊息。視通道而定，影片及音訊可以內嵌播放，也可能會顯示為連結。

注意

您的 Bot 也可能會收到包含媒體附件的訊息。比方說，如果通道可讓使用者上傳要分析的相片或要儲存的文件，Bot 所收到的訊息可能會包含附件。

新增 AudioCard 附件

新增 AudioCard 或 VideoCard 附件等同於新增媒體附件。例如，下列 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.audio",
      "content": {
        "title": "Allegro in C Major",
        "subtitle": "Allegro Duet",
        "text": "No Image, No Buttons, Autoloop, Autostart, Sharable",
        "duration": "PT2M55S",
        "media": [
          {
            "url": "https://contoso.com/media/AllegrofromDuetinCMajor.mp3"
          }
        ],
        "shareable": true,
        "autoloop": true,
        "autostart": true,
        "value": {
            // Supplementary parameter for this card
        }
      }
    }],
    "replyToId": "5d5cdc723"
}

一旦通道收到此附件，它就會開始播放音訊檔案。例如，如果使用者藉由選取 [暫停] 來與音訊互動，通道就會使用如下所示的 JSON 將回呼傳送給 Bot：

{
    ...
    "type": "event",
    "name": "media/pause",
    "value": {
        "url": // URL for media
        "cardValue": {
            // Supplementary parameter for this card
        }
    }
}

媒體事件名稱 media/pause 會出現在 activity.name 欄位中。請參考下方的資料表，以取得所有媒體事件名稱的清單。

事件	描述
media/next	用戶端已跳到下一個媒體
media/pause	用戶端已暫停播放媒體
media/play	用戶端已開始播放媒體
media/previous	用戶端已跳到上一個媒體
media/resume	用戶端已繼續播放媒體
media/stop	用戶端已停止播放媒體

使用 Bot 連接器 API 將媒體附件新增至訊息

新增媒體附件

新增 AudioCard 附件

其他資源

其他資源