Obtenha notificações de alteração para chats usando o Microsoft Graph

As notificações de alteração permitem que você se inscreva para receber alterações (criar e atualizar) nos chats. Você pode ser notificado sempre que um chat for criado ou atualizado. Você também pode obter os dados do recurso nas notificações e, portanto, evitar chamar a API para obter o conteúdo.

Continue com este artigo sobre cenários para o recurso de chat . Ou descubra mais sobre notificações de alteração para outros recursos do Microsoft Teams.

Observação

Se você solicitar uma expirationDateTime de assinatura superior a 1 hora no futuro, deverá assinar notificações de ciclo de vida incluindo uma propriedade lifecycleNotificationUrl em sua solicitação de assinatura. Caso contrário, sua solicitação de assinatura falhará com a seguinte mensagem de erro: lifecycleNotificationUrl é uma propriedade necessária para a criação de assinatura neste recurso quando o valor expirationDateTime é definido como maior que 1 hora.

Inscrever-se para alterações em qualquer chat a nível de locatário

Para obter notificações de alteração para todas as alterações (criar e atualizar) relacionadas a qualquer chat em um locatário, inscreva-se em /chats. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Sem suporte.
Delegado (conta pessoal da Microsoft) Sem suporte.
Aplicativo Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Exemplo

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

Inscrever-se para alterações em um chat específico

Para obter notificações de alteração para todas as alterações relacionadas a um chat específico, inscreva-se em /chats/{id}. Esse recurso dá suporte à inclusão de dados de recursos na notificação e ao fornecimento do parâmetro de cadeia de caracteres de consulta notifyOnUserSpecificProperties no contexto do usuário.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Delegado (conta pessoal da Microsoft) Sem suporte.
Application ChatSettings.Read. Chat*, ChatSettings.ReadWrite. Chat*, Chat. Gerar. Chat*, Chat. ReadBasic.All, Chat. Read.All, Chat. ReadWrite.All

Observação: Permissões marcadas com * usam consentimento específico de recurso.

Exemplo 1: Assinar alterações em um chat específico

O exemplo a seguir mostra como se inscrever para receber notificações de alterações em um chat específico.

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

Exemplo 2: Assinar alterações em um chat específico usando o parâmetro de consulta notifyOnUserSpecificProperties

O exemplo a seguir mostra como se inscrever para receber notificações de alterações em um chat específico, fornecendo o 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}"
}

Assinar as alterações em qualquer chat no nível do usuário

Para receber notificações de alteração de todas as alterações em todos os chats dos quais um determinado usuário faz parte, inscreva-se /users/{user-id}/chatsno . Esse recurso dá suporte à inclusão de dados de recursos na notificação e ao fornecimento do parâmetro de cadeia de caracteres de consulta notifyOnUserSpecificProperties no contexto do usuário.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Delegado (conta pessoal da Microsoft) Sem suporte.
Aplicativo Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Exemplo 1: Assinar alterações em chats no nível do usuário

O exemplo a seguir mostra como se inscrever para receber notificações de alterações em todos os chats dos quais um determinado usuário faz parte.

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

Exemplo 2: Assinar alterações em chats no nível do usuário usando o me caminho

O exemplo a seguir mostra como se inscrever para receber notificações de alterações em todos os chats dos quais o usuário conectado faz parte.

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

Exemplo 3: Assinar alterações em chats no nível do usuário usando o parâmetro de consulta notifyOnUserSpecificProperties

O exemplo a seguir mostra como se inscrever para receber notificações de alterações em todos os chats dos quais um determinado usuário faz parte, fornecendo o parâmetro de consulta notifyOnUserSpecificProperties .

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

Assinar as alterações em qualquer chat em um locatário onde um aplicativo do Teams está instalado

Para obter notificações de alteração de todas as alterações relacionadas a qualquer chat em um locatário em que um aplicativo específico do Teams está instalado, assine o /appCatalogs/teamsApps/{teams-app-id}/installedToChats. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Sem suporte.
Delegado (conta pessoal da Microsoft) Sem suporte.
Application Chat. ReadBasic.WhereInstalled, Chat. Read.WhereInstalled, Chat. ReadWrite.WhereInstalled

Exemplo

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 notificação

Notificações com dados de recursos

Para notificações com dados de recursos, a carga se parece com a seguinte. Este conteúdo é para uma alteração de propriedade em um 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 obter detalhes sobre como validar tokens e descriptografar a carga útil, consulte Definir notificações de alteração que incluem dados de recursos.

A carga de notificação descriptografada parece com a seguinte. O conteúdo está de acordo com o esquema de chats. A carga é semelhante à devolvida pelas operações 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 notificação para propriedades específicas do usuário

Quando você fornece o parâmetro de cadeia de caracteres de consulta notifyOnUserSpecificProperties com valor true durante a criação da assinatura, dois tipos de cargas com diferentes conjuntos de informações são enviados ao assinante. Um tipo contém propriedades específicas do usuário; o outro não contém propriedades específicas do usuário.

Observação: o parâmetro da cadeia de caracteres de consulta notifyOnUserSpecificProperties tem suporte apenas para assinaturas de chat no contexto do usuário, especificamente para assinaturas de um chat específico ou no nível do usuário.

O conteúdo a seguir descreve as informações enviadas em uma solicitação de notificações que contêm propriedades específicas do usuário. A carga contém um subconjunto de propriedades do esquema de chat , incluindo a propriedade viewpoint com um valor não nulo, específico para o usuário assinante. A omissão de outras propriedades do esquema de chat não implica nenhuma alteração em seus valores.

Observação: quando um usuário oculta um chat no cliente do Teams, ele recebe uma notificação com isHidden: true na propriedade viewpoint ; no entanto, nenhuma notificação com isHidden: false é enviada quando o chat se torna visível novamente após a chegada de uma nova mensagem. Para determinar se o chat não está mais oculto, o assinante deve comparar lastMessageReadDateTime na propriedade viewpoint com o createdDateTime da nova mensagem. Se createdDateTime for posterior a lastMessageReadDateTime, o chat estará visível. O assinante deve ter uma assinatura ativa para receber notificações de alteração sobre mensagens no chat e ser notificado sobre novas mensagens em um chat oculto. Quando o usuário abre o chat e lê a nova mensagem, uma notificação é enviada e isHidden: false uma lastMessageReadDateTime atualizada na propriedade do ponto 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"
  }
}

O conteúdo a seguir descreve as informações enviadas em uma solicitação de notificações que não contêm propriedades específicas do usuário. O conteúdo não inclui a propriedade viewpoint; No entanto, essa situação não implica uma alteração em seu valor para o usuário.

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

Notificações sem dados de recursos

O conteúdo descriptografado a seguir descreve as informações enviadas em uma solicitação de notificações sem dados de recurso. Este conteúdo específico significa que um novo chat foi criado.

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

O recurso e a propriedades @odata.id pode ser usado para fazer chamadas para o Microsoft Graph para obter o conteúdo dos detalhes do chat. As chamadas GET sempre retornam o estado atual dos detalhes do chat. Se os detalhes do chat foram atualizados entre o momento em que a notificação é enviada e o momento em que os detalhes do chat são recuperados, a operação retorna os detalhes do chat atualizados.

Conteúdo relacionado

  • Last updated on