Compartilhar via

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

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 canal ou no contexto 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.

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

Para controlar todas as alterações relacionadas com mensagens num inquilino, pode utilizar subscrições ao nível do inquilino para mensagens de canal e chat, criando duas subscrições: uma para controlar todas as mensagens entre canais e outra para controlar todas as mensagens nas conversas.

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 controlar mensagens e respostas num canal, pode criar uma subscrição de notificação de alteração ao nível do canal ao subscrever /teams/{team-id}/channels/{channel-id}/messageso . 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

O pedido seguinte envia mensagens que contêm Hello ao subscritor.

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 controlar mensagens num chat, pode criar uma subscrição de notificação de alteração ao nível do chat ao subscrever /chats/{chat-id}/messageso . 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

O pedido seguinte envia mensagens que contêm Hello ao subscritor.

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 controlar mensagens em todas as conversas de que um determinado utilizador faz parte, pode criar uma subscrição de notificação de alteração ao /users/{user-id}/chats/getAllMessagesnível do utilizador ao subscrever o . 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}"
}

Subscrever mensagens de qualquer conversa num inquilino onde está instalada uma aplicação específica do Teams

Para obter notificações de alteração para todas as mensagens em chats num inquilino onde está instalada uma aplicação específica do Teams, subscreva /appCatalogs/teamsApps/{teams-app-id}/installedToChats/getAllMessageso . 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.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. As subscrições para notificações sem dados de recursos não necessitam de um certificado de encriptação (porque os dados de recursos reais 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 devolvem sempre o estado atual da mensagem. Se a mensagem for alterada entre quando a notificação é enviada e quando a mensagem é obtida, a operação devolve a mensagem atualizada.

Conteúdo relacionado

  • Last updated on