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

Note

Die REST-API entspricht nicht dem SDK. Die REST-API wird bereitgestellt, um die standardmäßige REST-Kommunikation zuzulassen. Die bevorzugte Methode der Interaktion mit dem Bot Framework ist jedoch das SDK.

Innerhalb des Bot-Frameworks ermöglicht der Bot Connector-Dienst Ihrem Bot, Nachrichten mit Benutzern in Kanälen auszutauschen, die im Bot Framework-Portal konfiguriert sind. Der Dienst verwendet Branchenstandard-REST und JSON über HTTPS.

Basis-URL

Wenn ein Benutzer eine Nachricht an Ihren Bot sendet, enthält die eingehende Anforderung ein Aktivitätsobjekt mit einer serviceUrl Eigenschaft, die den Endpunkt angibt, an den Ihr Bot seine Antwort senden soll. Um auf den Bot Connector-Dienst zuzugreifen, verwenden Sie den serviceUrl Wert 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/ sie als Dienst-URL. Weitere Informationen finden Sie unter Erstellen einer Unterhaltung und einer proaktiven Nachricht in Teams.

Angenommen, Ihr Bot empfängt die folgende Aktivität, 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 der Basis-URI für alle nachfolgenden Anforderungen, die der Bot im Kontext dieser Unterhaltung ausgibt. Wenn Ihr Bot eine proaktive Nachricht an den Benutzer senden muss, achten Sie darauf, den Wert von serviceUrl.

Das folgende Beispiel zeigt die Anforderung, dass der Bot auf die Nachricht des Benutzers reagiert.

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

Headers

Anforderungsheader

Zusätzlich zu den standardmäßigen HTTP-Anforderungsheadern muss jede api-Anforderung, die Sie ausgeben, einen Authorization Header enthalten, der ein Zugriffstoken für die Authentifizierung Ihres Bots angibt. Geben Sie die Authorization Kopfzeile mit diesem 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 an den Bot Connector-Dienst.

Antwortkopfzeilen

Zusätzlich zu den standardmäßigen HTTP-Antwortheadern 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 das Problem nicht unabhängig beheben können, schließen Sie diesen Wert in die Informationen ein, 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 entsprechenden Anforderung an.

Note

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

HTTP-Statuscode	Bedeutung
200	Die Anfrage war erfolgreich.
201	Die Anfrage 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 anderweitig falsch.
401	Der Bot ist noch nicht authentifiziert.
403	Der Bot ist nicht berechtigt, den angeforderten Vorgang auszuführen.
404	Die angeforderte Ressource wurde nicht gefunden.
405	Der Kanal unterstützt den angeforderten Vorgang nicht.
500	Interner Serverfehler.
503	Der Dienst ist vorübergehend nicht verfügbar.

Errors

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

Unterhaltungsvorgänge

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

Important

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	Description
Unterhaltung erstellen	Erstellt eine neue Unterhaltung.
Aktivität löschen	Löscht eine vorhandene Aktivität.
Unterhaltungsmitglied löschen	Entfernt ein Mitglied aus einer Unterhaltung.
Abrufen von Aktivitätsmitgliedern	Ruft die Mitglieder der angegebenen Aktivität innerhalb der angegebenen Unterhaltung ab.
Unterhaltungsmitglied abrufen	Ruft Details zu einem Mitglied einer Unterhaltung ab.
Abrufen von Unterhaltungsmitgliedern	Ruft die Mitglieder der angegebenen Unterhaltung ab.
Unterhaltungsseitenmitglieder abrufen	Ruft die Mitglieder der angegebenen Unterhaltung jeweils eine Seite ab.
Abrufen von Unterhaltungen	Ruft eine Liste der Unterhaltungen 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.
Unterhaltungsverlauf senden	Lädt eine Transkription vergangener Aktivitäten in die Unterhaltung hoch.
An Unterhaltung senden	Sendet eine Aktivität (Nachricht) an das Ende der angegebenen Unterhaltung.
Updateaktivität	Aktualisiert eine vorhandene Aktivität.
Anlage in Kanal hochladen	Lädt eine Anlage direkt in den BLOB-Speicher eines Kanals hoch.

Unterhaltung erstellen

Erstellt eine neue Unterhaltung.

POST /v3/conversations

Content	Description
Anforderungstext	Ein ConversationParameters-Objekt
Rückgabe	Ein ConversationResourceResponse-Objekt

Aktivität löschen

In einigen Kanälen können Sie eine vorhandene Aktivität löschen. Bei erfolgreicher Ausführung entfernt dieser Vorgang die angegebene Aktivität aus der angegebenen Unterhaltung.

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

Content	Description
Anforderungstext	n/a
Rückgabe	Ein HTTP-Statuscode, der das Ergebnis des Vorgangs angibt. Im Textkörper der Antwort ist nichts angegeben.

Unterhaltungsmitglied löschen

Entfernt ein Mitglied aus einer Unterhaltung. Wenn dieses Mitglied das letzte Mitglied der Unterhaltung war, wird die Unterhaltung ebenfalls gelöscht.

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

Content	Description
Anforderungstext	n/a
Rückgabe	Ein HTTP-Statuscode, der das Ergebnis des Vorgangs angibt. Im Textkörper der Antwort ist 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

Content	Description
Anforderungstext	n/a
Rückgabe	Ein Array von ChannelAccount-Objekten

Abrufen von Unterhaltungen

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

GET /v3/conversations?continuationToken={continuationToken}

Content	Description
Anforderungstext	n/a
Rückgabe	Ein ConversationsResult-Objekt

Unterhaltungsmitglied abrufen

Ruft Details zu einem bestimmten Mitglied einer bestimmten Unterhaltung ab.

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

Content	Description
Anforderungstext	n/a
Rückgabe	Ein ChannelAccount-Objekt für das Element.

Mitglieder einer Konversation abrufen

Ruft die Mitglieder der angegebenen Unterhaltung ab.

GET /v3/conversations/{conversationId}/members

Content	Description
Anforderungstext	n/a
Rückgabe	Ein Array von ChannelAccount-Objekten für die Mitglieder der Unterhaltung.

Unterhaltungsseitenmitglieder abrufen

Ruft die Mitglieder der angegebenen Unterhaltung jeweils eine Seite ab.

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

Content	Description
Anforderungstext	n/a
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 sie 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}

Content	Description
Anforderungstext	Ein Activity-Objekt
Rückgabe	Ein ResourceResponse-Objekt

Unterhaltungsverlauf senden

Lädt eine Transkription früherer Aktivitäten in die Unterhaltung hoch, damit der Client sie rendern kann.

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

Content	Description
Anforderungstext	Ein Transkriptobjekt .
Rückgabe	Ein ResourceResponse-Objekt

An Unterhaltung senden

Sendet eine Aktivität (Nachricht) an die angegebene Unterhaltung. Die Aktivität wird gemäß dem Zeitstempel oder der Semantik des Kanals am Ende der Unterhaltung angefügt. Wenn Sie auf eine bestimmte Nachricht innerhalb der Unterhaltung antworten möchten, verwenden Sie stattdessen "Auf Aktivität antworten ".

POST /v3/conversations/{conversationId}/activities

Content	Description
Anforderungstext	Ein Activity-Objekt
Rückgabe	Ein ResourceResponse-Objekt

Updateaktivität

In einigen Kanälen können Sie eine vorhandene Aktivität bearbeiten, um den neuen Status einer Bot-Unterhaltung 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 erfolgreicher Ausführung aktualisiert dieser Vorgang die angegebene Aktivität innerhalb der angegebenen Unterhaltung.

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

Content	Description
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 BLOB-Speicher eines Kanals hoch. Auf diese Weise können Sie Daten in einem kompatiblen Speicher speichern.

POST /v3/conversations/{conversationId}/attachments

Content	Description
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.

Anlagenvorgänge

Verwenden Sie diese Vorgänge, um Informationen zu einer Anlage sowie die Binärdaten für die Datei selbst abzurufen.

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

Abrufen von Anlageninformationen

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

GET /v3/attachments/{attachmentId}

Content	Description
Anforderungstext	n/a
Rückgabe	Ein AttachmentInfo-Objekt

Anlage abrufen

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

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

Content	Description
Anforderungstext	n/a
Rückgabe	Binärer Inhalt, der die angegebene Ansicht der angegebenen Anlage darstellt

Statusvorgä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	Description
`Set User Data`	Speichert Statusdaten für einen bestimmten Benutzer in einem Kanal.
`Set Conversation Data`	Speichert Statusdaten für eine bestimmte Unterhaltung in einem Kanal.
`Set Private Conversation Data`	Speichert Statusdaten 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 Statusdaten 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	Description
Activity-Objekt	Definiert eine Nachricht, die zwischen Bot und Benutzer ausgetauscht wird.
AnimationCard-Objekt	Definiert eine Karte, die animierte GIFs 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. Audio, Video, Bild, Datei) oder eine Rich-Karte sein.
AttachmentData-Objekt	Beschreibt eine 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 Karte, die eine Audiodatei wiedergeben kann.
CardAction-Objekt	Definiert eine auszuführende Aktion.
CardImage-Objekt	Definiert ein Bild, das auf einer Karte 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 Mitglieder einer Unterhaltung.
ConversationParameters-Objekt	Definieren von Parametern zum Erstellen einer neuen Unterhaltung
ConversationReference-Objekt	Definiert einen bestimmten Punkt in einer Unterhaltung.
ConversationResourceResponse-Objekt	Definiert eine Antwort auf "Unterhaltung erstellen".
ConversationsResult-Objekt	Definiert das Ergebnis eines Anrufs zum Abrufen von Unterhaltungen.
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 eine Tatsache enthält.
GeoCoordinates-Objekt	Definiert einen geografischen Standort mithilfe von WSG84-Koordinaten (World Geodetic System).
HeroCard-Objekt	Definiert eine Karte mit großen Bild-, Titel-, Text- und Interaktiven Schaltflächen.
InnerHttpError-Objekt	Objekt, das einen inneren HTTP-Fehler darstellt.
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 der Mitglieder, die von get Conversation Paged Members zurückgegeben werden.
Place-Objekt	Definiert einen Ort, der in der Unterhaltung erwähnt wurde.
ReceiptCard-Objekt	Definiert eine Karte, die einen Beleg für einen Kauf enthält.
ReceiptItem-Objekt	Definiert eine Position innerhalb einer Quittung.
ResourceResponse-Objekt	Definiert eine Ressource.
SemanticAction-Objekt	Definiert einen Verweis auf eine programmgesteuerte Aktion.
SignInCard-Objekt	Definiert eine Karte, mit der sich ein Benutzer bei einem Dienst anmelden kann.
SuggestedActions-Objekt	Definiert die Optionen, aus denen ein Benutzer auswählen kann.
TextHighlight-Objekt	Bezieht sich auf eine Teilzeichenfolge von Inhalt innerhalb eines anderen Felds.
ThumbnailCard-Objekt	Definiert eine Karte mit einer Miniaturansicht, einem Titel, text und interaktiven Schaltflächen.
ThumbnailUrl-Objekt	Definiert die URL zur Quelle eines Bilds.
Transcript-Objekt	Eine Sammlung von Aktivitäten, die mit " Aufgezeichnete Unterhaltung senden" hochgeladen werden sollen.
VideoCard-Objekt	Definiert eine Karte, die Videos wiedergeben kann.

Activity-Objekt

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

Property	Typ	Description
action	String	Die anzuwendende Aktion oder die angewendet wurde. Verwenden Sie die Typeigenschaft , um den Kontext für die Aktion zu bestimmen. Wenn der Typ beispielsweise "contactRelationUpdate" lautet, würde der Wert der Aktionseigenschafthinzugefügt , wenn der Benutzer Ihren Bot zur Kontaktliste hinzugefügt oder entfernt hat, wenn er Ihren Bot aus der Kontaktliste entfernt hat.
attachmentLayout	String	Layout der Rich-Card-Anlagen , die die Nachricht enthält. Einer der folgenden Werte: Karussell, Liste. Weitere Informationen zu Rich-Card-Anlagen finden Sie unter Hinzufügen von Rich-Card-Anlagen zu Nachrichten.
Anhängsel	Anlage[]	Array von Attachment-Objekten , die zusätzliche Informationen definieren, die in die Nachricht eingeschlossen werden sollen. Jede Anlage kann entweder eine Datei (z. B. Audio, Video, Bild) oder eine umfangreiche Karte sein.
callerId	String	Eine Zeichenfolge, die einen IRI enthält, der den Aufrufer eines Bots identifiziert. Dieses Feld soll nicht über den Draht übertragen werden, sondern von Bots und Clients basierend auf kryptografisch überprüfbaren Daten gefüllt werden, die die Identität der Aufrufer (z. B. Token) bestätigen.
channel-Daten	Object	Ein Objekt, das kanalspezifische Inhalte enthält. Einige Kanäle stellen Features bereit, die zusätzliche Informationen erfordern, die nicht mithilfe des Anlagenschemas dargestellt werden können. Legen Sie diese Eigenschaft für diese Fälle auf den kanalspezifischen Inhalt fest, wie in der Dokumentation des Kanals definiert. Weitere Informationen finden Sie unter Implementieren kanalspezifischer Funktionen.
channelId (Kanal-ID)	String	Eine ID, die den Kanal eindeutig identifiziert. Vom Kanal festgelegt.
code	String	Code, der angibt, warum die Unterhaltung beendet wurde.
Konversation	ConversationAccount	Ein ConversationAccount -Objekt, das die Unterhaltung definiert, zu der die Aktivität gehört.
deliveryMode	String	Ein Übermittlungshinweis, der dem Empfänger alternative Übermittlungspfade für die Aktivität signalisiert. Einer der folgenden Werte: normal, Benachrichtigung.
Entitäten	Objekt[]	Array von Objekten, die die Entitäten darstellen, die in der Nachricht erwähnt wurden. Objekte in diesem Array können ein beliebiges Schema.org-Objekt sein. Beispielsweise kann das Array Erwähnungsobjekte 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	Der Zeitpunkt, zu dem die Aktivität als "abgelaufen" betrachtet werden sollte und dem Empfänger nicht angezeigt werden sollte.
from	ChannelAccount	Ein ChannelAccount-Objekt , das den Absender der Nachricht angibt.
historyDisclosed	Boolean	Kennzeichen, das angibt, ob der Verlauf offengelegt wird. Der Standardwert ist False.
id	String	ID, die die Aktivität im Kanal eindeutig identifiziert.
importance	String	Definiert die Wichtigkeit einer Aktivität. Einer der folgenden Werte: niedrig, normal, hoch.
inputHint	String	Wert, der angibt, ob Ihr Bot Benutzereingaben akzeptiert, erwartet oder ignoriert, nachdem die Nachricht an den Client übermittelt wurde. Einer der folgenden Werte: acceptingInput, expectingInput, ignoringInput.
label	String	Eine beschreibende Bezeichnung für die Aktivität.
listenFor	String[]	Liste der Ausdrücke und Verweise, auf die Sprach- und Sprachprimierungssysteme lauschen sollten.
Gebietsschema	String	Gebietsschema der Sprache, die verwendet werden soll, um Text in der Nachricht im Format `<language>-<country>`anzuzeigen. Der Kanal verwendet diese Eigenschaft, um die Sprache des Benutzers anzugeben, damit Ihr Bot möglicherweise Anzeigezeichenfolgen in dieser Sprache angeben kann. Der Standardwert ist en-US.
localTimestamp	String	Datum und Uhrzeit, zu der die Nachricht in der lokalen Zeitzone gesendet wurde, ausgedrückt im ISO-8601-Format .
localTimezone	String	Enthält den Namen der lokalen Zeitzone der Nachricht, ausgedrückt im IANA Time Zone-Datenbankformat. Beispiel: Amerika/Los_Angeles.
membersAdded	ChannelAccount[]	Array von ChannelAccount-Objekten , die die Liste der Benutzer darstellt, die der Unterhaltung beigetreten sind. Nur vorhanden, wenn der Aktivitätstyp "conversationUpdate" ist und Benutzer der Unterhaltung beigetreten sind.
membersRemoved	ChannelAccount[]	Array von ChannelAccount-Objekten , die die Liste der Benutzer darstellt, die die Unterhaltung verlassen haben. Nur vorhanden, wenn der Aktivitätstyp "conversationUpdate" lautet und Benutzer die Unterhaltung verlassen haben.
Name	String	Der Name des auszuführenden Vorgangs oder der Name des Ereignisses.
ReaktionenAdded	MessageReaction[]	Die Sammlung von Reaktionen, die der Unterhaltung hinzugefügt wurden.
ReaktionenRemoved	MessageReaction[]	Die Sammlung von Reaktionen, die aus der Unterhaltung entfernt wurden.
Empfänger	ChannelAccount	Ein ChannelAccount-Objekt , das den Empfänger der Nachricht angibt.
relatesTo	ConversationReference	Ein ConversationReference-Objekt , das einen bestimmten Punkt in einer Unterhaltung definiert.
replyToId	String	Die ID der Nachricht, auf die diese Nachricht antwortet. 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 zeitgeordnete Semantik (Zeitstempel), um die Nachricht an die Unterhaltung anzufügen.
semanticAction	SemanticAction	Ein SemanticAction -Objekt, das einen Verweis auf eine programmgesteuerte Aktion darstellt.
serviceUrl	String	URL, die den Dienstendpunkt des Kanals angibt. Vom Kanal festgelegt.
sprechen	String	Text, der von Ihrem Bot in einem sprachfähigen Kanal gesprochen werden soll. Wenn Sie verschiedene Merkmale der Spracherkennung Ihres Bots steuern möchten, z. B. Sprache, Rate, Lautstärke, Aussprache und Pitch, 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	Zusammenfassung der Informationen, die die Nachricht enthält. Bei einer Nachricht, die in einem E-Mail-Kanal gesendet wird, kann diese Eigenschaft beispielsweise die ersten 50 Zeichen der E-Mail-Nachricht angeben.
text	String	Text der Nachricht, die vom Benutzer an Bot oder Bot an den Benutzer gesendet wird. In der Dokumentation des Kanals finden Sie Beschränkungen, die für den Inhalt dieser Eigenschaft gelten.
textFormat	String	Format des Nachrichtentexts. Einer der folgenden Werte: markdown, plain, xml. Ausführliche Informationen zum Textformat finden Sie unter Erstellen von Nachrichten.
textHighlights	TextHighlight[]	Die Sammlung von Textfragmenten, die hervorgehoben werden sollen, wenn die Aktivität einen replyToId-Wert enthält.
timestamp	String	Datum und Uhrzeit, zu der die Nachricht in der UTC-Zeitzone gesendet wurde, ausgedrückt im ISO-8601-Format .
topicName	String	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. Ausführliche Informationen zu Aktivitätstypen finden Sie in der Spezifikation des Aktivitätsprotokolls.
Wert	Object	Wert mit offenem Ende.
valueType	String	Der Typ des Wertobjekts der Aktivität.

Property	Typ	Description
Aspekt	Boolean	Seitenverhältnis des Platzhalters für Miniaturansichten/Medien. Zulässige Werte sind "16:9" und "4:3".
autoloop	Boolean	Flag, das angibt, ob die Liste der animierten GIFs wiedergegeben werden soll, wenn die letzte endet. Legen Sie diese Eigenschaft auf "true" fest , damit die Animation automatisch wiedergegeben wird. andernfalls "false". Der Standardwert lautet true.
Autostart	Boolean	Flag, das angibt, ob die Animation automatisch wiedergegeben werden soll, wenn die Karte angezeigt wird. Legen Sie diese Eigenschaft auf "true" fest , um die Animation automatisch wiederzugeben. andernfalls "false". Der Standardwert lautet true.
Schaltflächen	CardAction[]	Array von CardAction-Objekten , mit denen der Benutzer eine oder mehrere Aktionen ausführen kann. Der Kanal bestimmt die Anzahl der Schaltflächen, die Sie angeben können.
duration	String	Die Länge des Medieninhalts im ISO 8601-Dauerformat.
image	ThumbnailUrl	Ein ThumbnailUrl -Objekt, das das Bild angibt, das auf der Karte angezeigt werden soll.
media	MediaUrl[]	Array von MediaUrl-Objekten . Wenn dieses Feld mehrere URLs enthält, ist jede URL ein alternatives Format desselben Inhalts.
Freigabefähig	Boolean	Flag, das angibt, ob die Animation für andere Personen freigegeben werden kann. Legen Sie diese Eigenschaft auf "true " fest, wenn die Animation freigegeben werden kann. andernfalls "false". Der Standardwert lautet true.
Untertitel	String	Untertitel, der unter dem Titel der Karte angezeigt werden soll.
text	String	Beschreibung oder Aufforderung zum Anzeigen unter dem Titel oder Untertitel der Karte.
Titel	String	Titel der Karte.
Wert	Object	Ergänzender Parameter für diese Karte.

Property	Typ	Description
Inhalt	Object	Der Inhalt der Anlage. Wenn es sich bei der Anlage um eine umfangreiche Karte handelt, 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 in der Anlage. Legen Sie diese Eigenschaft für Mediendateien auf bekannte Medientypen wie Bild/PNG, Audio/Wav und Video/mp4 fest. Legen Sie diese Eigenschaft für umfangreiche Karten auf einen der folgenden anbieterspezifischen Typen fest: application/vnd.microsoft.card.adaptive: Eine umfangreiche Karte, die eine beliebige Kombination aus Text, Sprache, Bildern, Schaltflächen und Eingabefeldern enthalten kann. Legen Sie die Inhaltseigenschaft auf ein AdaptiveCard-Objekt fest. application/vnd.microsoft.card.animation: Eine umfangreiche Karte, die Animationen wiedergibt. Legen Sie die Inhaltseigenschaft auf ein AnimationCard-Objekt fest. application/vnd.microsoft.card.audio: Eine umfangreiche Karte, die Audiodateien wiedergibt. Legen Sie die Inhaltseigenschaft auf ein AudioCard-Objekt fest. application/vnd.microsoft.card.hero: Eine Hero-Karte. Legen Sie die Inhaltseigenschaft auf ein HeroCard-Objekt fest. application/vnd.microsoft.card.receipt: Eine Belegkarte. Legen Sie die Inhaltseigenschaft auf ein ReceiptCard-Objekt fest. application/vnd.microsoft.card.signin: Eine Benutzeranmeldungskarte. Legen Sie die Inhaltseigenschaft auf ein SignInCard-Objekt fest. application/vnd.microsoft.card.thumbnail: Eine Miniaturansichtskarte. Legen Sie die Inhaltseigenschaft auf ein ThumbnailCard-Objekt fest. application/vnd.microsoft.card.video: Eine umfangreiche Karte, die Videos wiedergibt. Legen Sie die Inhaltseigenschaft auf ein VideoCard-Objekt fest.
contentUrl	String	URL für den Inhalt der Anlage. Wenn die Anlage beispielsweise ein Bild ist, 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	Name der Anlage.
thumbnailUrl	String	URL zu einem Miniaturbild, das der Kanal verwenden kann, wenn er eine alternative, kleinere Form von Inhalten oder contentUrl unterstützt. Wenn Sie contentType z. B. auf "application/word" festlegen und "contentUrl" auf den Speicherort des Word Dokuments festlegen, können Sie ein Miniaturbild einfügen, das das Dokument darstellt. Der Kanal könnte das Miniaturbild anstelle des Dokuments anzeigen. Wenn der Benutzer auf das Bild klickt, würde der Kanal das Dokument öffnen.

Property	Typ	Description
Größe	Nummer	Größe der Datei.
viewId	String	Ansichts-ID.

Property	Typ	Description
Aspekt	String	Seitenverhältnis der Miniaturansicht, die in der Bildeigenschaft angegeben ist. Gültige Werte sind 16:9 und 4:3.
autoloop	Boolean	Flag, das angibt, ob die Liste der Audiodateien wiedergegeben werden soll, wenn die letzte endet. Legen Sie diese Eigenschaft auf "true" fest , um die Audiodateien automatisch wiederzugeben. andernfalls "false". Der Standardwert lautet true.
Autostart	Boolean	Flag, das angibt, ob die Audiowiedergabe automatisch wiedergegeben werden soll, wenn die Karte angezeigt wird. Legen Sie diese Eigenschaft auf "true" fest , um die Audiowiedergabe automatisch wiederzugeben. andernfalls "false". Der Standardwert lautet true.
Schaltflächen	CardAction[]	Array von CardAction-Objekten , mit denen der Benutzer eine oder mehrere Aktionen ausführen kann. Der Kanal bestimmt die Anzahl der Schaltflächen, die Sie angeben können.
duration	String	Die Länge des Medieninhalts im ISO 8601-Dauerformat.
image	ThumbnailUrl	Ein ThumbnailUrl -Objekt, das das Bild angibt, das auf der Karte angezeigt werden soll.
media	MediaUrl[]	Array von MediaUrl-Objekten . Wenn dieses Feld mehrere URLs enthält, ist jede URL ein alternatives Format desselben Inhalts.
Freigabefähig	Boolean	Flag, das angibt, ob die Audiodateien für andere personen freigegeben werden können. Legen Sie diese Eigenschaft auf "true " fest, wenn die Audiodaten freigegeben werden können. andernfalls "false". Der Standardwert lautet true.
Untertitel	String	Untertitel, der unter dem Titel der Karte angezeigt werden soll.
text	String	Beschreibung oder Aufforderung zum Anzeigen unter dem Titel oder Untertitel der Karte.
Titel	String	Titel der Karte.
Wert	Object	Ergänzender Parameter für diese Karte.

Property	Typ	Description
channel-Daten	String	Kanalspezifische Daten, die mit dieser Aktion verbunden sind.
displayText	String	Text, der im Chatfeed angezeigt werden soll, wenn auf die Schaltfläche geklickt wird.
image	String	Bild-URL, die auf der Schaltfläche neben der Textbezeichnung angezeigt wird.
text	String	Text für die Aktion.
Titel	String	Textbeschreibung, die auf der Schaltfläche angezeigt wird.
type	String	Art der auszuführenden Aktion. Eine Liste der gültigen Werte finden Sie unter Hinzufügen von Rich-Card-Anlagen zu Nachrichten.
Wert	Object	Ergänzender Parameter für die Aktion. Das Verhalten dieser Eigenschaft variiert je nach Aktionstyp. Weitere Informationen finden Sie unter Hinzufügen von Rich-Card-Anlagen zu Nachrichten.

Property	Typ	Description
alt	String	Beschreibung des Bildes. Sie sollten die Beschreibung einschließen, um die Barrierefreiheit zu unterstützen.
Tippen Sie auf	CardAction	Ein CardAction-Objekt , das die auszuführende Aktion angibt, wenn der Benutzer auf das Bild tippt oder klickt.
url	String	URL zur Quelle des Bilds oder der Base64-Binärdatei des Bilds (z. B `data:image/png;base64,iVBORw0KGgo...`. ).

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

Property	Typ	Description
id	String	Die Unterhaltungs-ID.
Elemente	ChannelAccount[]	Liste der Mitglieder in dieser Unterhaltung.

Property	Typ	Description
Aktivität	Aktivität	Die erste Nachricht, die beim Erstellen an die Unterhaltung gesendet werden soll.
Bot	ChannelAccount	Kanalkontoinformationen, die zum Weiterleiten einer Nachricht an den Bot erforderlich sind.
channel-Daten	Object	Kanalspezifische Nutzlast zum Erstellen der Unterhaltung.
isGroup	Boolean	Gibt an, ob es sich um eine Gruppenunterhaltung handelt.
Elemente	ChannelAccount[]	Kanalkontoinformationen, die zum Weiterleiten einer Nachricht an jeden Benutzer erforderlich sind.
tenantId	String	Die Mandanten-ID, in der die Unterhaltung erstellt werden soll.
topicName	String	Thema der Unterhaltung. Diese Eigenschaft wird nur verwendet, wenn ein Kanal sie unterstützt.

Property	Typ	Description
activityId	String	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 (Kanal-ID)	String	Eine ID, die den Kanal in der Unterhaltung eindeutig identifiziert, auf die dieses Objekt verweist.
Konversation	ConversationAccount	Ein ConversationAccount -Objekt, das die Unterhaltung definiert, auf die dieses Objekt verweist.
serviceUrl	String	URL, die den Dienstendpunkt des Kanals in der Unterhaltung angibt, auf die dieses Objekt verweist.
user	ChannelAccount	Ein ChannelAccount-Objekt , das den Benutzer in der Unterhaltung identifiziert, auf die dieses Objekt verweist.

Property	Typ	Description
activityId	String	ID der Aktivität, falls gesendet.
id	String	ID der Ressource.
serviceUrl	String	Service-Endpunkt, an dem Operationen bezüglich der Konversation durchgeführt werden können.

Property	Typ	Description
Unterhaltungen	ConversationMembers[]	Die Mitglieder in den einzelnen Unterhaltungen.
continuationToken	String	Das Fortsetzungstoken, das in nachfolgenden Aufrufen von "Unterhaltungen abrufen" verwendet werden kann.

Property	Typ	Description
code	String	Fehlercode.
innerHttpError	InnerHttpError	Objekt, das den inneren HTTP-Fehler darstellt.
Nachricht	String	Eine Beschreibung des Fehlers.

Property	Typ	Description
Schlüssel	String	Name der Tatsache. Beispiel: Einchecken. Der Schlüssel wird beim Anzeigen des Faktenwerts als Beschriftung verwendet.
Wert	String	Wert der Tatsache. Beispiel: 10. Oktober 2016.

Property	Typ	Description
Erhöhung	Nummer	Erhöhung der Position.
latitude	Nummer	Breitengrad des Standorts.
longitude	Nummer	Längengrad des Standorts.
Name	String	Name des Speicherorts.
type	String	Der Typ dieses Objekts. Immer auf GeoCoordinates festgelegt.

Property	Typ	Description
statusCode	Nummer	HTTP-Statuscode aus der fehlgeschlagenen Anforderung.
Inhalt	Object	Der Textkörper der fehlgeschlagenen Anforderung.

Property	Typ	Description
profile	String	Hinweis, der den Inhalt der Medien beschreibt.
url	String	DIE URL zur Quelle der Mediendatei.

Property	Typ	Description
erwähnt	ChannelAccount	Ein ChannelAccount -Objekt, das den Benutzer oder den Bot angibt, der erwähnt wurde. Einige Kanäle, z. B. Slack, weisen Namen pro Unterhaltung zu, sodass es möglich ist, dass der erwähnte Name Ihres Bots (in der Empfängereigenschaft der Nachricht) möglicherweise von dem Handle abweicht, das Sie beim Registrieren Ihres Bots angegeben haben. Die Konto-IDs für beides wären jedoch identisch.
text	String	Der Benutzer oder Bot, wie in der Unterhaltung erwähnt. Wenn die Meldung beispielsweise "@ColorBot eine neue Farbe auswählen" lautet, wird diese Eigenschaft auf @ColorBot festgelegt. Nicht alle Kanäle legen diese Eigenschaft fest.
type	String	Der Typ dieses Objekts. Immer auf Erwähnung festgelegt.

Property	Typ	Description
address	Object	Adresse eines Orts. Diese Eigenschaft kann eine Zeichenfolge oder ein komplexes Objekt vom Typ "PostalAddress" sein.
Geo	GeoCoordinates	Ein GeoCoordinates-Objekt , das die geografischen Koordinaten des Ortes angibt.
hasMap	Object	Karte zum Ort. Diese Eigenschaft kann eine Zeichenfolge (URL) oder ein komplexes Objekt vom Typ Map sein.
Name	String	Name des Orts.
type	String	Der Typ dieses Objekts. Immer auf "Ort" festgelegt.

Property	Typ	Description
image	CardImage	Ein CardImage-Objekt , das miniaturansichtenbild angibt, das neben dem Zeilenelement angezeigt werden soll.
Preis	String	Eine währungsformatierte Zeichenfolge, die den Gesamtpreis aller erworbenen Einheiten angibt.
Menge	String	Eine numerische Zeichenfolge, die die Anzahl der erworbenen Einheiten angibt.
Untertitel	String	Untertitel, der unter dem Titel des Zeilenelements angezeigt werden soll.
Tippen Sie auf	CardAction	Ein CardAction - Objekt, das die auszuführende Aktion angibt, wenn der Benutzer auf das Zeilenelement tippt oder klickt.
text	String	Beschreibung des Zeilenelements.
Titel	String	Titel des Zeilenelements.

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

Basis-URL

Headers

Anforderungsheader

Antwortkopfzeilen

HTTP-Statuscodes

Errors

Unterhaltungsvorgänge

Unterhaltung erstellen

Aktivität löschen

Unterhaltungsmitglied löschen

Abrufen von Aktivitätsmitgliedern

Abrufen von Unterhaltungen

Unterhaltungsmitglied abrufen

Mitglieder einer Konversation abrufen

Unterhaltungsseitenmitglieder abrufen

Auf Aktivität antworten

Unterhaltungsverlauf senden

An Unterhaltung senden

Updateaktivität

Anlage in Kanal hochladen

Anlagenvorgänge

Abrufen von Anlageninformationen

Anlage abrufen

Statusvorgä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

Property	Typ	Description
Entitäten	Object	Ein Objekt, bei dem der Wert jeder Eigenschaft ein Entity-Objekt ist.
id	String	ID dieser Aktion.
Status	String	Status dieser Aktion. Zulässige Werte: start, continue, done.

Property	Typ	Description
Aktionen	CardAction[]	Array von CardAction-Objekten , die die vorgeschlagenen Aktionen definieren.
to	String[]	Array von Zeichenfolgen, die die IDs der Empfänger enthalten, für die die vorgeschlagenen Aktionen angezeigt werden sollen.

Property	Typ	Description
Vorkommen	Nummer	Vorkommen des Textfelds innerhalb des referenzierten Texts, falls vorhanden.
text	String	Definiert den Textausschnitt, der hervorgehoben werden soll.

Property	Typ	Description
Aspekt	String	Seitenverhältnis des Videos. Entweder 16:9 oder 4:3.
autoloop	Boolean	Flag, das angibt, ob die Liste der Videos wiedergegeben werden soll, wenn die letzte endet. Legen Sie diese Eigenschaft auf "true" fest , damit die Videos automatisch wiedergegeben werden. andernfalls "false". Der Standardwert lautet true.
Autostart	Boolean	Flag, das angibt, ob die Videos automatisch wiedergegeben werden sollen, wenn die Karte angezeigt wird. Legen Sie diese Eigenschaft auf "true" fest , um die Videos automatisch wiederzugeben. andernfalls "false". Der Standardwert lautet true.
Schaltflächen	CardAction[]	Array von CardAction-Objekten , mit denen der Benutzer eine oder mehrere Aktionen ausführen kann. Der Kanal bestimmt die Anzahl der Schaltflächen, die Sie angeben können.
duration	String	Die Länge des Medieninhalts im ISO 8601-Dauerformat.
image	ThumbnailUrl	Ein ThumbnailUrl -Objekt, das das Bild angibt, das auf der Karte angezeigt werden soll.
media	MediaUrl[]	Array von MediaUrl. Wenn dieses Feld mehrere URLs enthält, ist jede URL ein alternatives Format desselben Inhalts.
Freigabefähig	Boolean	Flag, das angibt, ob die Videos für andere personen freigegeben werden können. Legen Sie diese Eigenschaft auf "true " fest, wenn die Videos möglicherweise freigegeben werden. andernfalls "false". Der Standardwert lautet true.
Untertitel	String	Untertitel, der unter dem Titel der Karte angezeigt werden soll.
text	String	Beschreibung oder Aufforderung zum Anzeigen unter dem Titel oder Untertitel der Karte.
Titel	String	Titel der Karte.
Wert	Object	Ergänzender Parameter für diese Karte