Obtener notificaciones de cambio de mensajes en canales y chats de Teams con Microsoft Graph

Artículo
03/26/2023

Las notificaciones de cambio le permiten suscribirse a cambios (crear, actualizar y eliminar) de mensajes en un canal o chat. Las notificaciones de cambio proporcionan un modelo de latencia baja ya que le permiten mantener una suscripción. 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 chatMessage en el contexto de canal o chat . O bien, obtenga información sobre las notificaciones de cambio para otros recursos de Microsoft Teams.

Para realizar un seguimiento de todos los cambios relacionados con los mensajes de un espacio empresarial, puede usar suscripciones en el nivel de espacio empresarial para mensajes de chat y canales. Esto requiere la creación de dos suscripciones: una para realizar un seguimiento de todos los mensajes de los canales y otro para realizar un seguimiento de todos los mensajes en los chats.

Para tener acceso a las notificaciones de cambio de todos los mensajes y respuestas de todos los canales de un espacio empresarial, suscríbase a /teams/getAllMessages. Este recurso permite incluir datos de recursos en la notificación.

Nota: Esta API tiene requisitos de licencia y pago. Admite parámetros de consulta model=A y 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	ChannelMessage.Read.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": "/teams/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Para obtener las notificaciones de cambio para todos los mensajes en todos los chats de un espacio empresarial, suscríbase a /chats/getAllMessages. Este recurso permite incluir datos de recursos en la notificación.

Nota: Esta API tiene requisitos de licencia y pago. Admite parámetros de consulta model=A y 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.Read.All

Ejemplo

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

Para realizar un seguimiento de los mensajes y respuestas en un canal, puede crear una suscripción de notificación de cambios a nivel de chat. Para hacerlo, suscríbase a /teams/{team-id}/channels/{channel-id}/messages. Este recurso admite la inclusión de datos de recursos en la notificación tanto en el modo delegado, como en el modo de solo aplicación.

Las suscripciones a nivel de canal también son compatibles con la búsqueda basada en palabras clave mediante el parámetro de consulta $search.

Permisos

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

Nota: Los permisos marcados con * se admiten como parte del consentimiento específico del recurso.

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

La siguiente solicitud enviará mensajes que contienen Hello al suscriptor.

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

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

Para recibir notificaciones solo de mensajes en los que se ha mencionado a un usuario en concreto, puede especificar el Id. del usuario (9a6eb4d1-826b-48b1-9627-b50836c8fee9 en este ejemplo) en la consulta.

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

Para realizar un seguimiento de mensajes en un chat, puede crear una suscripción de notificación de cambio a nivel de chat. Para hacerlo, suscríbase a /chats/{chat-id}/messages. Este recurso admite la inclusión de datos de recursos en la notificación tanto en el modo delegado, como en el modo de solo aplicación.

Las suscripciones a nivel de chat también son compatibles con la búsqueda basada en palabras clave mediante el parámetro de consulta $search.

Permisos

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

Nota: Los permisos marcados con * se admiten como parte del consentimiento específico del recurso, actualmente solo para la versión beta.

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

La siguiente solicitud enviará mensajes que contienen Hello al suscriptor.

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

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

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

Para hacer un seguimiento de los mensajes en todos los chats de los que forma parte un usuario concreto, puede crear una suscripción de notificación de cambios a nivel de usuario. Para hacerlo, suscríbase a /users/{user-id}/chats/getAllMessages. Este recurso admite la inclusión de datos de recursos en la notificación tanto en el modo delegado, y como en el modo de sólo aplicación.

Las suscripciones de mensajería de chat a nivel de usuario también admiten la búsqueda basada en palabras clave a través del $search parámetro de consulta.

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)	Chat.Read, Chat.ReadWrite
Delegado (cuenta personal de Microsoft)	No admitida.
Aplicación	Chat.Read.All, Chat.ReadWrite.All

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

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

Nota. Este tipo de recurso está actualmente en versión preliminar.

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.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled

Ejemplo:

POST https://graph.microsoft.com/beta/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}"
}

Cargas de notificaciones

Dependiendo de su suscripción, puede obtener la notificación con datos de recursos o sin ellos. Suscribirse con datos de recursos le permite obtener la carga del mensaje junto con la notificación, lo que elimina la necesidad de devolver la llamada y obtener el contenido.

Notificaciones con datos de recursos

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

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

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 chatMessage. La carga es similar a la devuelta por las operaciones 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": []
}

Notificaciones con datos de recursos

Las notificaciones sin datos de recursos le proporcionarán suficiente información para realizar llamadas GET y obtener el contenido del mensaje. Las suscripciones para las notificaciones sin datos de recursos no requieren ningún certificado de cifrado (porque no se envían los datos de recursos reales).

La carga es similar a la siguiente. Esta carga es para un mensaje enviado en un chat.

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

Las propiedades recurso y @odata.id pueden usarse para realizar llamadas a Microsoft Graph y obtener la carga del mensaje. Las llamadas GET siempre devolverán el estado actual del mensaje: Si el mensaje se cambia entre el momento en que se envía la notificación y cuando se recupera el mensaje, la operación devolverá el mensaje actualizado.

Obtener notificaciones de cambio de mensajes en canales y chats de Teams con Microsoft Graph

Permisos

Ejemplo

Permisos

Ejemplo

Permisos

Permisos

Permisos

Permisos

Ejemplo:

Cargas de notificaciones

Notificaciones con datos de recursos

Notificaciones con datos de recursos

Ver también

Recursos adicionales

Recursos adicionales

Obtener notificaciones de cambio de mensajes en canales y chats de Teams con Microsoft Graph

Suscribirse a los cambios en el nivel de espacio empresarial

Suscribirse a mensajes en todos los canales

Permisos

Ejemplo

Suscribirse a mensajes en todos los chats

Permisos

Ejemplo

Suscribirse a mensajes en un canal

Permisos

Ejemplo 1: suscribirse a todos los mensajes y respuestas en un canal

Ejemplo 2: suscribirse a mensajes (y respuestas) en un canal que contenga texto determinado

Ejemplo 3: suscribirse a mensajes (y respuestas) en un canal sin datos de recursos

Ejemplo 4: suscribirse a mensajes (y respuestas) en un canal que mencione a un usuario en concreto.

Suscribirse a mensajes en un chat

Permisos

Ejemplo 1: suscribirse a mensajes en un chat

Ejemplo 2: suscribirse a mensajes en un chat que contienen determinado texto

Ejemplo 3: suscribirse a mensajes (y respuestas) en un chat sin datos de recursos

Ejemplo 4: suscribirse a mensajes en un chat en los que se ha mencionado a un usuario en concreto.

Suscribirse a los cambios a nivel de usuario

Permisos

Ejemplo: Suscribirse a los mensajes de todos los chats de los que forma parte un determinado usuario

Suscribirse a mensajes de cualquier chat de un inquilino donde esté instalada una aplicación específica de Teams (versión preliminar)

Permisos

Ejemplo:

Cargas de notificaciones

Notificaciones con datos de recursos

Notificaciones con datos de recursos

Ver también

Recursos adicionales

Recursos adicionales