Compartir a través de

Obtener notificaciones de cambios para los chats mediante Microsoft Graph

  • Artículo

Las notificaciones de cambio le permiten suscribirse a los cambios (crear y actualizar) en los chats. Puede recibir una notificación cada vez que se crea o actualiza un chat . También puede obtener los datos de recursos en las notificaciones y, por lo tanto, evitar llamar a la API para obtener la carga.

Continúe con este artículo sobre los escenarios del recurso de chat . O bien, obtenga información sobre las notificaciones de cambio para otros recursos de Microsoft Teams.

Nota:

Si solicita una expiración de suscripciónDateTime que sea superior a 1 hora en el futuro, debe suscribirse a las notificaciones de ciclo de vida incluyendo una propiedad lifecycleNotificationUrl en la solicitud de suscripción. De lo contrario, se producirá un error en la solicitud de suscripción con el siguiente mensaje de error: lifecycleNotificationUrl es una propiedad necesaria para la creación de la suscripción en este recurso cuando el valor expirationDateTime se establece en mayor que 1 hora.

Suscribirse a los cambios en cualquier equipo en el nivel de espacio empresarial

Para obtener notificaciones de cambios para todos los cambios (crear y actualizar) relacionados con cualquier canal de un espacio empresarial, suscríbase a /chats. Este recurso permite incluir datos de recursos en la notificación.

Permisos

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) No admitida.
Delegado (cuenta personal de Microsoft) No admitida.
Aplicación Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Ejemplo

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

Suscribirse a cambios en un chat determinado

Para obtener notificaciones de cambios para todos los cambios relacionados con un chat determinado, suscríbase a /chats/{id}. Este recurso admite incluir datos de recursos en la notificación y proporcionar el parámetro de cadena de consulta notifyOnUserSpecificProperties en el contexto de usuario.

Permisos

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Delegado (cuenta personal de Microsoft) No admitida.
Aplicación ChatSettings.Read.Chat*, ChatSettings.ReadWrite.Chat*, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Nota: Los permisos marcados con * usan un consentimiento específico del recurso.

Ejemplo 1: Suscribirse a cambios en un chat determinado

En el ejemplo siguiente se muestra cómo suscribirse para recibir notificaciones de cambios en un chat determinado.

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

Ejemplo 2: Suscribirse a cambios en un chat determinado mediante el parámetro de consulta notifyOnUserSpecificProperties

En el ejemplo siguiente se muestra cómo suscribirse para recibir notificaciones de cambios en un chat determinado proporcionando el parámetro de consulta 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}"
}

Suscribirse a los cambios en cualquier chat en el nivel de usuario (versión preliminar)

Para obtener notificaciones de cambios para todos los cambios en todos los chats de los que forma parte un usuario determinado, suscríbase a /users/{user-id}/chats. Este recurso admite incluir datos de recursos en la notificación y proporcionar el parámetro de cadena de consulta notifyOnUserSpecificProperties en el contexto de usuario.

Permisos

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Delegado (cuenta personal de Microsoft) No admitida.
Aplicación Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Ejemplo 1: Suscribirse a cambios en los chats de nivel de usuario

En el ejemplo siguiente se muestra cómo suscribirse para recibir notificaciones de cambios en todos los chats de los que forma parte un usuario determinado.

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

Ejemplo 2: Suscribirse a los cambios en los chats de nivel de usuario mediante la ruta de me acceso

En el ejemplo siguiente se muestra cómo suscribirse para recibir notificaciones de cambios en todos los chats de los que forma parte el usuario que ha iniciado sesión.

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

Ejemplo 3: Suscribirse a los cambios en los chats de nivel de usuario mediante el parámetro de consulta notifyOnUserSpecificProperties

En el ejemplo siguiente se muestra cómo suscribirse para recibir notificaciones de cambios en todos los chats de los que forma parte un usuario determinado proporcionando el parámetro de consulta 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}"
}

Suscribirse a los cambios en cualquier chat de un inquilino donde esté instalada una aplicación de Teams

Para obtener notificaciones de cambios para todos los cambios relacionados con cualquier chat en un inquilino donde esté instalada una aplicación específica de Teams, suscríbase a /appCatalogs/teamsApps/{teams-app-id}/installedToChats. Este recurso permite incluir datos de recursos en la notificación.

Nota: Esta API tiene requisitos de licencia y pago. Admite el parámetro de consulta model=B. Si no se especifica ningún modelo, se usará el modo de evaluación.

Permisos

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) No admitida.
Delegado (cuenta personal de Microsoft) No admitida.
Aplicación Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled

Ejemplo

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

Cargas de notificaciones

Notificaciones con datos de recursos

Para las notificaciones con datos de recursos, la carga es similar a la siguiente. Esta carga es para un cambio de propiedad en un chat.

{
    "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-->>"]
}

Para obtener más información sobre cómo validar tokens y descifrar la carga, consulte Configurar notificaciones de cambio que incluyan datos de recursos.

La carga de notificación descifrada es similar a la siguiente. La carga se ajusta al esquema de chats. La carga es similar a la devuelta por las operaciones 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": []
}

Cargas de notificación para propiedades específicas del usuario

Cuando se proporciona el parámetro de cadena de consulta notifyOnUserSpecificProperties con el valor true durante la creación de la suscripción, se envían al suscriptor dos tipos de cargas con distintos conjuntos de información. Un tipo contiene propiedades específicas del usuario; el otro no contiene propiedades específicas del usuario.

Nota: El parámetro de cadena de consulta notifyOnUserSpecificProperties solo se admite para las suscripciones de chat en el contexto de usuario, específicamente para las suscripciones a un chat determinado o en el nivel de usuario.

En la siguiente carga se describe la información enviada en una solicitud de notificaciones que contienen propiedades específicas del usuario. La carga contiene un subconjunto de propiedades del esquema de chat , incluida la propiedad de punto de vista con un valor distinto de NULL, específico del usuario suscrito. La omisión de otras propiedades del esquema de chat no implica ningún cambio en sus valores.

Nota: Cuando un usuario oculta un chat en el cliente de Teams, recibe una notificación con isHidden: true en la propiedad punto de vista ; sin embargo, no se envía ninguna notificación con isHidden: false cuando el chat vuelve a ser visible después de que llega un nuevo mensaje. Para determinar si el chat ya no está oculto, el suscriptor debe comparar lastMessageReadDateTime en la propiedad de punto de vista con el createdDateTime del nuevo mensaje. Si createdDateTime es posterior a lastMessageReadDateTime, el chat es visible. El suscriptor debe tener una suscripción activa para recibir notificaciones de cambio sobre mensajes en el chat para recibir notificaciones de nuevos mensajes en un chat oculto. Cuando el usuario abre el chat y lee el nuevo mensaje, se envía una notificación con isHidden: false y se actualiza lastMessageReadDateTime en la propiedad del punto de vista .

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

En la siguiente carga se describe la información enviada en una solicitud de notificaciones que no contienen propiedades específicas del usuario. La carga útil no incluye la propiedad de punto de vista ; sin embargo, esta situación no implica un cambio en su valor para el usuario.

{
  "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": []
}

Notificaciones con datos de recursos

La siguiente carga descifrada describe la información enviada en una solicitud de notificaciones sin datos de recursos. Esta carga concreta significa que se ha creado un nuevo chat.

{
  "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')"
  }
}

Las propiedades de recurso y @odata.id pueden usarse para realizar llamadas a Microsoft Graph y obtener la carga de los detalles del chat. Las llamadas GET siempre devuelven el estado actual de los detalles del chat. Si los detalles del chat se actualizaron entre el momento en que se envía la notificación y el momento en que se recuperan los detalles del chat, la operación devuelve los detalles actualizados del chat.

Contenido relacionado