Freigeben über

Arbeiten mit Microsoft Teams-Messaging-APIs in Microsoft Graph

Microsoft Graph bietet einen umfassenden Satz von Microsoft Teams-APIs, mit denen Sie Vorgänge für Teams-Nachrichten ausführen können. In diesem Artikel werden die primären Teams-API-Schemaelemente beschrieben und eine Übersicht über die APIs bereitgestellt, die basierend auf allgemeinen Szenarien verwendet werden können. Weitere Informationen zu Teams-APIs in Microsoft Graph finden Sie unter Verwenden des Microsoft Graph-API für die Arbeit mit Teams.

chatMessage-Schema

Der Ressourcentyp chatMessage stellt Nachrichten in Teams-Chats und -Kanälen dar. In diesem Abschnitt werden die Elemente des chatMessage-Schemas beschrieben.

Anmerkung: Die Beispiele in diesem Abschnitt zeigen nur die relevanten Schemaelemente und nicht die gesamte Nachrichtennutzlast.

Anlagen

Der Ressourcentyp chatMessageAttachment stellt Entitäten dar, auf die von einer chatMessage verwiesen werden kann. Zu diesen Entitäten gehören Dateien, Registerkarten, Karten, Besprechungen oder andere Nachrichten. Die Elemente selbst befinden sich möglicherweise an einer anderen Stelle. Beispielsweise können Dateien in SharePoint gespeichert werden. In den folgenden Abschnitten werden die möglichen Anlagentypen für ein chatMessage-Objekt beschrieben.

Karte Anlage

Karten stellen visuelle Elemente dar, die von einem vordefinierten Schema unterstützt werden. Teams unterstützt die vom Bot Framework definierten Karten zusätzlich zu den folgenden Karte Typen:

  • Codeausschnitt oder Platzhalter: Legen Sie contentType auf fest. application/vnd.microsoft.card.codesnippet
  • Ankündigungs-Karte : Festlegen von contentType aufapplication/vnd.microsoft.card.announcement
  • Microsoft Loop komponente Karte – contentType auf festlegenapplication/vnd.microsoft.card.fluidEmbedCard

Bei Karten wird die contentType-Eigenschaft auf den Typ der Karte festgelegt, und die inhaltseigenschaft enthält den serialisierten JSON-Code für die Karte.

Anmerkung: Aspekte von Karten wie Bildern können sich auf externe Ressourcen oder von Teams gehostete Ressourcen als chatMessageHostedContent beziehen.

Das folgende Beispiel zeigt das Schema für eine adaptive Karte Anlage. Dieses Karte verfügt über Images, die von Teams gehostet werden.

    "attachments": [
        {
            "id": "74d20c7f34aa4a7fb74e2b30004247c5",
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": "{  \"type\": \"AdaptiveCard\",  \"body\": [    {      \"items\": [        {          \"columns\": [            {              \"width\": \"auto\",              \"items\": [                {                  \"size\": \"medium\",                  \"url\": \"https://graph.microsoft.com/beta/teams/68a3e365-f7d9-4a56-b499-24332a9cc572/channels/19:0b50940236084d258c97b21bd01917b0@thread.skype/messages/1596694346004/hostedContents/aWQ9LHR5cGU9MSx1cmw9aHR0cHM6Ly91cy1hcGkuYXNtLnNreXBlLmNvbS92MS9vYmplY3RzLzAtd3VzLWQyLTUxZDYxNGE5MDQ5ZTU4MjFlMTRmMGI2NmExNmVlNzhlL3ZpZXdzL2ltZ28=/$value\",                  \"height\": \"auto\",                  \"type\": \"Image\"                },                {                  \"horizontalAlignment\": \"center\",                  \"text\": \"SHADES\",                  \"weight\": \"bolder\",                  \"type\": \"TextBlock\"                }              ],              \"type\": \"Column\"            },            {              \"width\": \"stretch\",              \"items\": [                {                  \"horizontalAlignment\": \"center\",                  \"text\": \"08/31/2019 19:30:00\",                  \"type\": \"TextBlock\"                },                {                  \"horizontalAlignment\": \"center\",                  \"text\": \"Final\",                  \"spacing\": \"None\",                  \"type\": \"TextBlock\"                },                {                  \"horizontalAlignment\": \"center\",                  \"size\": \"extraLarge\",                  \"text\": \"40 - 7\",                  \"type\": \"TextBlock\"                }              ],              \"spacing\": \"Medium\",              \"separator\": true,              \"type\": \"Column\"            },            {              \"width\": \"auto\",              \"items\": [                {                  \"horizontalAlignment\": \"center\",                  \"size\": \"medium\",                  \"url\": \"https://graph.microsoft.com/beta/teams/68a3e365-f7d9-4a56-b499-24332a9cc572/channels/19:0b50940236084d258c97b21bd01917b0@thread.skype/messages/1596694346004/hostedContents/aWQ9LHR5cGU9MSx1cmw9aHR0cHM6Ly91cy1hcGkuYXNtLnNreXBlLmNvbS92MS9vYmplY3RzLzAtd3VzLWQyLWM4NjgwMjMzMzcyMzc2MmQ0MWEyY2QxMGVhMWI4ZGRhL3ZpZXdzL2ltZ28=/$value\",                  \"height\": \"auto\",                  \"type\": \"Image\"                },                {                  \"horizontalAlignment\": \"center\",                  \"text\": \"SKINS\",                  \"weight\": \"bolder\",                  \"type\": \"TextBlock\"                }              ],              \"spacing\": \"Medium\",              \"separator\": true,              \"type\": \"Column\"            }          ],          \"type\": \"ColumnSet\"        }      ],      \"type\": \"Container\"    }  ],  \"speak\": \"The Seattle Seahawks beat the Carolina Panthers 40-7\",  \"$schema\": \"http://adaptivecards.io/schemas/adaptive-card.json\",  \"version\": \"1.2\"}",
            "name": null,
            "thumbnailUrl": null,
            "teamsAppId": null
        }
    ]

Für Nachrichten, die von einer Teams-App erstellt werden, z. B. über Messaging-Erweiterungen, enthält die eigenschaft teamsAppId die ID der App, die die Nachricht gesendet hat.

Das folgende Beispiel zeigt das Schema für eine adaptive Karte Anlage, wenn die Nachricht von einer Teams-App gesendet wurde.

    "attachments": [
        {
            "id": "f60e7358497741f5bdb5fa7f101fe425",
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": "{  \"type\": \"AdaptiveCard\",  \"body\": [    {      \"items\": [        {          \"items\": [],          \"type\": \"Container\"        },        {          \"altText\": \"Awesome\",          \"horizontalAlignment\": \"center\",          \"url\": \"https://dev.praise.myanalytics.cdn.office.net/2024.1.31.2/assets/emojis/Trophy_Icon.png\",          \"width\": \"82px\",          \"height\": \"auto\",          \"spacing\": \"small\",          \"type\": \"Image\"        },        {          \"size\": \"large\",          \"text\": \"Awesome\",          \"weight\": \"lighter\",          \"wrap\": true,          \"spacing\": \"large\",          \"type\": \"TextBlock\"        },        {          \"size\": \"large\",          \"text\": \"Test User 1\",          \"weight\": \"bolder\",          \"wrap\": true,          \"spacing\": \"none\",          \"type\": \"TextBlock\"        },        {          \"size\": \"small\",          \"text\": \"From Test User 2\",          \"wrap\": true,          \"spacing\": \"extraLarge\",          \"type\": \"TextBlock\"        },        {          \"items\": [],          \"spacing\": \"small\",          \"type\": \"Container\"        }      ],      \"backgroundImage\": {        \"url\": \"https://dev.praise.myanalytics.cdn.office.net/2024.1.31.2/assets/themes/CornflowerGradient.png\"      },      \"type\": \"Container\"    },    {      \"columns\": [        {          \"width\": \"stretch\",          \"items\": [            {              \"text\": \"**[Review your praise history](https://teams.microsoft.com/l/entity/57e078b5-6c0e-44a1-a83f-45f75b030d4a)**\",              \"wrap\": true,              \"spacing\": \"small\",              \"type\": \"TextBlock\"            }          ],          \"type\": \"Column\"        },        {          \"width\": \"auto\",          \"items\": [            {              \"horizontalAlignment\": \"right\",              \"text\": \"**[Send praise](https://teams.microsoft.com/l/task/d832a33f-28c2-4969-8ad0-4fee681dc5b4)**\",              \"spacing\": \"small\",              \"type\": \"TextBlock\"            }          ],          \"type\": \"Column\"        }      ],      \"spacing\": \"small\",      \"type\": \"ColumnSet\"    }  ],  \"speak\": \"Praise card sent from Test User 2 to Test User 1. Awesome, with message \",  \"version\": \"1.2\"}",
            "name": null,
            "thumbnailUrl": null,
            "teamsAppId": "d832a33f-28c2-4969-8ad0-4fee681dc5b4"
        }
    ]

Anmerkung: Microsoft Graph unterstützt nur Karten, für die die OpenUrl-Aktion festgelegt ist. Andere Aktionen wie ShowCard werden nicht unterstützt. Microsoft Graph lässt das Lesen von Nachrichten zu, die von Bots gepostet wurden, die andere Aktionen enthalten.

Das folgende Beispiel zeigt das Schema für eine Loop-Komponente als zwei Anlagen.

    "attachments": [
        {
            "id": "b21e256a-8581-45cf-ae05-8bb998360bcc",
            "contentType": "application/vnd.microsoft.card.fluidEmbedCard",
            "contentUrl": null,
            "content": "{\r\n  \"componentUrl\": \"https://teamsgraph-my.sharepoint.com/:fl:/g/personal/sumanac_teamsgraph_onmicrosoft_com/EQnofOQM0MpOoDaRIvw-pS8Bfsj_WDFuanBBXnjDAD-w3g?nav=cz0lMkZwZXJzb25hbCUyRnN1bWFuYWNfdGVhbXNncmFwaF9vbm1pY3Jvc29mdF9jb20mZD1iIWVUcmxYX19jN2t5eW9GSFhJdG8yTDI4bmtnV2EtOXhEa244SVBOdGZFYnlxandPblkwdE9TcFVldkh6dWtBV1ImZj0wMUU2TzQ0WFlKNUI2T0lER1FaSkhLQU5VUkVMNkQ1SkpQJmM9JTJGJmZsdWlkPTEmYT1UZWFtcyZwPSU0MGZsdWlkeCUyRmxvb3AtcGFnZS1jb250YWluZXI%3D\",\r\n  \"sourceType\": \"Compose\"\r\n}",
            "name": null,
            "thumbnailUrl": null,
            "teamsAppId": "FluidEmbedCard"
        },
        {
            "id": "placeholderCard",
            "contentType": "application/vnd.microsoft.card.codesnippet",
            "contentUrl": null,
            "content": "{}",
            "name": null,
            "thumbnailUrl": null,
            "teamsAppId": "FLUID_PLACEHOLDER_CARD"
        }
    ],

Dateianlage

Wenn ein Anlageobjekt auf eine Datei verweist, enthält es Informationen zur Datei, einschließlich des Links zum Öffnen der Datei. Die Datei selbst befindet sich in einem zugänglichen Speicher wie SharePoint. Wenn eine chatMessage über eine Anlage vom Typ Datei verfügt, wird der Wert der contentType-Eigenschaft für die Attachment-Ressource auf referencefestgelegt, und die contentUrl-Eigenschaft enthält die Datei-URL.

Anmerkung: Die SharePoint-URL ist der Link, über den die Datei geöffnet wird. dies ist nicht die Microsoft Graph-URL. Aufrufer können jedoch die API für den Zugriff auf freigegebene Elemente verwenden, um die Informationen zum Inhalt der Datei abzurufen.

Das folgende Beispiel zeigt das Schema für eine Dateianlage.

    "attachments": [
        {
            "id": "924D1F74-E0D2-4927-8A67-15ECEF455527",
            "contentType": "reference",
            "contentUrl": "https://testing.sharepoint.com/sites/Samples/Shared Documents/General/color.png",
            "content": null,
            "name": "color.png",
            "thumbnailUrl": null,
            "teamsAppId": null
        }
    ],

Weitergeleitete Nachrichtenanlage

Ein Anlageobjekt enthält eine weitergeleitete Nachricht, die an einen Chat weitergeleitet wurde. Bei Nachrichtenanlagen enthält die Id-Eigenschaft die ID der weitergeleiteten Nachricht. Die Inhaltseigenschaft enthält weitere Details zur Nachricht. Beispielsweise der ursprüngliche Nachrichtenkontext und das ursprüngliche Absenderdetail. Bei Nachrichtenanlagen ist die contentType-Eigenschaft auf forwardedMessageReferencefestgelegt.

Das folgende Beispiel zeigt das Schema für eine weitergeleitete Nachrichtenanlage.

    "attachments": [
        {
            "id": "1727881360458",
            "contentType": "forwardedMessageReference",
            "contentUrl": null,
            "content": "{\"originalMessageId\":\"1727881360458\",\"originalMessageContent\":\"\\n<p>hello</p>\\n\",\"originalConversationId\":\"19:97641583cf154265a237da28ebbde27a@thread.v2\",\"originalSentDateTime\":\"2024-10-02T15:02:40.458+00:00\",\"originalMessageSender\":{\"application\":null,\"device\":null,\"user\":{\"userIdentityType\":\"aadUser\",\"tenantId\":\"2432b57b-0abd-43db-aa7b-16eadd115d34\",\"id\":\"28c10244-4bad-4fda-993c-f332faef94f0\",\"displayName\":null}}}",
            "name": null,
            "thumbnailUrl": null,
            "teamsAppId": null
        }
    ],

Besprechungsanlage

Wenn eine Besprechung in einem Kanal geplant ist, wird eine Nachricht mit Besprechungsdetails im Kanal gepostet. Eine Besprechungsanlage stellt dieses Objekt dar und enthält die Besprechungsdetails. Die Id-Eigenschaft enthält die ID der Besprechung, und die Inhaltseigenschaft enthält Details zum Besprechungsorganisator und zur Exchange-ID der Besprechung. Sie können die Exchange-ID verwenden, um die Besprechung mithilfe der Kalender-APIs nachzuschlagen. Die contentType-Eigenschaft ist für Besprechungsanlagen auf meetingReference festgelegt.

Das folgende Beispiel zeigt das Schema für eine adaptive Karte Anlage.

    "attachments": [
        {
            "id": "1628156567881",
            "contentType": "meetingReference",
            "contentUrl": null,
            "content": "{\"exchangeId\":\"AAMkAGU2NzgzNDQ3LWFkMTctNGY2MC05ZjM1LWFkOTYxZWZhYTY2MgBGAAAAAADFwPNVvpzXRqmCO5F6qAKtBwB89fWKTP8MSaPLNsJWtozvAAAAAAENAAB89fWKTP8MSaPLNsJWtozvAAFg-8IoAAA=\",\"organizerId\":\"8ea0e38b-efb3-4757-924a-5f94061cf8c2\"}",
            "name": "Testing channel meeting",
            "thumbnailUrl": null
        }
    ],

Nachrichtenanlage

Ein Anlageobjekt enthält eine Nachricht, wenn ein Chat eine Antwort auf eine bestimmte Nachricht enthält. Bei Nachrichtenanlagen enthält die ID-Eigenschaft die ID der Nachricht. Die Inhaltseigenschaft enthält weitere Details zur Nachricht. Beispiel: Text und Absender der Nachrichtenvorschau. Bei Nachrichtenanlagen ist die contentType-Eigenschaft auf messageReferencefestgelegt.

Das folgende Beispiel zeigt das Schema für eine Nachrichtenanlage.

    "attachments": [
        {
            "id": "1622853091207",
            "contentType": "messageReference",
            "contentUrl": null,
            "content": "{\"messageId\":\"1622853091207\",\"messagePreview\":\"Testing unread read status\",\"messageSender\":{\"application\":null,\"device\":null,\"user\":{\"userIdentityType\":\"aadUser\",\"id\":\"8ea0e38b-efb3-4757-924a-5f94061cf8c2\",\"displayName\":\"Alex\"}}}",
            "name": null,
            "thumbnailUrl": null
        }
    ],

Tabstoppanlage

Wenn ein Anlageobjekt auf eine Registerkarte verweist, die im aktuellen Kontext gehostet wird, wird die contentType-Eigenschaft auf tabReferencefestgelegt, die id-Eigenschaft wird auf die ID der Registerkarte und die name-Eigenschaft auf den Namen der Registerkarte festgelegt. Dieses Szenario gilt häufig, wenn Registerkarten neu hinzugefügt werden.

Das folgende Beispiel zeigt das Schema für eine Registerkartenanlage.

"attachments": [
        {
            "id": "tab::d64ea8d0-8b63-4f53-9bf6-806648176968",
            "contentType": "tabReference",
            "contentUrl": null,
            "content": null,
            "name": "Bing",
            "thumbnailUrl": null,
            "teamsAppId": null
        }
    ],

body

Die body-Eigenschaft eines chatMessage-Objekts stellt den Text der Nachricht dar. Die body-Eigenschaft kann auf andere Elemente im Schema wie Erwähnungen oder Anlagen verweisen. Der Inhalt kann oder htmlseintext, wie durch die contentType-Eigenschaft des itemBody-Ressourcentyps angegeben.

Das chatMessage-Schema unterstützt die folgenden Nicht-HTML-Elemente, die teams auch unterstützt:

  • at : Ein Verweis auf eine chatMessageMention , die die Details eines Benutzers, einer Anwendung, eines Kanals, eines Teams oder eines Tags darstellt, das ist @mentioned.
  • attachment: Stellt die Position eines Anlagenverweises dar.
  • systemEventMessage: Wenn die inhaltseigenschaft der itemBody-Ressource auf <systemEventMessage/>festgelegt ist, stellt die Nachricht ein spezielles Ereignis dar. Weitere Informationen finden Sie unter Abrufen von Systemmeldungen.
  • emoji: Wenn der Nachrichtentext ein Emoji enthält, stellt das $"<emoji id="IdOfTheEmoji" alt="AlternateRepresentationOfEmoji" title="TitleOfEmoji"></emoji>" -Element die Eigenschaften eines Emojis dar:
    • id: Die ID des Emojis.
    • alt: Eine alternative Darstellung für das Emoji; Beispiel: Unicode.
    • title: Ein Titel für das Emoji.
  • customemoji: Wenn der Nachrichtentext ein benutzerdefiniertes Emoji enthält, stellt das $"<customemoji id="IdOfTheCustomEmoji" alt="AlternateRepresentationOfCustomEmoji" source="HostedContentOfCustomEmoji"></customemoji>" Element die Eigenschaften eines customemoji dar:
    • id: Die ID des benutzerdefinierten Emojis.
    • alt: Eine alternative Darstellung für das benutzerdefinierte Emoji; Beispielsweise der Name des benutzerdefinierten Emojis.
    • source: Der gehostete Inhalt des benutzerdefinierten Emojis, das der Nachricht zugeordnet ist.
  • codeblock: Wenn der Text der Nachricht einen Codeblock enthält, stellt das "<codeblock class=\"Json\"><code>Hello world</code></codeblock>" -Element die Eigenschaften eines Codeblocks dar.

Beispiel: Eine Meldung, dass @mentions ein Team

    "body": {
        "contentType": "html",
        "content": "<div><div><at id=\"0\">WebhookTesting</at>&nbsp;Hello team</div></div>"
    },
    "mentions": [
        {
            "id": 0,
            "mentionText": "WebhookTesting",
            "mentioned": {
                "application": null,
                "device": null,
                "user": null,
                "tag": null,
                "conversation": {
                    "id": "68a3e365-f7d9-4a56-b499-24332a9cc572",
                    "displayName": "WebhookTesting",
                    "conversationIdentityType": "team"
                }
            }
        }
    ],

Beispiel: Eine Nachricht mit einer Anlage

    "body": {
        "contentType": "html",
        "content": "Scheduled a meeting<attachment id=\"1628156567881\"></attachment>"
    },
    "attachments": [
        {
            "id": "1628156567881",
            "contentType": "meetingReference",
            "contentUrl": null,
            "content": "{\"exchangeId\":\"AAMkAGU2NzgzNDQ3LWFkMTctNGY2MC05ZjM1LWFkOTYxZWZhYTY2MgBGAAAAAADFwPNVvpzXRqmCO5F6qAKtBwB89fWKTP8MSaPLNsJWtozvAAAAAAENAAB89fWKTP8MSaPLNsJWtozvAAFg-8IoAAA=\",\"organizerId\":\"8ea0e38b-efb3-4757-924a-5f94061cf8c2\"}",
            "name": "Testing channel meeting",
            "thumbnailUrl": null
        }
    ],

Beispiel: Eine Nachricht mit einem Systemereignis

    "body": {
        "contentType": "html",
        "content": "<systemEventMessage/>"
    },
    "channelIdentity": {
        "teamId": "68a3e365-f7d9-4a56-b499-24332a9cc572",
        "channelId": "19:0b50940236084d258c97b21bd01917b0@thread.skype"
    },
    "attachments": [],
    "mentions": [],
    "reactions": [],
    "eventDetail": {
        "@odata.type": "#microsoft.graph.conversationMemberRoleUpdatedEventMessageDetail",
        "conversationMemberRoles": [],
        "conversationMemberUser": {
            "id": "c4aefc8e-f890-4aa6-b586-6cce899ff7f8",
            "displayName": null,
            "userIdentityType": "aadUser"
        },
        "initiator": {
            "application": null,
            "device": null,
            "user": {
                "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
                "displayName": null,
                "userIdentityType": "aadUser"
            }
        }
    }

Beispiel: Eine Nachricht mit einem Emoji

{
    "body": {
        "contentType": "html",
        "content": "<p><emoji id=\"smile\" alt=\"🙂\" title=\"Smile\"></emoji></p>"
    }
}

Beispiel: Eine Nachricht mit einem benutzerdefinierten Emoji

{
    "body": {
        "contentType": "html",
        "content": "<p><customemoji id=\"dGVzdHNjOzAtd3VzLWQyLTdiNWRkZGQ2ZGVjMDNkYzIwNTgxY2NkYTE1MmEyZTM4\" alt=\"testsc\" source=\"https://graph.microsoft.com/beta/chats/19:bcf84b15c2994a909770f7d05bc4fe16@thread.v2/messages/1706638496169/hostedContents/aWQ9LHR5cGU9MSx1cmw9aHR0cHM6Ly91cy1jYW5hcnkuYXN5bmNndy50ZWFtcy5taWNyb3NvZnQuY29tL3YxL29iamVjdHMvMC13dXMtZDItN2I1ZGRkZDZkZWMwM2RjMjA1ODFjY2RhMTUyYTJlMzgvdmlld3MvaW1ndDJfYW5pbQ==/$value\"></customemoji></p>"
    }
}

Beispiel: Eine Nachricht mit einem Codeblock

Anmerkung: Hervorgehobene Codeblöcke werden nicht unterstützt, wenn eine Nachricht mit einem Codeblock mithilfe des Microsoft Graph-API gesendet wird.

{
    "body": {
        "contentType": "html",
        "content": "\n<codeblock class=\"\"><code>Hello world</code></codeblock>"
    }
}

Beispiel: Eine Nachricht mit einem Codeblock mit sprachspezifischer Hervorhebung

{
    "body": {
        "contentType": "html",
        "content": "<p>&nbsp;</p>\n\n<codeblock class=\"Json\"><code>{<br> &nbsp;&nbsp; <span class=\"hljs-function\">\"body\"</span>:&nbsp;{<br> &nbsp;&nbsp; <span class=\"hljs-function\">\"contentType\"</span>:&nbsp;<span class=\"hljs-string\">\"html\"</span>,<br> &nbsp;&nbsp; <span class=\"hljs-function\">\"content\"</span>:&nbsp;<span class=\"hljs-string\">\"&lt;codeblock&gt;&lt;code&gt;Hello&nbsp;world&lt;/code&gt;&lt;/codeblock&gt;\"</span><br> &nbsp;&nbsp; }<br>}</code></codeblock>\n<p>&nbsp;</p>"
    }
}

channelIdentity

Wenn eine chatMessage in einem Kanal gesendet wird, enthält die channelIdentity-Eigenschaft Details zum Kanal. Dies schließt die ID des Kanals und des Teams ein. Diese Eigenschaft ist schreibgeschützt.

Das folgende Beispiel zeigt das Schema für eine channelIdentity in einer Nachricht.

    "channelIdentity": {
        "teamId": "68a3e365-f7d9-4a56-b499-24332a9cc572",
        "channelId": "19:0b50940236084d258c97b21bd01917b0@thread.skype"
    },

chatId

Wenn eine chatMessage in einem Chat gesendet wird, enthält die chatId-Eigenschaft die ID des Chats. Diese Eigenschaft ist schreibgeschützt.

Das folgende Beispiel zeigt das Schema für eine chatId.

"chatId": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",

createdDateTime

Die createdDateTime-Eigenschaft stellt den Zeitpunkt dar, zu dem die Nachricht auf dem Server erstellt wurde. Dieser Zeitstempel kann sich von dem Zeitpunkt unterscheiden, zu dem die Nachricht vom Aufrufer gesendet wurde. Der Server zeichnet nur den serverseitigen Zeitstempel auf. Diese Eigenschaft ist schreibgeschützt. Sie kann jedoch geschrieben werden, wenn Sie Nachrichten aus einem externen System importieren.

deletedDateTime

Wenn eine chatMessage gelöscht wird, enthält die deletedDateTime-Eigenschaft den Zeitpunkt, zu dem die Nachricht gelöscht wurde. Diese Eigenschaft ist schreibgeschützt.

Anmerkung: Gelöschte Nachrichten werden nicht immer von allen APIs zurückgegeben. Änderungsbenachrichtigungen geben immer Benachrichtigungen zu gelöschten Nachrichten zurück, wenn der changeType des Abonnements enthält deleted.

etag

Die etag-Eigenschaft stellt die Version der Nachricht dar. Alle Änderungen an der Nachricht (einschließlich Reaktionen und Bearbeitungen) ändern den etag-Wert der Nachricht. Diese Eigenschaft ist schreibgeschützt.

eventDetail

Falls vorhanden, stellt die eventDetails-Eigenschaft Details eines Ereignisses dar, das in einem Chat, in einem Kanal oder in einem Team aufgetreten ist. Beispielsweise das Hinzufügen neuer Mitglieder. Für Ereignisnachrichten ist die messageType-Eigenschaft der chatMessage auf systemEventMessagefestgelegt. Weitere Informationen finden Sie unter Abrufen von Systemmeldungen.

von

Die from-Eigenschaft stellt den Absender der Nachricht dar. Microsoft Teams unterstützt die folgenden Absendertypen.

  • Entra ID-Benutzer: Benutzer, die über eine gültige Entra-ID verfügen. Dies schließt Entra External ID Gäste und externe Zugriffsbenutzer ein.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht, die von einem Entra-ID-Benutzer gesendet wird.

    "from": {
    "application": null,
    "device": null,
    "user": {
        "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
        "displayName": "Alex Wilber",
        "userIdentityType": "aadUser"
    }
},

  • Anonyme Gäste: Benutzer, die über einen Teilnahmelink an einer Besprechung teilnehmen. Diese Benutzer geben einen Anzeigenamen an, wenn sie an der Besprechung teilnehmen. Sie haben keine dauerhafte Identität in Microsoft 365.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht, die von einem anonymen Gast gesendet wird.

    "from": {
    "application": null,
    "device": null,
    "user": {
        "id": "8578568e393e4ffe8763e0b7c3da01fe",
        "displayName": "Anon (Guest)",
        "userIdentityType": "anonymousGuest"
    }
},

  • Persönliche Microsoft-Kontobenutzer: Benutzer, die ihr persönliches Microsoft-Konto verwenden, um sich bei Teams anzumelden.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht, die von einem anonymen Gast gesendet wird.

    "from": {
    "application": null,
    "device": null,
    "user": {
        "id": "d78f5bc88c39f6b8",
        "displayName": "TFL 1017",
        "userIdentityType": "personalMicrosoftAccountUser"
    }
},

  • Skype-Benutzer: Skype-Benutzer (für Consumer). Weitere Informationen finden Sie unter Teams und Skype-Interoperabilität.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht, die von einem Skype-Benutzer gesendet wurde.

    "from": {
    "application": null,
    "device": null,
    "user": {
        "id": "alex1122",
        "displayName": "Alex",
        "userIdentityType": "skypeUser"
    }
},

  • Lokale Skype for Business-Benutzer: Benutzer, die das lokale Skype For Business-Angebot verwenden. Weitere Informationen finden Sie unter Teams und Skype for Business Koexistenz und Interoperabilität.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht, die von einem lokalen Skype for Business-Benutzer gesendet wurde.

    "from": {
    "application": null,
    "device": null,
    "user": {
        "id": "b0eddfe2-659b-437d-b289-cf55c8b3bb1d",
        "displayName": "Alex",
        "userIdentityType": "onPremiseAadUser"
    }
},

  • Bots: Über die Microsoft Bot Framework erstellte Konversationsbots.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht, die von einem Bot gesendet wird.

    "from": {
    "device": null,
    "user": null,
    "application": {
        "id": "358f0194-6b0e-4dd3-af35-c24fe8a9ec87",
        "displayName": "Flow",
        "applicationIdentityType": "bot"
    }
}

  • Ausgehende Webhooks: Ausgehende Webhooks ermöglichen Entwicklern das Erstellen einer kostengünstigen Lösung, die Bots ähnelt. Weitere Informationen finden Sie unter Erstellen ausgehender Webhooks.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht, die von einem Bot gesendet wird.

    "from": {
    "device": null,
    "user": null,
    "application": {
        "id": "22e50a9b-80cc-4eab-a092-ce64796d28d7",
        "displayName": "Custom bot",
        "applicationIdentityType": "outgoingWebhook"
    }
}

  • Connectors für Microsoft 365-Gruppen: Connectors ermöglichen das Senden von unidirektionalen Nachrichten an Teams. Weitere Informationen finden Sie unter Erstellen von Connectors für Microsoft 365-Gruppen.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht von einem Office 365 Connector.

    "from": {
    "device": null,
    "user": null,
    "application": {
        "id": "4c6cfc6e-cf78-44e8-87fd-bbb0efcad6a2",
        "displayName": "Bing News",
        "applicationIdentityType": "office365Connector"
    }
}

  • Email : Teams ermöglicht das Senden von E-Mails an Kanäle. Wenn der Benutzer nicht bekannt ist, wird die Identität des Absenders als E-Mail-Benutzer mit den Details der E-Mail angezeigt, die zum Senden der Nachricht verwendet wurde.

    Das folgende Beispiel zeigt die from-Eigenschaft für eine Nachricht, die von einem E-Mail-Benutzer gesendet wurde.

    "from": {
        "application": null,
        "device": null,
        "user": {
            "@odata.type": "#microsoft.graph.teamworkUserIdentity",
            "id": "testemailuser@outlook.com",
            "displayName": "Test User",
            "userIdentityType": "emailUser"
        }
    }

  • Azure Communication Services Benutzer: Wenn eine Nachricht von einem Azure Communication Services Benutzer gesendet wird, werden die Identitätsdetails des Absenders im Feld von dargestellt.

    Das folgende Beispiel zeigt die from-Eigenschaft eines E-Mail-Sendevorgangs eines Azure Communication Services Benutzers.

    "from": {
    "application": null,
    "device": null,
    "user": {
        "@odata.type": "#microsoft.graph.teamworkUserIdentity",
        "id": "8:acs:a04d09ad-aaa9-4e25-90de-475594b0fb52_00000006-96d3-711c-6a0b-343a0d000eb4",
        "displayName": null,
        "userIdentityType": "azureCommunicationServicesUser"
    }
}

Diese Eigenschaft ist schreibgeschützt. Sie können jedoch darauf schreiben, wenn Sie Nachrichten aus einem externen System importieren.

Anmerkung: Der Anzeigename ist nicht immer vorhanden.

id

Die id-Eigenschaft enthält eine eindeutige ID, die die Nachricht darstellt. Diese Eigenschaft ist schreibgeschützt.

Anmerkung: Die ID ist nur innerhalb eines bestimmten Bereichs eindeutig, z. B. in einem Chat oder Kanal. Unterschiedliche Nachrichten in Chats und Kanälen weisen möglicherweise dieselbe ID auf.

Wichtigkeit

Die importance-Eigenschaft stellt die Wichtigkeit der Nachricht dar. Im Folgenden sind die möglichen Werte aufgeführt:

  • normal
  • Hoch
  • dringend

Das folgende Beispiel zeigt eine Meldung, deren Wichtigkeit auf "Hoch" festgelegt ist.

"importance": "high",

lastEditedDateTime

Die lastEditedDateTime-Eigenschaft stellt den Zeitstempel dar, als die Nachricht vom Benutzer bearbeitet wurde. Dies wird in der Teams-Benutzeroberfläche mit dem Edited Flag dargestellt. Sie wird auf null festgelegt, wenn die Nachricht noch nie bearbeitet wurde.

lastModifiedDateTime

Die lastModifiedDateTime-Eigenschaft stellt den Zeitstempel dar, zu dem die Nachricht zuletzt geändert wurde. Dazu gehören Änderungen wie Reaktionen. Sowohl die Eigenschaften eTag als auch lastModifiedDateTime , wenn eine Nachricht geändert wird.

Erwähnungen

Die Mentions-Eigenschaft stellt Benutzer, Anwendungen (Bots, Webhooks), Kanäle, Teams oder Tags dar, die sind @mentioned.

Beispiel: Eine Nachricht, die ein @mentions anderer Benutzer angibt

    "body": {
        "contentType": "html",
        "content": "<div><div><div><div><at id=\"0\">Alex</at>&nbsp;Test123</div></div></div></div>"
    },
    "mentions": [
        {
            "id": 0,
            "mentionText": "Alex",
            "mentioned": {
                "application": null,
                "device": null,
                "conversation": null,
                "tag": null,
                "user": {
                    "id": "c27c1b19-3904-4822-9813-4f6bdaab2eae",
                    "displayName": "Alex",
                    "userIdentityType": "aadUser"
                }
            }
        }
    ],

Beispiel: Eine Nachricht, dass @mentions ein Bot

    "body": {
        "contentType": "html",
        "content": "<div><div><at id=\"0\">Power Automate</at> Learn more&nbsp;</div></div>"
    },
    "mentions": [
        {
            "id": 0,
            "mentionText": "Power Automate",
            "mentioned": {
                "device": null,
                "user": null,
                "conversation": null,
                "tag": null,
                "application": {
                    "id": "358f0194-6b0e-4dd3-af35-c24fe8a9ec87",
                    "displayName": "Power Automate",
                    "applicationIdentityType": "bot"
                }
            }
        }
    ],

Beispiel: Eine Meldung, dass @mentions ein Team

    "body": {
        "contentType": "html",
        "content": "<div><div><at id=\"0\">WebhookTesting</at>&nbsp;Hello team</div></div>"
    },
    "mentions": [
        {
            "id": 0,
            "mentionText": "WebhookTesting",
            "mentioned": {
                "application": null,
                "device": null,
                "user": null,
                "tag": null,
                "conversation": {
                    "id": "68a3e365-f7d9-4a56-b499-24332a9cc572",
                    "displayName": "WebhookTesting",
                    "conversationIdentityType": "team"
                }
            }
        }
    ],

Anmerkung:@mentions kann auch in Karten angezeigt werden.

messageType

Die messageType-Eigenschaft stellt den Typ der Nachricht dar. Im Folgenden sind die möglichen Werte aufgeführt:

  • message: Stellt nachrichten dar, die von Benutzern und Anwendungen gesendet werden.
  • systemEventMessage: Stellt von Teams gesendete Nachrichten mit Details zu verschiedenen Ereignissen wie dem Hinzufügen von Mitgliedern oder Löschen von Kanälen dar. Weitere Informationen finden Sie unter Abrufen von Systemmeldungen.

Die folgenden Werte werden derzeit nicht verwendet:

  • Typisierung
  • chatEvent

onBehalfOf

Die onBehalfOf-Eigenschaft stellt die Benutzerzuordnung für Nachrichten dar, die von einem Bot im Namen eines Benutzers gesendet werden. Weitere Informationen finden Sie unter Benutzerzuordnung für Bots-Nachrichten.

Das folgende Beispiel zeigt eine Nachricht, die von einem Bot im Namen eines Benutzers gesendet wurde.

"from": {
        "device": null,
        "user": null,
        "application": {
            "id": "8a34cb8d-65dc-44e2-8375-a2261d1f2a4b",
            "displayName": "PolicyMaker",
            "applicationIdentityType": "bot"
        }
    },
    "onBehalfOf": {
        "application": null,
        "device": null,
        "user": {
            "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
            "displayName": "Alex Wilber",
            "userIdentityType": "aadUser"
        }
    },

policyViolation

Wenn eine Nachricht gegen richtlinien zur Verhinderung von Datenverlust (Data Loss Prevention, DLP) verstößt, die vom Mandanten festgelegt wurden, kann ein Nachrichtenpatch mit den Details der Richtlinie aufgerufen werden, gegen die die Richtlinie verstoßen wurde. Dadurch wird die Nachricht auf der Teams-Benutzeroberfläche ausgeblendet. Die policyViolation-Eigenschaft stellt die Details der Richtlinie dar, die verletzt wurde, zusammen mit der Aktion.

Das folgende Beispiel zeigt eine Nachricht, die aufgrund einer Richtlinie blockiert wurde.

    "body": {
        "contentType": "text",
        "content": ""
    },
    "policyViolation": {
        "dlpAction": "blockAccess",
        "justificationText": null,
        "userAction": "none",
        "verdictDetails": "none",
        "policyTip": null
    },

Reaktionen

Die Reactions-Eigenschaft stellt Reaktionen anderer Benutzer auf die Nachricht dar, z. B. Likes. Jedes Element stellt Informationen über die Reaktion und den Benutzer dar, der reagiert hat.

Das folgende Beispiel zeigt eine Nachricht mit Reaktionen.

Anmerkung: Der Anzeigename ist nicht immer in der Benutzereigenschaft vorhanden.

{
    "reactions": [
        {
            "reactionType": "💯",
            "displayName": "Hundred points",
            "createdDateTime": "2022-01-18T23:41:57.573Z",
            "user": {
                "application": null,
                "device": null,
                "user": {
                    "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
                    "displayName": null,
                    "userIdentityType": "aadUser"
                }
            }
        }
    ]
}

Das folgende Beispiel zeigt eine Nachricht mit einer benutzerdefinierten Reaktion.

Hinweis:

  • Benutzerdefinierte Reaktionen sind nur auf dem /beta Endpunkt verfügbar.
  • Der Anzeigename ist für den Benutzer nicht immer vorhanden.
{
    "reactions": [
        {
            "reactionType": "custom",
            "displayName": "microsoft_teams",
            "reactionContentUrl": "https://graph.microsoft.com/beta/chats/19:bcf84b15c2994a909770f7d05bc4fe16@thread.v2/messages/1706763669648/hostedContents/aWQ9MC13dXMtZDExLTc3ZmI2NmY4MTMwMGI2OGEzYzRkOWUyNmU1YTc5ZmMyLHR5cGU9MSx1cmw9/$value",
            "createdDateTime": "2024-02-14T22:07:02.288Z",
            "user": {
                "application": null,
                "device": null,
                "user": {
                    "@odata.type": "#microsoft.graph.teamworkUserIdentity",
                    "id": "28c10244-4bad-4fda-993c-f332faef94f0",
                    "displayName": null,
                    "userIdentityType": "aadUser"
                }
            }
        }
    ]
}

replyToId

Die replyToId-Eigenschaft stellt die ID der Nachricht dar, auf die eine Nachricht in einer Antwortkette antwortet. Diese Eigenschaft ist nur für Kanalnachrichten festgelegt. Diese Eigenschaft ist schreibgeschützt.

Anmerkung: Zum Beantworten von Nachrichten in einem Chat wird ein Nachrichtenverweis verwendet.

subject

Die subject-Eigenschaft enthält den Betreff der Nachricht. Dies gilt nur für Nachrichten, die in einem Kanal gesendet werden.

webUrl

Die webUrl-Eigenschaft enthält eine URL, die auf die Nachricht in der Teams-Benutzeroberfläche verweist. Diese URL öffnet die Nachricht direkt in der Teams-Benutzeroberfläche in einem Browser.

Auswählen der richtigen API für Ihr Szenario

Die Auswahl der richtigen API ist für Sie unerlässlich, um die bestmögliche Erfahrung zu erstellen. Wenn Sie den richtigen Satz von APIs verwenden, stellen Sie auch sicher, dass Sie Daten ohne Drosselung abrufen können.

Die Messaging-APIs in Microsoft Graph sind drei:

  • APIs, die der Teams-Benutzeroberfläche zugeordnet sind. Alle Änderungen sind sofort sichtbar.
  • APIs, die Daten exportieren, die sich auf Benutzer und Teams konzentrieren. Es kann bis zu 24 Stunden dauern, bis Änderungen verfügbar sind.
  • Ändern Sie benachrichtigungsbasierte APIs, um in Echtzeit benachrichtigt zu werden.

Teams-APIs, die auf die Benutzeroberfläche ausgerichtet sind

APIs, die an der Teams-Benutzeroberfläche ausgerichtet sind, funktionieren auf ähnliche Weise wie die Teams-Benutzeroberfläche. Diese APIs werden für einmalige Synchronisierungen erstellt, um Nachrichten in einem bestimmten Kontext abzurufen. Diese APIs sind sehr leistungsfähig, und alle Änderungen (gesendete, bearbeitete oder gelöschte Nachrichten) sind sofort sichtbar.

Im Folgenden sind apIs aufgeführt, die auf die Benutzeroberfläche von Teams ausgerichtet sind:

Darüber hinaus agieren die folgenden APIs zusammen mit diesen APIs, um bestimmte Szenarien zu erfüllen, z. B. das Abrufen bestimmter Instanzen oder das Ändern der Reihenfolge des Durchlaufs.

APIs zum Exportieren von Daten aus Teams

APIs, die Daten exportieren, arbeiten in der Regel mit einer höheren Granularität als APIs, die auf die Benutzeroberfläche ausgerichtet sind. Diese APIs konzentrieren sich darauf, das Abrufen großer Datenmengen zu ermöglichen. Es kann eine Weile dauern (in bestimmten Fällen bis zu 24 Stunden), bis Daten synchronisiert und über diese APIs verfügbar werden.

Die folgenden APIs fallen in diese Kategorie:

Echtzeit-APIs

Echtzeit-APIs ermöglichen es einem Aufrufer, benachrichtigt zu werden, sobald eine Änderung vorgenommen wurde (Gesendete, bearbeitete, gelöschte Nachricht usw.). Diese APIs eignen sich für Echtzeitanwendungen wie das Rendern von Nachrichten außerhalb der Teams-Benutzeroberfläche. Darüber hinaus ermöglichen diese APIs die Erstellung von Abonnements und damit den Empfang großer Datenmengen ohne Drosselung. Weitere Informationen finden Sie unter Ändern von Benachrichtigungen für Channles und Chats.