Obter notificações de alteração para mensagens nos canais e bate-papos do Teams usando o Microsoft Graph

  • Artigo

As notificações de alteração habilitam você a inscrever-se para receber alterações (criar, atualizar e excluir) de mensagens em um canal ou chat. As notificações da alteração fornecem um modelo de baixa latência, permitindo que você mantenha uma assinatura. Você também pode obter os dados do recurso nas notificações e, portanto, evitar chamar a API para obter a carga útil.

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

Observação

Se você solicitar uma assinatura expirationDateTime com mais de 1 hora no futuro, você 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 criação de assinatura nesse recurso quando o valor expirationDateTime for definido como maior que 1 hora.

Assinar para receber alterações no nível do locatário

Para acompanhar todas as alterações relacionadas a mensagens em um locatário, você pode usar assinaturas em um nível de locatário para mensagens de canal e chat, criando duas assinaturas: uma para acompanhar todas as mensagens entre canais e outra para acompanhar todas as mensagens em chats.

Assine para receber mensagens em todos os canais

Para obter notificações de alteração para todas as mensagens e respostas nos canais de um locatário, inscreva-se em /teams/getAllMessages. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Observação: esta API tem requisitos de licenciamento e pagamento. Ela suporta os parâmetros de consulta model=A e model=B. 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.
Aplicativo ChannelMessage.Read.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": "/teams/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Assine para receber mensagens em chats

Para obter notificações de alteração para todas as mensagens em chats em um locatário, assine em /chats/getAllMessages. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Observação: esta API tem requisitos de licenciamento e pagamento. Ela suporta os parâmetros de consulta model=A e model=B. 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.
Aplicativo Chat.Read.All

Exemplo

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

Assine em mensagens em um canal

Para acompanhar mensagens e respostas em um canal, você pode criar uma assinatura de notificação de alteração em um nível de canal assinando ./teams/{team-id}/channels/{channel-id}/messages Esse recurso oferece suporte à inclusão de dados de recursos na notificação no modo delegado e somente no aplicativo.

As assinaturas no nível do canal também oferecem suporte à pesquisa baseada em palavras-chave por meio do parâmetro de consulta $search.

Permissões

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

Nota: As permissões marcadas com * são suportadas como parte do consentimento específico do recurso.

Exemplo 1: assinar em todas as mensagens (e respostas) em um 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}"
}

Exemplo 2: assinar para receber mensagens (e respostas) em um canal que contém determinado texto

A solicitação a seguir envia mensagens que contêm Hello ao assinante.

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

Exemplo 3: assinar para receber mensagens (e respostas) em um canal sem dados 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}"
}

Exemplo 4: assinar para receber mensagens (e respostas) em um canal que menciona um usuário específico

Para obter notificações somente para mensagens em que um usuário específico foi mencionado, você pode especificar a ID do usuário (9a6eb4d1-826b-48b1-9627-b50836c8fee9 nesse exemplo) na 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}"
}

Assinar para receber mensagens em um chat

Para acompanhar mensagens em um chat, você pode criar uma assinatura de notificação de alteração em um nível de chat assinando o /chats/{chat-id}/messages. Esse recurso oferece suporte à inclusão de dados de recursos na notificação no modo delegado e somente no aplicativo.

As assinaturas no nível do chat também oferecem suporte à pesquisa baseada em palavras-chave por meio do parâmetro de consulta $search.

Permissões

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

Nota: As permissões marcadas com * são suportadas como parte do consentimento específico do recurso apenas para a versão beta atualmente.

Exemplo 1: assinar para receber mensagens em um 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}"
}

Exemplo 2: assinar para receber mensagens em um chat que contenham determinado texto

A solicitação a seguir envia mensagens que contêm Hello ao assinante.

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

Exemplo 3: assinar para receber mensagens (e respostas) em um chat sem dados 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}"
}

Exemplo 4: assinar para receber mensagem em um chat no qual um usuário específico for mencionado

Para obter notificações somente para mensagens em que um usuário específico foi mencionado, você pode especificar a ID do usuário (9a6eb4d1-826b-48b1-9627-b50836c8fee9 nesse exemplo) na 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}"
}

Assinar para receber alterações no nível do usuário

Para rastrear mensagens em todos os chats dos quais um determinado usuário faz parte, você pode criar uma assinatura de notificação de alteração em um nível de usuário assinando ./users/{user-id}/chats/getAllMessages Esse recurso dá suporte à inclusão de dados de recursos na notificação nos modos delegado e somente aplicativo.

As assinaturas de mensagens de chat no nível do usuário também suportam a pesquisa baseada em palavra-chave por meio do parâmetro de consulta $search.

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) Chat.Read, Chat.ReadWrite
Delegado (conta pessoal da Microsoft) Sem suporte.
Aplicativo Chat.Read.All, Chat.ReadWrite.All

Exemplo: assine para receber mensagens em todos os chats de que um usuário específico faz parte

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

Assinar mensagens de qualquer chat em um locatário em que um aplicativo específico do Teams está instalado

Para obter notificações de alteração para todas as mensagens em chats em um locatário em que um aplicativo específico do Teams está instalado, assine /appCatalogs/teamsApps/{teams-app-id}/installedToChats/getAllMessages. 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.
Aplicativo 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/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Notificação de conteúdo

Dependendo da sua assinatura, você pode receber a notificação com dados de recursos ou sem ele. Assinar com dados de recursos permite que você receba a carga da mensagem junto com a notificação, removendo a necessidade de ligar de volta e obter o conteúdo.

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 mensagem enviada em um bate-papo.

{
    "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 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. A carga está de acordo com o esquema chatMessage. A carga é semelhante à devolvida pelas operações 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": []
}

Notificações sem dados de recursos

Notificações sem dados de recursos dão informações suficientes para fazer chamadas GET para obter o conteúdo da mensagem. Assinaturas para notificações sem dados de recurso não exigem um certificado de criptografia (porque os dados reais do recurso não são enviados).

A carga parece ser a seguinte. Este conteúdo é para uma mensagem enviada em um canal.

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

As propriedades recurso e @odata.id podem ser usados para fazer chamadas para o Microsoft Graph para obter o conteúdo para a mensagem. As chamadas GET sempre retornam o estado atual da mensagem. Se a mensagem for alterada entre quando a notificação for enviada e quando a mensagem for recuperada, a operação retornará a mensagem atualizada.

Conteúdo relacionado