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

  • Artículo

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.

Suscribirse a los cambios en el nivel de espacio empresarial

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.

Suscribirse a mensajes en todos los canales

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

Suscribirse a mensajes en todos los chats

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

Suscribirse a mensajes en un canal

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.

Ejemplo 1: suscribirse a todos los mensajes y respuestas en 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}"
}

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

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

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

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

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

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

Suscribirse a mensajes en un chat

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.

Ejemplo 1: suscribirse a mensajes en un chat

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

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

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

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

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

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

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

Suscribirse a los cambios a nivel de usuario

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

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

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

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

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.

Contenido relacionado