Hinzufügen von Medienanlagen zu Nachrichten mit der Bot Connector-APIAdd media attachments to messages with the Bot Connector API

Bots und Kanäle tauschen in der Regel Textzeichenfolgen aus, aber einige Kanäle unterstützen auch den Austausch von Anlagen, wodurch Ihr Bot reichhaltigere Nachrichten an Benutzer senden kann.Bots and channels typically exchange text strings but some channels also support exchanging attachments, which lets your bot send richer messages to users. Ihr Bot kann z.B. Medienanlagen (z.B. Bilder, Videos, Audio, Dateien) und Rich Cards senden.For example, your bot can send media attachments (e.g., images, videos, audio, files) and rich cards. In diesem Artikel wird beschrieben, wie Sie mit dem Bot Connector-Dienst Medienanlagen zu Nachrichten hinzufügen.This article describes how to add media attachments to messages using the Bot Connector service.

Tipp

Tabellen, die beschreiben, welche Funktionen auf den einzelnen Kanälen unterstützt werden, finden Sie im Artikel Kategorisierte Aktivitäten nach Kanal.For tables describing which features are supported on each channel, see the channels reference article.

Hinzufügen einer MedienanlageAdd a media attachment

Um eine Medienanlage zu einer Nachricht hinzuzufügen, erstellen Sie ein Anlage-Objekt, legen Sie die Eigenschaft name fest, legen Sie die Eigenschaft contentUrl auf die URL der Mediendatei und die Eigenschaft contentType auf den entsprechenden Medientyp fest (z. B. image/png, audio/wav, video/mp4).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). Geben Sie dann im Aktivität-Objekt, das Ihre Nachricht darstellt, Ihr Attachment-Objekt im attachments-Array an.Then within the Activity object that represents your message, specify your Attachment object within the attachments array.

Das folgende Beispiel zeigt eine Anforderung, die eine Nachricht mit Text einer einzelnen Bildanlage sendet.The following example shows a request that sends a message containing text and a single image attachment. In dieser Beispielanforderung stellt https://smba.trafficmanager.net/apis den Basis-URI dar. Der Basis-URI für Anforderungen, die Ihr Bot ausgibt, kann ein anderer sein.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. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.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://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

Für Kanäle, die Inlinebinärdateien eines Bildes unterstützen, können Sie die contentUrl-Eigenschaft der Attachment auf eine base64-Binärdatei des Bildes setzen (z.B. data:image/png;base64,iVBORw0KGgo... ).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…). Der Kanal zeigt das Bild oder die URL des Bildes neben dem Text der Nachricht an.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"
}

Sie können eine Video- oder Audiodatei an eine Nachricht anhängen, indem Sie das gleiche Verfahren wie oben für eine Bilddatei verwenden.You can attach a video file or audio file to a message by using the same process as described above for an image file. Klicken Sie je nach den Kanal Video und Audio möglicherweise wiedergegeben werden Inline, oder kann als Link angezeigt werden.Depending on the channel, the video and audio may be played inline or it may be displayed as a link.

Hinweis

Ihr Bot kann auch Nachrichten empfangen, die Medienanlagen enthalten.Your bot may also receive messages that contain media attachments. Beispielsweise kann eine Nachricht, die Ihr Bot erhält, eine Anlage enthalten, wenn der Kanal es dem Benutzer ermöglicht, ein Foto zur Analyse hochzuladen oder ein Dokument zu speichern.For example, a message that your bot receives may contain an attachment if the channel enables the user to upload a photo to be analyzed or a document to be stored.

Hinzufügen einer AudioCard-AnlageAdd an AudioCard attachment

Das Hinzufügen einer AudioCard- oder VideoCard-Anlage ist dasselbe wie das Hinzufügen einer Medienanlage.Adding an AudioCard or VideoCard attachment is the same as adding a media attachment. Der folgende JSON-Code zeigt beispielsweise, wie Sie eine Soundkarte in der Medienanlage hinzufügen.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"
}

Sobald der Kanal diese Anlage empfängt, startet er die Wiedergabe der Audiodatei.Once the channel receives this attachment, it will start playing the audio file. Wenn ein Benutzer beispielsweise mit der Audiodatei interagiert, indem er auf die Schaltfläche Pause klickt, sendet der Kanal einen Rückruf an den Bot mit einem JSON-Code, der ungefähr so aussieht: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
        }
    }
}

Der Medienereignisname media/pause wird im Feld activity.name angezeigt.The media event name media/pause will appear in the activity.name field. Eine Liste aller Medienereignisnamen finden Sie in der Tabelle unten.Reference the below table for a list of all media event names.

EreignisEvent BESCHREIBUNGDescription
media/nextmedia/next Der Client ist zu den nächsten Medien gesprungen.The client skipped to the next media
media/pausemedia/pause Der Client hat die Wiedergabe von Medien unterbrochen.The client paused playing media
media/playmedia/play Der Client hat die Wiedergabe von Medien gestartet.The client began playing media
media/previousmedia/previous Der Client ist zu den vorherigen Medien gesprungen.The client skipped to the previous media
media/resumemedia/resume Der Client hat die Wiedergabe von Medien fortgesetzt.The client resumed playing media
media/stopmedia/stop Der Client hat die Wiedergabe von Medien angehalten.The client stopped playing media

Zusätzliche RessourcenAdditional resources