Recevez les notifications de modifications des messages de canaux et de conversations Teams à l’aide de Microsoft Graph

  • Article

Les notifications de modifications vous permettent de vous abonner aux modifications (créer, mettre à jour et supprimer) apportées aux messages de canal ou de conversation. Les notifications de modification fournissent un modèle de faible latence en vous permettant de gérer un abonnement. Vous pouvez également obtenir les données de ressource dans les notifications et ainsi éviter d’appeler l’API pour obtenir la charge utile.

Poursuivez avec cet article sur les scénarios de la ressource chatMessage dans le canal ou le contexte de conversation . Vous pouvez également découvrir les notifications de modification pour d’autres ressources Microsoft Teams.

Remarque

Si vous demandez un abonnement expirationDateTime supérieur à 1 heure à l’avenir, vous devez vous abonner aux notifications de cycle de vie en incluant une propriété lifecycleNotificationUrl dans votre demande d’abonnement. Sinon, votre demande d’abonnement échoue avec le message d’erreur suivant : lifecycleNotificationUrl est une propriété obligatoire pour la création d’abonnement sur cette ressource lorsque la valeur expirationDateTime est définie sur plus d’une heure.

S’abonner aux modifications au niveau du client

Pour suivre toutes les modifications liées aux messages dans un locataire, vous pouvez utiliser des abonnements au niveau du locataire pour les messages de canal et de conversation, en créant deux abonnements : un pour suivre tous les messages sur les canaux et un pour suivre tous les messages entre les conversations.

S’abonner aux messages sur tous les canaux

Pour recevoir les notifications de modification de tous les messages et réponses sur les canaux d’un client, abonnez-vous à /teams/getAllMessages. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

Remarque: cette API a des exigences de licences et de paiement. Il prend en charge paramètres de requêtemodel=A et model=B à la fois. Si aucun modèle n’est spécifié, le mode d’évaluation sera utilisé.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Non prise en charge.
Déléguée (compte Microsoft personnel) Non prise en charge.
Application ChannelMessage.Read.All

Exemple

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S'abonner aux messages de toutes les conversations

Pour recevoir les notifications de modification de tous les messages et réponses dans les conversations d’un client, abonnez-vous à /chats/getAllMessages. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

Remarque: cette API a des exigences de licences et de paiement. Il prend en charge paramètres de requêtemodel=A et model=B à la fois. Si aucun modèle n’est spécifié, le mode d’évaluation sera utilisé.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Non prise en charge.
Déléguée (compte Microsoft personnel) Non prise en charge.
Application Chat.Read.All

Exemple

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated,deleted",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Abonnement aux messages dans un canal

Pour suivre les messages et les réponses dans un canal, vous pouvez créer un abonnement aux notifications de modification au niveau du canal en vous abonnant à /teams/{team-id}/channels/{channel-id}/messages. Cette ressource prend en charge y compris les données de ressources dans la notification des modes délégué et application uniquement.

Les abonnements au niveau canal prennent également en charge la recherche basée sur les mots clés via le $searchparamètre de requête.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) ChannelMessage.Read.All
Déléguée (compte Microsoft personnel) Non prise en charge.
Application ChannelMessage.Read.Group*, ChannelMessage.Read.All

Remarque : les autorisations marquées d’un * sont prises en charge dans le cadre du consentement spécifique à la ressource.

Exemple 1: Abonnement à tous les messages (et réponses) dans un canal

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 2: Abonnement aux messages (et réponses) dans un canal contenant certains textes

La requête suivante envoie des messages qui contiennent Hello à l’abonné.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$search=Hello",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 3: Abonnement aux messages (et réponses) dans un canal sans données de ressource

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 4: Abonnement aux messages (et réponses) dans un canal mentionnant un utilisateur spécifique

Pour obtenir des notifications uniquement pour les messages où un utilisateur spécifique a été mentionné, vous pouvez spécifier l'ID de l'utilisateur (9a6eb4d1-826b-48b1-9627-b50836c8fee9 dans cet exemple) dans la requête.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Abonnement aux messages de conversations

Pour suivre les messages d’une conversation, vous pouvez créer un abonnement aux notifications de modification au niveau de la conversation en vous abonnant à /chats/{chat-id}/messages. Cette ressource prend en charge y compris les données de ressources dans la notification des modes délégué et application uniquement.

Les abonnements au niveau des conversations prennent également en charge la recherche basée sur les mots clés via le $searchparamètre de requête.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Chat.Read
Déléguée (compte Microsoft personnel) Non prise en charge.
Application ChatMessage.Read.Chat*, Chat.Read.All

Remarque : les autorisations marquées d’un * sont prises en charge dans le cadre du consentement spécifique à la ressource uniquement pour la version bêta actuellement.

Exemple 1: Abonnement aux messages de conversations

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 2: Abonnement aux messages de conversations contenant certains textes

La requête suivante envoie des messages qui contiennent Hello à l’abonné.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages?$search=Hello",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 3: Abonnement aux messages (et réponses) dans une conversation sans données de ressource

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 4 : Abonnement aux messages dans une conversation où un utilisateur spécifique est mentionné

Pour obtenir des notifications uniquement pour les messages dans lesquelles un utilisateur spécifique a été mentionné, vous pouvez spécifier l'ID de l'utilisateur (9a6eb4d1-826b-48b1-9627-b50836c8fee9 dans cet exemple) dans la requête.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S’abonner aux modifications au niveau de l’utilisateur

Pour suivre les messages dans toutes les conversations dont fait partie un utilisateur particulier, vous pouvez créer un abonnement aux notifications de modification au niveau de l’utilisateur en vous abonnant à /users/{user-id}/chats/getAllMessages. Cette ressource prend en charge y compris les données de ressources dans la notification des modes délégué et application uniquement.

Les abonnements de messagerie de conversation au niveau de l’utilisateur prennent également en charge la recherche basée sur les mots clés via le paramètre de requête $search.

Remarque: cette API a des exigences de licences et de paiement. Il prend en charge le paramètre de requête model=B. Si aucun modèle n’est spécifié, le mode d’évaluation sera utilisé.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Chat.Read, Chat.ReadWrite
Déléguée (compte Microsoft personnel) Non prise en charge.
Application Chat.Read.All, Chat.ReadWrite.All

Exemple : s’abonner à des messages dans toutes les conversations dont un utilisateur particulier fait partie

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated,deleted",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/{user-id}/chats/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S’abonner aux messages d’une conversation dans un locataire où une application Teams spécifique est installée

Pour obtenir des notifications de modification pour tous les messages entre les conversations dans un locataire où une application Teams spécifique est installée, abonnez-vous à /appCatalogs/teamsApps/{teams-app-id}/installedToChats/getAllMessages. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

Remarque: cette API a des exigences de licences et de paiement. Il prend en charge le paramètre de requête model=B. Si aucun modèle n’est spécifié, le mode d’évaluation sera utilisé.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Non prise en charge.
Déléguée (compte Microsoft personnel) Non prise en charge.
Application Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled

Exemple

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/appCatalogs/teamsApps/386bbcdb-1e1c-4f3f-b7d0-ad7b9ea6cf7c/installedToChats/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Charges utiles de notification

En fonction de votre abonnement, vous pouvez recevoir la notification avec ou sans les données de ressource. L’abonnement avec des données de ressource vous permet d’obtenir la charge utile du message ainsi que la notification, avec la suppression de la nécessité de rappeler pour obtenir le contenu.

Notifications avec des données de ressource

Pour les notifications avec des données de ressource, la charge utile se présente comme suit. Cette charge utile concerne un message envoyé dans une conversation.

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.chatMessage",
            "@odata.id": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Pour plus d’informations sur la validation des jetons et le déchiffrement de la charge utile, consultez Configurer des notifications de modification comprenant des données de ressource.

La charge utile de la notification déchiffrée se présente comme suit. La charge utile est conforme au schéma chatMessage. La charge utile est similaire à celle renvoyée par les opérations GET.

{
  "id": "1612289992105",
  "replyToId": null,
  "etag": "1612289992105",
  "messageType": "message",
  "createdDateTime": "2021-02-02T18:19:52Z",
  "lastModifiedDateTime": "2021-02-02T18:19:52.105Z",
  "lastEditedDateTime": null,
  "deletedDateTime": null,
  "subject": null,
  "summary": null,
  "chatId": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces",
  "importance": "normal",
  "locale": "en-us",
  "webUrl": null,
  "from": {
    "application": null,
    "device": null,
    "user": {
      "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
      "displayName": "Ramjot Singh",
      "userIdentityType": "aadUser"
    },
    "conversation": null
  },
  "body": {
    "contentType": "text",
    "content": "test"
  },
  "channelIdentity": null,
  "attachments": [],
  "mentions": [],
  "policyViolation": null,
  "reactions": [],
  "replies": [],
  "hostedContents": []
}

Notifications sans les données de ressource

Les notifications sans les données de ressource vous donnent suffisamment d’informations pour passer des appels GET pour obtenir le contenu du message. Les abonnements aux notifications sans données de ressource ne nécessitent pas de certificat de chiffrement (car les données de ressource réelles ne sont pas envoyées).

La charge utile se présente comme suit. Cette charge utile concerne un message envoyé dans un canal.

 {
  "subscriptionId": "9f9d1ed0-c9cc-42e7-8d80-a7fc4b0cda3c",
  "changeType": "created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-02-02T11:26:41.0537895-08:00",
  "resource": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.chatMessage",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')"
  }
}

Les propriétés de Ressource et @odata.id peuvent être utilisées pour effectuer des appels vers Microsoft Graph afin d’obtenir la charge utile du message. Les appels GET retournent toujours l’état actuel du message. Si le message est modifié entre le moment où la notification est envoyée et le moment où le message est récupéré, l’opération retourne le message mis à jour.

Contenu connexe