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

Artículo
09/09/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.

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.

Para realizar un seguimiento de todos los cambios relacionados con los mensajes de un inquilino, puede usar suscripciones en el nivel de inquilino para los mensajes de canal y chat, creando dos suscripciones: una para realizar un seguimiento de todos los mensajes entre canales y otra 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 mensajes y respuestas en un canal, puede crear una suscripción de notificación de cambios en un nivel de canal mediante la suscripción 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 envía 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 los mensajes en un chat, puede crear una suscripción de notificación de cambios en un nivel de chat mediante la suscripción 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 envía 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 realizar un seguimiento de los mensajes en todos los chats de los que forma parte un usuario determinado, puede crear una suscripción de notificación de cambios en el nivel de usuario mediante la suscripción 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: 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/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}"
}

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 notificaciones sin datos de recursos no requieren un certificado de cifrado (porque los datos de recursos reales no se envían).

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 devuelven el estado actual del mensaje. Si el mensaje cambia entre cuando se envía la notificación y cuando se recupera el mensaje, la operación devuelve el mensaje actualizado.

Compartir a través de

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

Comentarios

Recursos adicionales

Compartir a través de

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 los mensajes de cualquier chat de un inquilino donde esté instalada una aplicación específica de Teams

Permisos

Ejemplo

Cargas de notificaciones

Notificaciones con datos de recursos

Notificaciones con datos de recursos

Contenido relacionado

Comentarios

Recursos adicionales