Recevoir des notifications de modification pour les conversations à l’aide de Microsoft Graph

  • Article

Les notifications de modification vous permettent de vous abonner aux modifications (création et mise à jour) apportées aux conversations. Vous pouvez recevoir une notification chaque fois qu’une conversation est créée ou mise à jour. 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 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 dans n’importe quelle conversation au niveau du client

Pour recevoir les notifications pour toutes les modifications (création et mise à jour) relatives à une conversation dans un client, abonnez-vous à /chats. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

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.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.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": "/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S’abonner aux modifications dans une conversation particulière

Pour recevoir les notifications pour toutes les modifications relatives à une conversation en particulier dans un client, abonnez-vous à /chats/{id}. Cette ressource prend en charge l’inclusion de données de ressource dans la notification et la fourniture du paramètre de chaîne de requête notifyOnUserSpecificProperties dans le contexte utilisateur.

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.ReadBasic, Chat.Read, Chat.ReadWrite
Déléguée (compte Microsoft personnel) Non prise en charge.
Application ChatSettings.Read.Chat*, ChatSettings.ReadWrite.Chat*, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Remarque : les autorisations marquées d’un astérisque (*) utilisent une autorisation propre aux ressources.

Exemple 1 : S’abonner aux modifications d’une conversation particulière

L’exemple suivant montre comment s’abonner pour recevoir des notifications de modifications dans une conversation particulière.

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

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

Exemple 2 : S’abonner aux modifications d’une conversation particulière à l’aide du paramètre de requête notifyOnUserSpecificProperties

L’exemple suivant montre comment s’abonner pour recevoir des notifications de modifications dans une conversation particulière en fournissant le paramètre de requête notifyOnUserSpecificProperties .

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

{
  "changeType": "updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{id}?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S’abonner aux modifications dans une conversation au niveau de l’utilisateur (préversion)

Pour obtenir des notifications de modification pour toutes les modifications dans toutes les conversations dont fait partie un utilisateur particulier, abonnez-vous à /users/{user-id}/chats. Cette ressource prend en charge l’inclusion de données de ressource dans la notification et la fourniture du paramètre de chaîne de requête notifyOnUserSpecificProperties dans le contexte utilisateur.

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.ReadBasic, Chat.Read, Chat.ReadWrite
Déléguée (compte Microsoft personnel) Non prise en charge.
Application Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Exemple 1 : S’abonner aux modifications apportées aux conversations au niveau de l’utilisateur

L’exemple suivant montre comment s’abonner pour recevoir des notifications de modifications sur toutes les conversations dont fait partie un utilisateur particulier.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/456bbcdb-1e1c-4f3f-b7d0-ad7b9abcdefc/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 2 : S’abonner aux modifications apportées aux conversations au niveau de l’utilisateur à l’aide du chemin d’accès me

L’exemple suivant montre comment s’abonner pour recevoir des notifications de modifications sur toutes les conversations dont l’utilisateur connecté fait partie.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/me/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 3 : S’abonner aux modifications apportées aux conversations au niveau de l’utilisateur à l’aide du paramètre de requête notifyOnUserSpecificProperties

L’exemple suivant montre comment s’abonner pour recevoir des notifications de modifications sur toutes les conversations auxquelles un utilisateur particulier fait partie en fournissant le paramètre de requête notifyOnUserSpecificProperties .

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/456bbcdb-1e1c-4f3f-b7d0-ad7b9abcdefc/chats?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S’abonner aux modifications apportées à une conversation dans un locataire où une application Teams est installée

Pour obtenir des notifications de modification pour toutes les modifications liées à une conversation dans un locataire où une application Teams spécifique est installée, abonnez-vous à /appCatalogs/teamsApps/{teams-app-id}/installedToChats. 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.ReadBasic.WhereInstalled, 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",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Charges utiles de notification

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 une modification de propriété dans une conversation.

{
    "value": [{
        "subscriptionId": "352887e3-9be0-4b6f-a4e6-dec118d857db",
        "changeType": "Created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-06-03T09:50:37.719033+00:00",
        "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
        "resourceData": {
            "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
            "@odata.type": "#microsoft.graph.chat",
            "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
        },
        "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 conversations. La charge utile est similaire à celle renvoyée par les opérations GET.

{
  "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
  "topic": null,
  "createdDateTime": "2021-06-03T14:25:04+05:30",
  "lastUpdatedDateTime": "2021-06-03T14:25:04.387Z",
  "chatType": "oneOnOne",
  "webUrl": "https://teams.microsoft.com/l/chat/19%3A1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438%40unq.gbl.spaces/0?tenantId=27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
  "isHiddenForAllMembers": false,
  "lastMessagePreview": null,
  "onlineMeetingInfo": null,
  "members": [
    {
      "userId": "976f4b31-fd01-4e0b-9178-29cc40c14438",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyM5NzZmNGIzMS1mZDAxLTRlMGItOTE3OC0yOWNjNDBjMTQ0Mzg=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    },
    {
      "userId": "ee723d3d-22d0-4394-9c32-5764d68f4672",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyNlZTcyM2QzZC0yMmQwLTQzOTQtOWMzMi01NzY0ZDY4ZjQ2NzI=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": [],
  "assignedSensitivityLabel": null,
  "pinnedMessages": []
}

Charges utiles de notification pour les propriétés spécifiques à l’utilisateur

Lorsque vous fournissez la valeur true du paramètre de chaîne de requête notifyOnUserSpecificProperties lors de la création de l’abonnement, deux types de charges utiles avec différents ensembles d’informations sont envoyés à l’abonné. Un type contient des propriétés spécifiques à l’utilisateur ; l’autre ne contient pas de propriétés spécifiques à l’utilisateur.

Remarque : le paramètre de chaîne de requête notifyOnUserSpecificProperties est pris en charge uniquement pour les abonnements de conversation dans le contexte utilisateur, en particulier pour les abonnements à une conversation particulière ou au niveau de l’utilisateur.

La charge utile suivante décrit les informations envoyées dans une demande de notifications qui contiennent des propriétés spécifiques à l’utilisateur. La charge utile contient un sous-ensemble de propriétés du schéma de conversation , y compris la propriété viewpoint avec une valeur non null, propre à l’utilisateur abonné. L’omission d’autres propriétés dans le schéma de conversation n’implique aucune modification de leurs valeurs.

Remarque : Lorsqu’un utilisateur masque une conversation dans le client Teams, il reçoit une notification avec isHidden: true dans la propriété du point de vue ; toutefois, aucune notification avec isHidden: false n’est envoyée lorsque la conversation redevient visible après l’arrivée d’un nouveau message. Pour déterminer si la conversation n’est plus masquée, l’abonné doit comparer le lastMessageReadDateTime dans la propriété de point de vue avec le createdDateTime du nouveau message. Si createdDateTime est ultérieur à lastMessageReadDateTime, la conversation est visible. L’abonné doit disposer d’un abonnement actif pour recevoir des notifications de modification sur les messages dans la conversation afin d’être averti des nouveaux messages dans une conversation masquée. Lorsque l’utilisateur ouvre ensuite la conversation et lit le nouveau message, une notification est envoyée avec isHidden: false et une mise à jour lastMessageReadDateTime dans la propriété de point de vue .

{
  "id": "19:a1d516d162d441f38cd474916913c806@thread.v2",
  "topic": "Feature Crew",
  "createdDateTime": "2024-04-22T15:14:04.624Z",
  "lastUpdatedDateTime": "2024-04-23T14:37:53.87Z",
  "chatType": "group",
  "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "viewpoint": {
    "isHidden": false,
    "lastMessageReadDateTime": "2024-04-22T15:18:59.228Z"
  }
}

La charge utile suivante décrit les informations envoyées dans une demande de notifications qui ne contiennent pas de propriétés spécifiques à l’utilisateur. La charge utile n’inclut pas la propriété point de vue ; Toutefois, cette situation n’implique pas de modification de sa valeur pour l’utilisateur.

{
  "id": "19:2a81219665e6448da23022ddb949f693@thread.v2",
  "topic": "Group chat",
  "createdDateTime": "2024-04-22T15:02:57Z",
  "lastUpdatedDateTime": "2024-04-23T14:55:20.545Z",
  "chatType": "group",
  "webUrl": "https://teams.microsoft.com/l/chat/19%3A2a81219665e6448da23022ddb949f693%40thread.v2/0?tenantId=27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "isHiddenForAllMembers": false,
  "lastMessagePreview": null,
  "onlineMeetingInfo": null,
  "members": [
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "4595d2f2-7b31-446c-84fd-9b795e63114b",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    },
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "7d898072-792c-4006-bb10-5ca9f2590649",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    },
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "c27c1b19-3904-4822-9813-4f6bdaab2eae",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": [],
  "assignedSensitivityLabel": null,
  "pinnedMessages": []
}

Notifications sans les données de ressource

La charge utile déchiffrée suivante décrit les informations envoyées dans une demande de notifications sans données de ressource. Cette charge utile particulière signifie qu’une conversation a été créée.

{
  "subscriptionId": "8d85051d-779d-45bc-be92-e433f0a5d8ac",
  "changeType": "Created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-06-03T10:26:09.8959595+00:00",
  "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
  "resourceData": {
    "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
    "@odata.type": "#microsoft.graph.chat",
    "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
  }
}

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

Contenu connexe