Compartilhar via

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

  • Artigo

As notificações de alteração permitem que você se inscreva para receber alterações (criar e atualizar) nos chats. Pode ser notificado sempre que for criada ou atualizada uma conversa . 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 . Em alternativa, saiba mais sobre as notificações de alteração de outros recursos do Microsoft Teams.

Observação

Se pedir uma subscrição expirationDateTime que seja superior a 1 hora no futuro, terá de subscrever notificações de ciclo de vida ao incluir uma propriedade lifecycleNotificationUrl no pedido de subscrição. Caso contrário, o pedido de subscrição falhará com a seguinte mensagem de erro: lifecycleNotificationUrl é uma propriedade necessária para a criação da subscrição neste recurso quando o valor expirationDateTime estiver definido como superior a 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}. Este recurso suporta a inclusão de dados de recursos na notificação e o fornecimento do parâmetro de cadeia de consulta notifyOnUserSpecificProperties no contexto do utilizador.

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.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

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

Exemplo 1: subscrever alterações num chat específico

O exemplo seguinte mostra como subscrever para receber notificações de alterações num 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: subscrever alterações num chat específico com o parâmetro de consulta notifyOnUserSpecificProperties (pré-visualização)

O exemplo seguinte mostra como subscrever para receber notificações de alterações num chat específico ao fornecer o 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": "/chats/{id}?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Subscrever alterações em qualquer conversa ao nível do utilizador (pré-visualização)

Para obter notificações de alteração para todas as alterações em todas as conversas de que um determinado utilizador faz parte, subscreva /users/{user-id}/chats. Este recurso suporta a inclusão de dados de recursos na notificação e o fornecimento do parâmetro de cadeia de consulta notifyOnUserSpecificProperties no contexto do utilizador.

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: subscrever alterações em conversas ao nível do utilizador

O exemplo seguinte mostra como subscrever para receber notificações de alterações em todas as conversas das quais um determinado utilizador faz parte.

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

Exemplo 2: subscrever alterações em conversas ao nível do utilizador com o me caminho

O exemplo seguinte mostra como subscrever para receber notificações de alterações em todas as conversas das quais o utilizador com sessão iniciada faz parte.

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

Exemplo 3: subscrever alterações em conversas ao nível do utilizador com o parâmetro de consulta notifyOnUserSpecificProperties

O exemplo seguinte mostra como subscrever para receber notificações de alterações em todas as conversas de que um determinado utilizador faz parte ao fornecer o 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}"
}

Subscrever alterações em qualquer chat num inquilino onde esteja instalada uma aplicação do Teams

Para obter notificações de alteração de todas as alterações relacionadas com qualquer chat num inquilino onde esteja instalada uma aplicação específica do Teams, subscreva /appCatalogs/teamsApps/{teams-app-id}/installedToChatso . Este recurso oferece suporte a incluindo dados de recursos na notificação.

Observação: esta API tem requisitos de licenciamento e pagamento. Ele dá suporte ao parâmetro model=B consulta. Se nenhum modelo for especificado, o modo de avaliação será usado.

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

Payloads de notificação para propriedades específicas do utilizador

Quando fornece o parâmetro de cadeia de consulta notifyOnUserSpecificProperties com valor true durante a criação da subscrição, são enviados dois tipos de payloads com diferentes conjuntos de informações para o subscritor. Um tipo contém propriedades específicas do utilizador; o outro não contém propriedades específicas do utilizador.

Nota: o parâmetro de cadeia de consulta notifyOnUserSpecificProperties é suportado apenas para subscrições de chat no contexto de utilizador, especificamente para subscrições para um chat específico ou ao nível do utilizador.

O payload seguinte descreve as informações enviadas num pedido de notificações que contêm propriedades específicas do utilizador. O payload contém um subconjunto de propriedades do esquema de chat , incluindo a propriedade do ponto de vista com um valor não nulo, específico do utilizador subscrito. A omissão de outras propriedades do esquema de chat não implica qualquer alteração nos respetivos valores.

Nota: quando um utilizador oculta uma conversa no cliente do Teams, recebe uma notificação com isHidden: true na propriedade do ponto de vista ; no entanto, não é enviada nenhuma notificação quando isHidden: false o chat fica novamente visível após a chegada de uma nova mensagem. Para determinar se o chat já não está oculto, o subscritor tem de comparar lastMessageReadDateTime na propriedade do ponto de vista com o createdDateTime da nova mensagem. Se createdDateTime for posterior a lastMessageReadDateTime, o chat fica visível. O subscritor tem de ter uma subscrição ativa para receber notificações de alteração sobre mensagens no chat para ser notificado de novas mensagens numa conversa oculta. Quando o utilizador abre o chat e lê a nova mensagem, é enviada uma notificação com isHidden: false e 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 payload seguinte descreve as informações enviadas num pedido de notificações que não contêm propriedades específicas do utilizador. O payload não inclui a propriedade do ponto de vista ; no entanto, esta situação não implica uma alteração no respetivo valor para o utilizador.

{
  "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 payload desencriptado seguinte descreve as informações enviadas num pedido de notificações sem dados de recursos. 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 devolvem sempre o estado atual dos detalhes do chat. Se os detalhes da conversa tiverem sido atualizados entre quando a notificação é enviada e quando os detalhes da conversa são obtidos, a operação devolve os detalhes do chat atualizados.

Conteúdo relacionado