Hinzufügen von Medienanlagen zu Nachrichten mit der Bot Connector-API

  • Artikel

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. Ihr Bot kann beispielsweise Medienanlagen (z. B. Bilder, Videos, Audio, Dateien) und Rich Cards senden. In diesem Artikel wird beschrieben, wie Sie mit dem Bot Connector-Dienst Medienanlagen zu Nachrichten hinzufügen.

Tipp

Informationen dazu, welche Features auf den einzelnen Kanälen unterstützt werden, finden Sie im Referenzartikel zu Kanälen .

Hinzufügen einer Medienanlage

Um einer Nachricht eine Medienanlage hinzuzufügen, erstellen Sie ein Attachment-Objekt , legen Sie die name Eigenschaft fest, legen Sie die contentUrl Eigenschaft auf die URL der Mediendatei fest, und legen Sie die contentType Eigenschaft auf den entsprechenden Medientyp (z. B. image/jpg, audio/wav, video/mp4) fest. Geben Sie dann im Aktivität-Objekt, das Ihre Nachricht darstellt, Ihr Attachment-Objekt im attachments-Array an.

Das folgende Beispiel zeigt eine Anforderung, die eine Nachricht mit Text einer einzelnen Bildanlage sendet. In dieser Beispielanforderung stellt https://smba.trafficmanager.net/teams den Basis-URI dar. Der Basis-URI für Anforderungen, die Ihr Bot ausgibt, kann ein anderer sein. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.

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

Für Kanäle, die Inlinebinärdateien eines Bilds unterstützen, können Sie die contentUrl -Eigenschaft von Attachment auf eine Base64-Binärdatei des Bilds festlegen (z. B. data:image/jpg; base64,iVBORw0KGgo...). Der Kanal zeigt das Bild oder die URL des Bilds neben der Textzeichenfolge der Nachricht an.

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

Sie können eine Video- oder Audiodatei an eine Nachricht anhängen, indem Sie das gleiche Verfahren wie oben für eine Bilddatei verwenden. Klicken Sie je nach den Kanal Video und Audio möglicherweise wiedergegeben werden Inline, oder kann als Link angezeigt werden.

Hinweis

Ihr Bot kann auch Nachrichten empfangen, die Medienanlagen enthalten. 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.

Hinzufügen einer AudioCard-Anlage

Das Hinzufügen einer AudioCard- oder VideoCard-Anlage ist dasselbe wie das Hinzufügen einer Medienanlage. Der folgende JSON-Code zeigt beispielsweise, wie Sie eine Soundkarte in der Medienanlage hinzufügen.

{
    "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. Wenn ein Benutzer mit Audio interagiert, indem er z. B. Anhalten auswählt, sendet der Kanal einen Rückruf an den Bot mit einem JSON-Code, der in etwa wie folgt aussieht:

{
    ...
    "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. Eine Liste aller Medienereignisnamen finden Sie in der Tabelle unten.

Ereignis BESCHREIBUNG
media/next Der Client ist zu den nächsten Medien gesprungen.
media/pause Der Client hat die Wiedergabe von Medien unterbrochen.
media/play Der Client hat die Wiedergabe von Medien gestartet.
media/previous Der Client ist zu den vorherigen Medien gesprungen.
media/resume Der Client hat die Wiedergabe von Medien fortgesetzt.
media/stop Der Client hat die Wiedergabe von Medien angehalten.

Zusätzliche Ressourcen