Add media attachments to messages with the Bot Connector API

APPLIES TO: SDK v3

Bots and channels typically exchange text strings but some channels also support exchanging attachments, which lets your bot send richer messages to users. For example, your bot can send media attachments (e.g., images, videos, audio, files) and rich cards. This article describes how to add media attachments to messages using the Bot Connector service.

Add a media attachment

To add a media attachment to a message, create an Attachment object, set the name property, set the contentUrl property to the URL of the media file, and set the contentType property to the appropriate media type (e.g., image/png, audio/wav, video/mp4). Then within the Activity object that represents your message, specify your Attachment object within the attachments array.

The following example shows a request that sends a message containing text and a single image attachment. In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/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/png",
            "contentUrl": "https://aka.ms/DuckOnARock",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

For channels that support inline binaries of an image, you can set the contentUrl property of the Attachment to a base64 binary of the image (for example, data:image/png;base64,iVBORw0KGgo…). The channel will display the image or the image's URL next to the message's text string.

{
    "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/png",
            "contentUrl": "data:image/png;base64,iVBORw0KGgo…",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

You can attach a video file or audio file to a message by using the same process as described above for an image file. Depending on the channel, the video and audio may be played inline or it may be displayed as a link.

Add an AudioCard attachment

Adding an AudioCard or VideoCard attachment is the same as adding a media attachment. For example, the following JSON shows how to add an audio card in the media attachment.

{
    "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"
}

Once the channel receives this attachment, it will start playing the audio file. If a user interacts with audio by clicking the Pause button, for example, the channel will send a callback to the bot with a JSON that look something like this:

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

The media event name media/pause will appear in the activity.name field. Reference the below table for a list of all media event names.

Additional resources

• Create messages
• Send and receive messages
• Add rich cards to messages
• Bot Framework Activity schema
• Bot Framework card schema