API-Referenz für den Bot-Framework-Connector-Dienst

Artikel
12/27/2023

Hinweis

Die REST-API ist nicht gleichbedeutend mit dem SDK. Die REST-API wird bereitgestellt, um die standardmäßige REST-Kommunikation zu ermöglichen. Die bevorzugte Methode für die Interaktion mit dem Bot Framework ist jedoch das SDK.

Der Bot Connector-Dienst ermöglicht es Ihrem Bot, Nachrichten mit Benutzern über Kanäle auszutauschen, die im Bot Framework-Portal konfigurierten wurden. Der Dienst verwendet die Branchenstandards REST und JSON über HTTPS.

Basis-URI

Wenn ein Benutzer eine Nachricht an Ihren Bot sendet, enthält die eingehende Anforderung ein Activity-Objekt mit einer serviceUrl-Eigenschaft, die den Endpunkt angibt, an den Ihr Bot seine Antwort senden soll. Verwenden Sie für den Zugriff auf den Bot Connector-Dienst den Wert serviceUrl als Basis-URI für API-Anforderungen.

Wenn Sie noch keine Dienst-URL für den Kanal haben, verwenden Sie https://smba.trafficmanager.net/teams/ als Dienst-URL. Weitere Informationen finden Sie unter Erstellen einer Unterhaltung und einer proaktiven Nachricht in Teams.

Nehmen Sie zum Beispiel an, dass Ihr Bot die folgende Aktivität empfängt, wenn der Benutzer eine Nachricht an den Bot sendet.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams/",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

Die serviceUrl-Eigenschaft innerhalb der Nachricht des Benutzers gibt an, dass der Bot seine Antwort an den Endpunkt https://smba.trafficmanager.net/teams/ senden soll. Die Dienst-URL ist die Basis-URI für alle weiteren Anfragen, die der Bot im Rahmen dieser Konversation stellt. Wenn Ihr Bot eine proaktive Nachricht an den Benutzer senden muss, speichern Sie unbedingt den Wert von serviceUrl.

Das folgende Beispiel zeigt die Anforderung, die der Bot ausgibt, um auf die Nachricht des Benutzers zu antworten.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de...
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have several times available on Saturday!",
    "replyToId": "bf3cc9a2f5de..."
}

Kopfzeilen

Anforderungsheader

Zusätzlich zu den HTTP-Standardanforderungsheadern muss jede API-Anforderung, die Sie ausgeben, einen Authorization-Header enthalten, der ein Zugriffstoken für die Authentifizierung Ihres Bots angibt. Geben Sie den Authorization-Header im folgenden Format an:

Authorization: Bearer ACCESS_TOKEN

Ausführliche Informationen zum Abrufen eines Zugriffstokens für Ihren Bot finden Sie unter Authentifizieren von Anforderungen von Ihrem Bot mit dem Bot Connector-Dienst.

Antwortheader

Zusätzlich zu den HTTP-Standardantwortheadern enthält jede Antwort einen X-Correlating-OperationId-Header. Der Wert dieses Headers ist eine ID, die dem Bot-Framework-Protokolleintrag entspricht, der Details zur Anforderung enthält. Wenn Sie eine Fehlerantwort erhalten, sollten Sie den Wert dieses Headers erfassen. Wenn Sie nicht in der Lage sind, das Problem selbstständig zu lösen, nehmen Sie diesen Wert in die Informationen auf, die Sie dem Supportteam zur Verfügung stellen, wenn Sie das Problem melden.

HTTP-Statuscodes

Der HTTP-Statuscode, der mit jeder Antwort zurückgegeben wird, gibt das Ergebnis der entsprechende Anforderung an.

Hinweis

In der folgenden Tabelle werden die häufigsten HTTP-Statuscodes beschrieben. Einige Fehler werden vom Kanal generiert. Weitere Informationen finden Sie in der Entwicklerdokumentation des jeweiligen Kanals.

HTTP-Statuscode	Bedeutung
200	Die Anforderung war erfolgreich.
201	Die Anforderung war erfolgreich.
202	Die Anforderung wurde zur Verarbeitung akzeptiert.
204	Die Anforderung war erfolgreich, aber es wurden keine Inhalte zurückgegeben.
400	Die Anforderung war falsch formatiert oder auf andere Weise fehlerhaft.
401	Der Bot ist noch nicht authentifiziert.
403	Der Bot ist nicht autorisiert, den angeforderten Vorgang auszuführen.
404	Die angeforderte Ressource wurde nicht gefunden.
405	Die angeforderte Operation wird vom Kanal nicht unterstützt.
500	Interner Serverfehler.
503	Der Dienst ist vorübergehend nicht verfügbar.

Fehler

Jede Antwort, die einen HTTP-Statuscode im Bereich 4xx oder 5xx angibt, enthält ein ErrorResponse-Objekt im Text der Antwort, das Informationen zum Fehler bereitstellt. Wenn Sie eine Fehlerantwort im Bereich 4xx erhalten, überprüfen Sie das ErrorResponse-Objekt, um die Fehlerursache zu identifizieren und Ihr Problem zu beheben, bevor Sie die Anforderung erneut senden.

Konversationsvorgänge

Verwenden Sie diese Vorgänge, um Unterhaltung zu erstellen, Nachrichten (Aktivitäten) zu senden und den Inhalt von Unterhaltungen zu verwalten.

Wichtig

Nicht alle Kanäle unterstützen alle Endpunkte. Alle Kanäle sollten die Antwort auf den Aktivitätsendpunkt jedoch unterstützen.

Beispielsweise unterstützen nur Direct Line und Webchat den Endpunkt zum Abrufen von Unterhaltungen.

Vorgang	Beschreibung
Unterhaltung erstellen	Erstellt eine neue Unterhaltung.
Delete-Aktivität	Löscht eine vorhandene Aktivität.
Konversationsteilnehmer löschen	Entfernt einen Teilnehmer aus einer Konversation.
Aktivitätsmitgliedern abrufen	Ruft die Mitglieder der angegebenen Aktivität innerhalb der angegebenen Unterhaltung ab.
Konversationsteilnehmer abrufen	Ruft die Details zu einem Teilnehmer der Konversation ab.
Mitglieder der Unterhaltung abrufen	Ruft die Mitglieder der angegebenen Unterhaltung ab.
Mitglieder der Unterhaltung seitenweise abrufen	Ruft die Mitglieder der angegebenen Unterhaltung seitenweise ab.
Konversationen abrufen	Ruft eine Liste von Konversationen ab, an denen der Bot teilgenommen hat.
Auf Aktivität antworten	Sendet eine Aktivität (Nachricht) an die angegebene Unterhaltung als Antwort auf die angegebene Aktivität.
Konversationsverlauf senden	Lädt ein Transkript der letzten Aktivitäten in die Konversation hoch.
An Unterhaltung senden	Sendet eine Aktivität (Nachricht) an das Ende der angegebenen Unterhaltung.
Aktivität aktualisieren	Aktualisiert eine vorhandene Aktivität.
Anlage in Kanal hochladen	Lädt eine Anlage direkt in einen Blobspeicher eines Kanals hoch.

Unterhaltung erstellen

Erstellt eine neue Unterhaltung.

POST /v3/conversations

Inhalt	Beschreibung
Anforderungstext	Ein ConversationParameters-Objekt
Rückgabe	Ein ConversationResourceResponse-Objekt

Delete-Aktivität

Einige Kanäle ermöglichen das Löschen einer vorhandenen Aktivität. Bei Erfolg entfernt dieser Vorgang die angegebene Aktivität aus der angegebenen Unterhaltung.

DELETE /v3/conversations/{conversationId}/activities/{activityId}

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein HTTP-Statuscode, der das Ergebnis des Vorgangs angibt. Im Text der Antwort wird nichts angegeben.

Konversationsteilnehmer löschen

Entfernt einen Teilnehmer aus einer Konversation. Wenn dieser Teilnehmer der letzte Teilnehmer an der Konversation war, wird die Konversation ebenfalls gelöscht.

DELETE /v3/conversations/{conversationId}/members/{memberId}

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein HTTP-Statuscode, der das Ergebnis des Vorgangs angibt. Im Text der Antwort wird nichts angegeben.

Abrufen von Aktivitätsmitgliedern

Ruft die Mitglieder der angegebenen Aktivität innerhalb der angegebenen Unterhaltung ab.

GET /v3/conversations/{conversationId}/activities/{activityId}/members

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein Array von ChannelAccount-Objekten.

Konversationen abrufen

Ruft eine Liste von Konversationen ab, an denen der Bot teilgenommen hat.

GET /v3/conversations?continuationToken={continuationToken}

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein ConversationsResult-Objekt

Konversationsteilnehmer abrufen

Ruft Details zu einem bestimmten Teilnehmer einer bestimmten Konversation ab.

GET /v3/conversations/{conversationId}/members/{memberId}

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein ChannelAccount-Objekt für den Teilnehmer.

Abrufen von Mitgliedern einer Konversation

Ruft die Mitglieder der angegebenen Unterhaltung ab.

GET /v3/conversations/{conversationId}/members

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein Array mit ChannelAccount-Objekten für die Teilnehmer der Konversation.

Mitglieder der Unterhaltung seitenweise abrufen

Ruft die Mitglieder der angegebenen Unterhaltung seitenweise ab.

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein PagedMembersResult-Objekt

Auf Aktivität antworten

Sendet eine Aktivität (Nachricht) an die angegebene Unterhaltung als Antwort auf die angegebene Aktivität. Die Aktivität wird als Antwort auf eine andere Aktivität hinzugefügt, wenn der Kanal dies unterstützt. Wenn der Kanal keine geschachtelten Antworten unterstützt, verhält sich dieser Vorgang wie An Unterhaltung senden.

POST /v3/conversations/{conversationId}/activities/{activityId}

Inhalt	Beschreibung
Anforderungstext	Ein Activity-Objekt.
Rückgabe	Ein ResourceResponse-Objekt.

Aufgezeichnete Unterhaltungen senden

Lädt ein Transkript der letzten Aktivitäten in die Konversation hoch, sodass der Client sie rendern kann.

POST /v3/conversations/{conversationId}/activities/history

Inhalt	Beschreibung
Anforderungstext	Ein Transcript-Objekt.
Rückgabe	Ein ResourceResponse-Objekt.

An Unterhaltung senden

Sendet eine Aktivität (Nachricht) an die angegebene Unterhaltung. Die Aktivität wird am Ende der Unterhaltung gemäß dem Zeitstempel oder der Semantik des Kanals angefügt. Verwenden Sie zum Antworten auf eine bestimmte Nachricht in der Unterhaltung stattdessen Auf Aktivität antworten.

POST /v3/conversations/{conversationId}/activities

Inhalt	Beschreibung
Anforderungstext	Ein Activity-Objekt.
Rückgabe	Ein ResourceResponse-Objekt.

Update activity

Einige Kanäle ermöglichen das Bearbeiten einer vorhandenen Aktivität, um den neuen Zustand einer Botunterhaltung widerzuspiegeln. Beispielsweise können Sie Schaltflächen aus einer Nachricht in der Unterhaltung entfernen, nachdem der Benutzer auf eine der Schaltflächen geklickt hat. Bei Erfolg aktualisiert dieser Vorgang die angegebene Aktivität innerhalb der angegebenen Unterhaltung.

PUT /v3/conversations/{conversationId}/activities/{activityId}

Inhalt	Beschreibung
Anforderungstext	Ein Activity-Objekt.
Rückgabe	Ein ResourceResponse-Objekt.

Anlage in Kanal hochladen

Lädt eine Anlage für die angegebene Unterhaltung direkt in den Blobspeicher eines Kanals hoch. Auf diese Weise können Sie Daten in einem kompatiblen Speicher speichern.

POST /v3/conversations/{conversationId}/attachments

Inhalt	Beschreibung
Anforderungstext	Ein AttachmentData-Objekt.
Rückgabe	Ein ResourceResponse-Objekt. Die id-Eigenschaft gibt die Anlagen-ID an, die mit dem Vorgang Anlageninformationen abrufen und dem Vorgang Anlage abrufen verwendet werden kann.

Vorgänge für Anlagen

Verwenden Sie diese Vorgänge zum Abrufen von Informationen zu einer Anlage sowie für die Binärdaten für die Datei selbst.

Vorgang	Beschreibung
Anlageninformationen abrufen	Ruft Informationen zur angegebenen Anlage ab, einschließlich Dateiname, Dateityp und verfügbaren Ansichten (z. B. Originalansicht oder Miniaturansicht).
Anlage abrufen	Ruft die angegebene Ansicht der angegebenen Anlage als binären Inhalt ab.

Anlageninformationen abrufen

Ruft Informationen zur angegebenen Anlage ab, einschließlich Dateiname, Typ und verfügbaren Ansichten (z. B. Originalansicht oder Miniaturansicht).

GET /v3/attachments/{attachmentId}

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein AttachmentInfo-Objekt.

Anlagen abrufen

Ruft die angegebene Ansicht der angegebenen Anlage als binären Inhalt ab.

GET /v3/attachments/{attachmentId}/views/{viewId}

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Binärer Inhalt, der die angegebene Ansicht der angegebenen Anlage darstellt.

Zustandsvorgänge (veraltet)

Der Microsoft Bot Framework-Zustandsdienst wurde am 30. März 2018 außer Betrieb genommen. Zuvor verfügten auf Azure KI Bot Service oder auf dem Bot Builder SDK basierende Bots über eine Standardverbindung mit diesem von Microsoft gehosteten Dienst zum Speichern von Botzustandsdaten. Bots müssen aktualisiert werden, um einen eigenen Zustandsspeicher zu verwenden.

Vorgang	Beschreibung
`Set User Data`	Speichert Zustandsdaten für einen bestimmten Benutzer in einem Kanal.
`Set Conversation Data`	Speichert Zustandsdaten für eine bestimmte Unterhaltung in einem Kanal.
`Set Private Conversation Data`	Speichert Zustandsdaten für einen bestimmten Benutzer im Kontext einer bestimmten Unterhaltung in einem Kanal.
`Get User Data`	Ruft Zustandsdaten ab, die zuvor für einen bestimmten Benutzer in allen Unterhaltungen in einem Kanal gespeichert wurden.
`Get Conversation Data`	Ruft Zustandsdaten ab, die zuvor für eine bestimmte Unterhaltung in einem Kanal gespeichert wurden.
`Get Private Conversation Data`	Ruft Zustandsdaten ab, die zuvor für einen bestimmten Benutzer im Kontext einer bestimmten Unterhaltung in einem Kanal gespeichert wurden.
`Delete State For User`	Löscht Zustandsdaten, die zuvor für einen Benutzer gespeichert wurden.

Schema

Das Bot Framework-Schema definiert die Objekte und deren Eigenschaften, die Ihr Bot für die Kommunikation mit einem Benutzer verwenden kann.

Object	Beschreibung
Activity-Objekt	Definiert eine Nachricht, die zwischen Bot und Benutzer ausgetauscht wird.
AnimationCard-Objekt	Definiert eine Rich Card, die animierte GIF-Dateien oder kurze Videos wiedergeben kann.
Attachment-Objekt	Definiert zusätzliche Informationen, die in die Nachricht eingeschlossen werden sollen. Eine Anlage kann eine Mediendatei (z. B. eine Audio-, Video- oder Bilddatei) oder eine Rich Card sein.
AttachmentData-Objekt	Beschreibt Anlagendaten.
AttachmentInfo-Objekt	Beschreibt eine Anlage.
AttachmentView-Objekt	Definiert ein Objekt, das eine verfügbare Ansicht für eine Anlage darstellt.
AudioCard-Objekt	Definiert eine Rich Card, die eine Audiodatei wiedergeben kann.
CardAction-Objekt	Definiert eine auszuführende Aktion.
CardImage-Objekt	Definiert ein Bild, das auf einer Rich Card angezeigt werden soll.
ChannelAccount-Objekt	Definiert einen Bot oder ein Benutzerkonto im Kanal.
ConversationAccount-Objekt	Definiert eine Unterhaltung in einem Kanal.
ConversationMembers-Objekt	Definiert die Teilnehmer einer Konversation.
ConversationParameters-Objekt	Definieren von Parametern zum Erstellen einer neuen Unterhaltung
ConversationReference-Objekt	Definiert einen bestimmten Zeitpunkt in einer Unterhaltung.
ConversationResourceResponse-Objekt	Definiert eine Antwort auf Konversation erstellen.
ConversationsResult-Objekt	Definiert das Ergebnis eines Aufrufs von Konversationen abrufen.
Entity-Objekt	Definiert ein Entitätsobjekt.
Error-Objekt	Definiert einen Fehler.
ErrorResponse-Objekt	Definiert eine HTTP-API-Antwort.
Fact-Objekt	Definiert ein Schlüssel-Wert-Paar, das einen Fakt enthält.
Geocoordinates-Objekt	Definiert einen geografischen Standort mithilfe von WSG84-Koordinaten (World Geodetic System).
HeroCard-Objekt	Definiert eine Rich Card mit einem großen Bild, Titel, Text und Aktionsschaltflächen.
InnerHttpError-Objekt	Stellt einen internen HTTP-Fehler dar.
MediaEventValue-Objekt	Zusätzlicher Parameter für Medienereignisse.
MediaUrl-Objekt	Definiert die URL zur Quelle einer Mediendatei.
Mention-Objekt	Definiert einen Benutzer oder Bot, der in der Unterhaltung erwähnt wurde.
MessageReaction-Objekt	Definiert eine Reaktion auf eine Nachricht.
PagedMembersResult-Objekt	Seite mit Mitgliedern, die durch Mitglieder der Unterhaltung seitenweise abrufen zurückgegeben wurden.
Place-Objekt	Definiert einen Ort, der in der Unterhaltung erwähnt wurde.
ReceiptCard-Objekt	Definiert eine Rich Card, die eine Quittung für einen Kauf enthält.
ReceiptItem-Objekt	Definiert eine Position in einer Quittung.
ResourceResponse-Objekt	Definiert eine Ressource.
SemanticAction-Objekt	Definiert einen Verweis auf eine programmgesteuerte Aktion.
SignInCard-Objekt	Definiert eine Rich Card, die es einem Benutzer ermöglicht, sich bei einem Dienst anzumelden.
SuggestedActions-Objekt	Definiert die Optionen, unter denen ein Benutzer auswählen kann.
TextHighlight-Objekt	Verweist auf eine Teilzeichenfolge des Inhalts eines anderen Felds.
ThumbnailCard-Objekt	Definiert eine Rich Card mit einem Miniaturbild, Titel, Text und Aktionsschaltflächen.
ThumbnailUrl-Objekt	Definiert die URL zur Quelle eines Bilds.
Transcript-Objekt	Eine Sammlung von Aktivitäten, die mithilfe von Konversationsverlauf senden hochgeladen werden.
VideoCard-Objekt	Definiert eine Rich Card, die Videos wiedergeben kann.

Activity-Objekt

Definiert eine Nachricht, die zwischen Bot und Benutzer ausgetauscht wird.

Eigenschaft	Typ	Beschreibung
action	String	Die anzuwendende Aktion oder die Aktion, die angewendet wurde. Verwenden Sie die type-Eigenschaft, um den Kontext für die Aktion zu ermitteln. Wenn beispielsweise typecontactRelationUpdate ist, wäre der Wert der action-Eigenschaft add, wenn der Benutzer Ihren Bot seiner Kontaktliste hinzugefügt hat, oder remove, wenn er Ihren Bot aus seiner Kontaktliste entfernt hat.
attachmentLayout	String	Das Layout der Rich Card-Anlagen, die die Nachricht enthält. Einer der folgenden Werte: carousel, list. Weitere Informationen zu Rich Card-Anlagen finden Sie unter Hinzufügen von Rich Card-Anlagen zu Nachrichten.
attachments	Attachment[]	Ein Array von Attachment-Objekten, die zusätzliche Informationen definieren, die in die Nachricht eingeschlossen werden sollen. Jede dieser Anlagen kann eine Mediendatei (z. B. eine Audio-, Video- oder Bilddatei) oder eine Rich Card sein.
callerId	String	Eine Zeichenfolge mit einem IRI-Wert, der den Aufrufer eines Bots identifiziert. Dieses Feld ist nicht für die Übertragung vorgesehen, sondern wird stattdessen durch Bots und Clients auf der Grundlage kryptografisch verifizierbarer Daten aufgefüllt, die die Identität der Aufrufer bestätigen (beispielsweise Token).
Kanaldaten	Object	Ein Objekt mit kanalspezifischem Inhalt. Einige Kanäle stellen Funktionen bereit, für die zusätzliche Informationen erforderlich sind, die mit dem Anlagenschema nicht dargestellt werden können. Legen Sie für diese Fälle diese Eigenschaft auf den kanalspezifischen Inhalt fest, wie in der Dokumentation des Kanals definiert. Weitere Informationen finden Sie unter Implementieren von kanalspezifischer Funktionalität.
channelId	String	Eine ID, die den Kanal eindeutig identifiziert. Wird vom Kanal festgelegt.
code	String	Code, der angibt, warum die Unterhaltung beendet wurde.
Unterhaltung	ConversationAccount	Ein ConversationAccount-Objekt, das die Unterhaltung definiert, zu der die Aktivität gehört.
deliveryMode	String	Ein Übermittlungshinweis, um den Empfänger über alternative Übermittlungspfade für die Aktivität zu informieren. Einer der folgenden Werte: normal, notification.
entities	object[]	Ein Array von Objekten, das die Entitäten darstellt, die in der Nachricht erwähnt wurden. Objekte in diesem Array können ein beliebiges Schema.org-Objekt sein. Zum Beispiel kann das Array Mention-Objekte enthalten, die jemanden identifizieren, der in der Unterhaltung erwähnt wurde, und Place-Objekte, die einen Ort identifizieren, der in der Unterhaltung erwähnt wurde.
expiration	String	Die Zeit, zu der die Aktivität als abgelaufen betrachtet und dem Empfänger nicht mehr angezeigt werden soll.
from	ChannelAccount	Ein ChannelAccount-Objekt, das den Absender der Nachricht angibt.
historyDisclosed	Boolean	Ein Flag, das angibt, ob der Verlauf offengelegt wird. Der Standardwert ist False.
id	String	Eine ID, die die Aktivität im Kanal eindeutig identifiziert.
importance	String	Definiert die Wichtigkeit einer Aktivität. Einer der folgenden Werte: low, normal, high.
inputHint	String	Ein Wert, der angibt, ob Ihr Bot Benutzereingaben akzeptiert, erwartet oder ignoriert, nachdem die Nachricht an den Client gesendet wurde. Einer der folgenden Werte: acceptingInput, expectingInput, ignoringInput.
label	String	Eine aussagekräftige Bezeichnung für die Aktivität.
listenFor	String[]	Liste mit Phrasen und Verweisen, auf die Sprach- und Sprachvorbereitungsdienste lauschen sollen.
locale	String	Das Gebietsschema der Sprache, die zum Anzeigen von Text in der Nachricht verwendet werden soll (im Format `<language>-<country>`). Der Kanal verwendet diese Eigenschaft, um die Sprache des Benutzers anzugeben, sodass Ihr Bot Anzeigezeichenfolgen in dieser Sprache angeben kann. Der Standardwert ist en-US.
localTimestamp	String	Datum und Uhrzeit des Sendens der Nachricht in der lokalen Zeitzone, ausgedrückt im ISO-8601-Format.
localTimezone	String	Enthält den Namen der lokalen Zeitzone der Nachricht, ausgedrückt im Format der IANA-Zeitzonendatenbank. Beispiel: America/Los_Angeles.
membersAdded	ChannelAccount[]	Ein Array von ChannelAccount-Objekten, das die Liste der Benutzer darstellt, die an der Unterhaltung teilgenommen haben. Nur vorhanden, wenn der type der Aktivität „conversationUpdate“ ist und Benutzer an der Unterhaltung teilgenommen haben.
membersRemoved	ChannelAccount[]	Ein Array von ChannelAccount-Objekten, das die Liste der Benutzer darstellt, die die Unterhaltung verlassen haben. Nur vorhanden, wenn der type der Aktivität „conversationUpdate“ ist und Benutzer die Unterhaltung verlassen haben.
name	String	Der Name des aufzurufenden Vorgangs oder der Name des Ereignisses.
reactionsAdded	MessageReaction[]	Die Auflistung von Reaktionen, die der Konversation hinzugefügt werden.
reactionsRemoved	MessageReaction[]	Die Auflistung von Reaktionen, die aus der Konversation entfernt werden.
recipient	ChannelAccount	Ein ChannelAccount-Objekt, das den Empfänger der Nachricht angibt.
relatesTo	ConversationReference	Ein ConversationReference-Objekt, das einen bestimmten Zeitpunkt in einer Unterhaltung definiert.
replyToId	String	Die ID der Nachricht, auf die diese Nachricht eine Antwort ist. Um auf eine Nachricht zu antworten, die der Benutzer gesendet hat, legen Sie diese Eigenschaft auf die ID der Nachricht des Benutzers fest. Nicht alle Kanäle unterstützen Threadantworten. In diesen Fällen ignoriert der Kanal diese Eigenschaft und verwendet zeitorientierte Semantik (Zeitstempel), um die Nachricht an die Konversation anzufügen.
semanticAction	SemanticAction	Ein SemanticAction-Objekt, das einen Verweis auf eine programmgesteuerte Aktion darstellt.
Dienst-URL	String	Die URL, die den Dienstendpunkt des Kanals angibt. Wird vom Kanal festgelegt.
speak	String	Text, der von Ihrem Bot in einem sprachaktivierten Kanal gesprochen werden soll. Um verschiedene Eigenschaften der Sprache Ihres Bots zu steuern (z.B. Stimme, Rate, Lautstärke, Aussprache und Tonhöhe), geben Sie diese Eigenschaft im SSML-Format (Speech Synthesis Markup Language) an.
suggestedActions	SuggestedActions	Ein SuggestedActions-Objekt, das die Optionen definiert, aus denen der Benutzer auswählen kann.
summary	String	Eine Zusammenfassung der Informationen, die die Nachricht enthält. Für eine Nachricht, die in einem E-Mail-Kanal gesendet wird, kann diese Eigenschaft z.B. die ersten 50 Zeichen der E-Mail-Nachricht angeben.
text	String	Der Text der Nachricht, die vom Benutzer an den Bot oder vom Bot an den Benutzer gesendet wird. In der Dokumentation des Kanals finden Sie die Einschränkungen, die für den Inhalt dieser Eigenschaft gelten.
textFormat	String	Das Format des text der Nachricht. Einer der folgenden Werte: markdown, plain, xml. Weitere Informationen zum Textformat finden Sie unter Erstellen von Nachrichten.
textHighlights	TextHighlight[]	Die Auflistung von Textfragmenten, die hervorgehoben werden sollen, wenn die Aktivität einen replyToId-Wert enthält.
timestamp	String	Datum und Uhrzeit des Sendens der Nachricht in der UTC-Zeitzone, ausgedrückt im ISO-8601-Format.
topicName	String	Das Thema der Unterhaltung, zu der die Aktivität gehört.
type	String	Aktivitätstyp Einer der folgenden Werte: message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. Weitere Informationen zu Aktivitätstypen finden Sie unter Aktivitäten: Überblick.
value	Object	Ein Wert mit unbestimmtem Ende.
valueType	String	Die Art des Wertobjekts der Aktivität.

Eigenschaft	Typ	Beschreibung
aspect	Boolean	Seitenverhältnis des Platzhalters für Miniaturansichten/Medien. Zulässige Werte: „16:9“ und „4:3“.
autoloop	Boolean	Ein Flag, das angibt, ob die Liste der animierte GIF-Dateien wiedergeben werden soll, nachdem die letzte Datei wiedergeben wurde. Legen Sie diese Eigenschaft auf TRUE fest, um die Animation automatisch wiederzugeben, andernfalls auf FALSE. Der Standardwert lautet true.
autostart	Boolean	Ein Flag, das angibt, ob die Animation automatisch wiedergegeben werden soll, wenn die Rich Card angezeigt wird. Legen Sie diese Eigenschaft auf TRUE fest, um die Animation automatisch wiederzugeben, andernfalls auf FALSE. Der Standardwert lautet true.
buttons	CardAction[]	Ein Array von CardAction-Objekten, das es dem Benutzer ermöglicht, mindestens eine Aktion auszuführen. Der Kanal bestimmt die Anzahl der Schaltflächen, die Sie angeben können.
duration	String	Die Länge des Medieninhalts im Format der Zeitspanne nach ISO 8601.
Abbildung	ThumbnailUrl	Ein ThumbnailUrl-Objekt, das das auf der Rich Card anzuzeigende Bild angibt.
media	MediaUrl[]	Array mit Objekten vom Typ MediaUrl. Wenn dieses Feld mehrere URLs enthält, ist jede URL ein alternatives Format des gleichen Inhalts.
shareable	Boolean	Ein Flag, das angibt, ob die Animation für andere Benutzer freigegeben werden kann. Legen Sie diese Eigenschaft auf TRUE fest, wenn die Animation freigegeben werden kann, andernfalls auf FALSE. Der Standardwert lautet true.
subtitle	String	Der Untertitel, der unter dem Titel der Rich Card angezeigt werden soll.
text	String	Eine Beschreibung oder Eingabeaufforderung, die unter dem Titel oder Untertitel der Rich Card angezeigt werden soll.
title	String	Der Titel der Rich Card.
value	Object	Zusätzlicher Parameter für diese Karte.

Eigenschaft	Typ	Beschreibung
content	Object	Der Inhalt der Anlage. Wenn die Anlage einer Rich Card ist, legen Sie diese Eigenschaft auf das Rich Card-Objekt fest. Diese Eigenschaft und die ContentUrl-Eigenschaft schließen sich gegenseitig aus.
contentType	String	Der Medientyp des Inhalts der Anlage. Legen Sie diese Eigenschaft für Mediendateien auf bekannten Medientypen fest, z.B. auf image/png, audio/wav und video/mp4. Legen Sie diese Eigenschaft für Rich Cards auf einen dieser anbieterspezifischen Typen fest: application/vnd.microsoft.card.adaptive: Rich Cards, die eine beliebige Kombination von Text, Sprache, Bildern, Schaltflächen und Eingabefeldern enthalten können. Legen Sie die content-Eigenschaft auf ein AdaptiveCard-Objekt fest. application/vnd.microsoft.card.animation: Eine Rich Card, die eine Animation wiedergibt. Legen Sie die content-Eigenschaft auf ein AnimationCard-Objekt fest. application/vnd.microsoft.card.audio: Eine Rich Card, die Audiodateien wiedergibt. Legen Sie die content-Eigenschaft auf ein AudioCard-Objekt fest. application/vnd.microsoft.card.hero: Eine Hero Card. Legen Sie die content-Eigenschaft auf ein HeroCard-Objekt fest. application/vnd.microsoft.card.receipt: Eine Receipt Card. Legen Sie die content-Eigenschaft auf ein ReceiptCard-Objekt fest. application/vnd.microsoft.card.signin: Eine Sign In Card eines Benutzers. Legen Sie die content-Eigenschaft auf ein SignInCard-Objekt fest. application/vnd.microsoft.card.thumbnail: Eine Thumbnail Card. Legen Sie die content-Eigenschaft auf ein ThumbnailCard-Objekt fest. application/vnd.microsoft.card.video: Eine Rich Card, die Videos wiedergibt. Legen Sie die content-Eigenschaft auf ein VideoCard-Objekt fest.
contentUrl	String	Die URL für den Inhalt der Anlage. Ist die Anlage beispielsweise ein Bild, können Sie contentUrl auf die URL festlegen, die den Speicherort des Bilds darstellt. Unterstützte Protokolle sind: HTTP, HTTPS, Datei und Daten.
name	String	Der Name der Anlage.
thumbnailUrl	String	Die URL zu einer Miniaturansicht, die der Kanal verwenden kann, wenn die Verwendung einer anderen, kleineren Form von content oder contentUrl unterstützt wird. Wenn Sie beispielsweise contentType auf application/word und contentUrl auf den Speicherort des Word-Dokuments festlegen, können Sie eine Miniaturansicht einfügen, die das Dokument darstellt. Der Kanal könnte die Miniaturansicht anstelle des Dokuments anzeigen. Klickt der Benutzer auf das Bild, öffnet der Kanal das Dokument.

Eigenschaft	Typ	Beschreibung
size	number	Die Größe der Datei.
viewId	String	Die Ansichts-ID.

Eigenschaft	Typ	Beschreibung
aspect	String	Das Seitenverhältnis der Miniaturansicht, das in der image-Eigenschaft angegeben wird. Gültige Werte: 16:9 und 4:3.
autoloop	Boolean	Ein Flag, das angibt, ob die Liste der Audiodateien wiedergeben werden soll, nachdem die letzte Datei wiedergeben wurde. Legen Sie diese Eigenschaft auf TRUE fest, um die Audiodateien automatisch wiederzugeben, andernfalls auf FALSE. Der Standardwert lautet true.
autostart	Boolean	Ein Flag, das angibt, ob die Audiodatei automatisch wiedergegeben werden soll, wenn die Rich Card angezeigt wird. Legen Sie diese Eigenschaft auf TRUE fest, um die Audiodatei automatisch wiederzugeben, andernfalls auf FALSE. Der Standardwert lautet true.
buttons	CardAction[]	Ein Array von CardAction-Objekten, das es dem Benutzer ermöglicht, mindestens eine Aktion auszuführen. Der Kanal bestimmt die Anzahl der Schaltflächen, die Sie angeben können.
duration	String	Die Länge des Medieninhalts im Format der Zeitspanne nach ISO 8601.
Abbildung	ThumbnailUrl	Ein ThumbnailUrl-Objekt, das das auf der Rich Card anzuzeigende Bild angibt.
media	MediaUrl[]	Array mit Objekten vom Typ MediaUrl. Wenn dieses Feld mehrere URLs enthält, ist jede URL ein alternatives Format des gleichen Inhalts.
shareable	Boolean	Ein Flag, das angibt, ob die Audiodateien für andere Benutzer freigegeben werden können. Legen Sie diese Eigenschaft auf TRUE fest, wenn die Audiodateien freigegeben werden können, andernfalls auf FALSE. Der Standardwert lautet true.
subtitle	String	Der Untertitel, der unter dem Titel der Rich Card angezeigt werden soll.
text	String	Eine Beschreibung oder Eingabeaufforderung, die unter dem Titel oder Untertitel der Rich Card angezeigt werden soll.
title	String	Der Titel der Rich Card.
value	Object	Zusätzlicher Parameter für diese Karte.

Eigenschaft	Typ	Beschreibung
Kanaldaten	String	Kanalspezifische Daten, die mit dieser Aktion verknüpft sind.
displayText	String	Der Text, der im Chatfeed angezeigt werden soll, wenn auf die Schaltfläche geklickt wird.
Abbildung	String	Die Bild-URL, die auf der Schaltfläche neben der Beschriftung angezeigt wird.
text	String	Der Text für die Aktion.
title	String	Die Textbeschreibung, die auf der Schaltfläche angezeigt wird.
type	String	Der Typ der auszuführenden Aktion. Eine Liste der gültigen Werte finden Sie unter Hinzufügen von Rich Card-Anlagen zu Nachrichten.
value	Object	Zusätzlicher Parameter für die Aktion. Das Verhalten dieser Eigenschaft ist abhängig vom Typ (type) der Aktion. Weitere Informationen finden Sie unter Hinzufügen von Rich Card-Anlagen zu Nachrichten.

Eigenschaft	Typ	Beschreibung
alt	String	Die Beschreibung des Bilds. Sie sollten die Beschreibung zur Unterstützung der Barrierefreiheit einschließen.
tap	CardAction	Ein CardAction-Objekt, das die auszuführende Aktion angibt, wenn der Benutzer auf das Bild tippt oder klickt.
url	String	Die URL zur Quelle des Bilds oder der base64-Binärdatei des Bilds (z.B. `data:image/png;base64,iVBORw0KGgo...`).

Eigenschaft	Typ	Beschreibung
aadObjectId	String	Die Objekt-ID dieses Kontos innerhalb der Microsoft Entra ID.
id	String	Eindeutige ID für den Benutzer oder den Bot in diesem Kanal
name	String	Anzeigename des Bots oder Benutzers
role	String	Rolle der Entität hinter dem Konto. Entweder user oder bot.

Eigenschaft	Typ	Beschreibung
id	String	Die Konversations-ID.
members	ChannelAccount[]	Die Liste der Konversationsmitglieder.

Eigenschaft	Typ	Beschreibung
activity	Aktivität	Die erste Nachricht, die bei der Erstellung an die Konversation gesendet werden soll.
bot	ChannelAccount	Kanalkontoinformationen erforderlich, um eine Nachricht an den Bot weiterzuleiten
Kanaldaten	Object	Kanalspezifische Nutzlast zum Erstellen der Konversation
isGroup	Boolean	Gibt an, ob es sich um eine Gruppenunterhaltung handelt.
members	ChannelAccount[]	Kanalkontoinformationen erforderlich, um eine Nachricht an jeden Benutzer weiterzuleiten
tenantId	String	Die Mandanten-ID, unter der die Konversation erstellt werden soll.
topicName	String	Das Thema der Konversation. Diese Eigenschaft wird nur verwendet, wenn sie von einem Kanal unterstützt wird.

Eigenschaft	Typ	Beschreibung
activityId	String	Die ID, die die Aktivität eindeutig identifiziert, auf die dieses Objekt verweist.
bot	ChannelAccount	Ein ChannelAccount-Objekt, das den Bot in der Unterhaltung identifiziert, auf die dieses Objekt verweist.
channelId	String	Die ID, die die Aktivität in der Unterhaltung eindeutig identifiziert, auf die dieses Objekt verweist.
Unterhaltung	ConversationAccount	Ein ChannelAccount-Objekt, das die Unterhaltung identifiziert, auf die dieses Objekt verweist.
Dienst-URL	String	Die URL, die den Dienstendpunkt des Kanals in der Unterhaltung angibt, auf die dieses Objekt verweist.
Benutzer	ChannelAccount	Ein ChannelAccount-Objekt, das den Benutzer in der Unterhaltung identifiziert, auf die dieses Objekt verweist.

Eigenschaft	Typ	Beschreibung
activityId	String	ID der Aktivitätsausführung, falls gesendet
id	String	Die ID der Ressource.
Dienst-URL	String	Dienstendpunkt, an dem unter Umständen Vorgänge für die Konversation ausgeführt werden

Eigenschaft	Typ	Beschreibung
Konversationen	ConversationMembers[]	Die Mitglieder in den einzelnen Konversationen.
fortsetzungsToken	String	Das Fortsetzungstoken, das bei nachfolgenden Aufrufen von Konversationen abrufen verwendet werden kann.

Eigenschaft	Typ	BESCHREIBUNG
code	String	Fehlercode
innerHttpError	InnerHttpError	Objekt, das den internen HTTP-Fehler darstellt.
Nachricht	String	Eine Beschreibung des Fehlers.

Eigenschaft	Typ	BESCHREIBUNG
key	String	Der Name des Fakts. Beispielsweise Check-in. Der Schlüssel wird beim Anzeigen des Werts des Fakts als Bezeichnung verwendet.
value	String	Der Wert des Fakts. Beispielsweise 10. Oktober 2016.

Eigenschaft	Typ	Beschreibung
elevation	number	Die Höhe des Standorts.
latitude	number	Der Breitengrad des Standorts.
longitude	number	Der Längengrad des Standorts.
name	String	Der Name des Standorts.
type	String	Der Typ dieses -Objekts. Wird immer auf GeoCoordinates festgelegt.

Eigenschaft	Typ	Beschreibung
statusCode	number	HTTP-Statuscode aus der nicht erfolgreichen Anforderung.
Text	Object	Text aus der nicht erfolgreichen Anforderung.

Eigenschaft	Typ	Beschreibung
profile	String	Ein Hinweis, der den Medieninhalt beschreibt.
url	String	Die URL zur Quelle der Mediendatei.

Eigenschaft	Typ	Beschreibung
mentioned	ChannelAccount	Ein ChannelAccount-Objekt, das den Benutzer oder Bot angibt, der erwähnt wurde. Einige Kanäle wie Slack weisen Namen pro Unterhaltung zu. Daher ist es möglich, dass der erwähnte Name Ihres Bots (in der Eigenschaft recipient der Nachricht) sich von dem Handle unterscheidet, das Sie angegeben haben, als Sie Ihren Bot registriert haben. Allerdings sind die Konto-IDs für beide Angaben identisch.
text	String	Der Benutzer oder Bot wie in der Unterhaltung erwähnt. Wenn die Nachricht z. B. "@ColorBot pick me a new color“ lautet, würde diese Eigenschaft auf @ColorBot festgelegt. Nicht alle Kanäle legen diese Eigenschaft fest.
type	String	Der Typ dieses Objekts. Immer auf Mention festgelegt.

Eigenschaft	Typ	Beschreibung
address	Object	Die Adresse eines Orts. Bei dieser Eigenschaft kann es sich um eine Zeichenfolge (string) oder um ein komplexes Objekt vom Typ PostalAddress handeln.
geo	GeoCoordinates	Ein GeoCoordinates-Objekt, das die geografischen Koordinaten des Orts angibt.
hasMap	Object	Eine Karte für den Ort. Bei dieser Eigenschaft kann es sich um eine URL-Zeichenfolge (string) oder um ein komplexes Objekt vom Typ Map handeln.
name	String	Der Name des Orts.
type	String	Der Typ dieses Objekts. Immer auf Place festgelegt.

Eigenschaft	Typ	Beschreibung
Abbildung	CardImage	Ein CardImage-Objekt, das die Miniaturansicht angibt, die neben der Position angezeigt werden soll.
price	String	Eine als Währung formatierte Zeichenfolge, die den Gesamtpreis aller erworbenen Einheiten angibt.
quantity	String	Eine numerische Zeichenfolge, die die Anzahl der erworbenen Einheiten angibt.
subtitle	String	Der Untertitel, der unter dem Titel der Position angezeigt werden soll.
tap	CardAction	Ein CardAction-Objekt, das die auszuführende Aktion angibt, wenn der Benutzer auf die Position tippt oder klickt.
text	String	Eine Beschreibung der Position.
title	String	Der Titel der Position.

Freigeben über

API-Referenz für den Bot-Framework-Connector-Dienst

Basis-URI

Kopfzeilen

Anforderungsheader

Antwortheader

HTTP-Statuscodes

Fehler

Konversationsvorgänge

Unterhaltung erstellen

Delete-Aktivität

Konversationsteilnehmer löschen

Abrufen von Aktivitätsmitgliedern

Konversationen abrufen

Konversationsteilnehmer abrufen

Abrufen von Mitgliedern einer Konversation

Mitglieder der Unterhaltung seitenweise abrufen

Auf Aktivität antworten

Aufgezeichnete Unterhaltungen senden

An Unterhaltung senden

Update activity

Anlage in Kanal hochladen

Vorgänge für Anlagen

Anlageninformationen abrufen

Anlagen abrufen

Zustandsvorgänge (veraltet)

Schema

Activity-Objekt

AnimationCard-Objekt

Attachment-Objekt

AttachmentData-Objekt

AttachmentInfo-Objekt

AttachmentView-Objekt

AudioCard-Objekt

CardAction-Objekt

CardImage-Objekt

ChannelAccount-Objekt

ConversationAccount-Objekt

ConversationMembers-Objekt

ConversationParameters-Objekt

ConversationReference-Objekt

ConversationResourceResponse-Objekt

ConversationsResult-Objekt

Entity-Objekt

Error-Objekt

ErrorResponse-Objekt

Fact-Objekt

GeoCoordinates-Objekt

HeroCard-Objekt

InnerHttpError-Objekt

MediaEventValue-Objekt

MediaUrl-Objekt

Mention-Objekt

MessageReaction-Objekt

PagedMembersResult-Objekt

Place-Objekt

ReceiptCard-Objekt

ReceiptItem-Objekt

ResourceResponse-Objekt

SemanticAction-Objekt

SignInCard-Objekt

SuggestedActions-Objekt

TextHighlight-Objekt

ThumbnailCard-Objekt

ThumbnailUrl-Objekt

Transcript-Objekt

VideoCard-Objekt

Zusätzliche Ressourcen

Eigenschaft	Typ	BESCHREIBUNG
entities	Object	Ein Objekt, bei dem der Wert jeder Eigenschaft ein Entity-Objekt ist.
id	String	Die ID dieser Aktion.
state	String	Der Zustand dieser Aktion. Zulässige Werte: start, continue, done.

Eigenschaft	Typ	Beschreibung
actions	CardAction[]	Ein Array von CardAction-Objekten, die die vorgeschlagenen Aktionen definieren.
to	String[]	Ein Array von Zeichenfolgen, das die IDs der Empfänger enthält, denen die vorgeschlagenen Aktionen angezeigt werden sollen.

Eigenschaft	Typ	Beschreibung
occurrence	number	Vorkommen des Textfelds innerhalb des referenzierten Texts, sofern mehrere Vorkommen vorhanden sind.
text	String	Definiert den hervorzuhebenden Textausschnitt.

Eigenschaft	Typ	Beschreibung
aspect	String	Das Seitenverhältnis des Videos. Entweder 16:9 oder 4:3.
autoloop	Boolean	Ein Flag, das angibt, ob die Liste der Videos wiedergeben werden soll, nachdem die letzte Datei wiedergeben wurde. Legen Sie diese Eigenschaft auf TRUE fest, um die Videos automatisch wiederzugeben, andernfalls auf FALSE. Der Standardwert lautet true.
autostart	Boolean	Ein Flag, das angibt, ob die Videos automatisch wiedergegeben werden sollen, wenn die Rich Card angezeigt wird. Legen Sie diese Eigenschaft auf TRUE fest, um die Videos automatisch wiederzugeben, andernfalls auf FALSE. Der Standardwert lautet true.
buttons	CardAction[]	Ein Array von CardAction-Objekten, das es dem Benutzer ermöglicht, mindestens eine Aktion auszuführen. Der Kanal bestimmt die Anzahl der Schaltflächen, die Sie angeben können.
duration	String	Die Länge des Medieninhalts im Format der Zeitspanne nach ISO 8601.
Abbildung	ThumbnailUrl	Ein ThumbnailUrl-Objekt, das das auf der Rich Card anzuzeigende Bild angibt.
media	MediaUrl[]	Array mit Objekten vom Typ MediaUrl. Wenn dieses Feld mehrere URLs enthält, ist jede URL ein alternatives Format des gleichen Inhalts.
shareable	Boolean	Ein Flag, das angibt, ob die Videos für andere Benutzer freigegeben werden können. Legen Sie diese Eigenschaft auf TRUE fest, wenn die Videos freigegeben werden können, andernfalls auf FALSE. Der Standardwert lautet true.
subtitle	String	Der Untertitel, der unter dem Titel der Rich Card angezeigt werden soll.
text	String	Eine Beschreibung oder Eingabeaufforderung, die unter dem Titel oder Untertitel der Rich Card angezeigt werden soll.
title	String	Der Titel der Rich Card.
value	Object	Zusätzlicher Parameter für diese Rich Card.