Obter notificações de alteração para mensagens nos canais e bate-papos do Teams usando o Microsoft GraphGet change notifications for messages in Teams channels and chats using Microsoft Graph

As notificações de alteração habilitam você a assinar para receber alterações (criar, atualizar e excluir) de mensagens em um canal ou chat.Change notifications enable you to subscribe to changes (create, update, and delete) to messages in a channel or chat. As notificações de alteração fornecem um modelo de baixa latência, permitindo que você mantenha uma assinatura.Change notifications provide a low latency model by allowing you to maintain a subscription. Você também pode obter os dados do recurso nas notificações e, portanto, evitar chamar a API para obter o conteúdo.You can also get the resource data in the notifications and therefore avoid calling the API to get the payload.

Observação: o tempo máximo que uma assinatura pode durar é 60 minutos; entretanto, as assinaturas podem ser renovadas até que o chamador tenha permissão para acessar o recurso.Note: The maximum time a subscription can last is 60 minutes; however, subscriptions can be renewed until the caller has permissions to access to resource.

Assinar para receber alterações no nível do locatárioSubscribe to changes at the tenant level

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.To track all changes related to messages in a tenant, you can use subscriptions at a tenant level for channel and chat messages. Isso requer que você crie duas assinaturas: uma para acompanhar todas as mensagens nos canais e outra para acompanhar todas as mensagens nos chats.This requires you to create two subscriptions: one to track all messages across channels, and one to track all messages across chats.

Assine para receber mensagens em todos os canaisSubscribe to messages across channels

Para obter notificações de alteração para todas as mensagens e respostas nos canais de um locatário, assine em /teams/getAllMessages.To get to change notifications for all messages and replies across channels in a tenant, subscribe to /teams/getAllMessages. Este recurso oferece suporte a incluindo dados de recursos na notificação.This resource supports including resource data in the notification.

PermissõesPermissions

Tipo de permissãoPermission type Permissões (da com menos para a com mais privilégios)Permissions (from least to most privileged) Versões com suporteSupported versions
Delegado (conta corporativa ou de estudante)Delegated (work or school account) Sem suporte.Not supported. Sem suporte.Not supported.
Delegado (conta pessoal da Microsoft)Delegated (personal Microsoft account) Sem suporte.Not supported. Sem suporte.Not supported.
AplicativoApplication ChannelMessage.Read.AllChannelMessage.Read.All beta, v1.0beta, v1.0

ExemploExample

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

Assinar para receber mensagens em chatsSubscribe to messages across chats

Para obter notificações de alteração para todas as mensagens em chats em um locatário, assine em /chats/getAllMessages.To get change notifications for all messages across chats in a tenant, subscribe to /chats/getAllMessages. Este recurso oferece suporte a incluindo dados de recursos na notificação.This resource supports including resource data in the notification.

PermissõesPermissions

Tipo de permissãoPermission type Permissões (da com menos para a com mais privilégios)Permissions (from least to most privileged) Versões com suporteSupported versions
Delegado (conta corporativa ou de estudante)Delegated (work or school account) Sem suporte.Not supported. Sem suporte.Not supported.
Delegado (conta pessoal da Microsoft)Delegated (personal Microsoft account) Sem suporte.Not supported. Sem suporte.Not supported.
AplicativoApplication Chat.Read.AllChat.Read.All beta, v1.0beta, v1.0

ExemploExample

POST https://graph.microsoft.com/beta/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 canalSubscribe to messages in a channel

Para acompanhar mensagens e respostas em um canal, você pode criar uma assinatura de notificação de alteraração no nível do canal.To track messages and replies in a channel, you can create a change notification subscription at a channel level. Para fazer isso, assine em /teams{id}/channels/{id}/messages.To do this, subscribe to /teams{id}/channels/{id}/messages. Este recurso oferece suporte à inclusão de dados de recursos na notificação no modo somente de aplicativo.This resource supports including resource data in the notification in application-only mode.

As assinaturas no nível do canal também oferecem suporte à pesquisa baseada em palavras-chave por meio do parâmetro de consulta $search.Channel-level subscriptions also support keyword-based search via the $search query parameter.

PermissõesPermissions

Tipo de permissãoPermission type Permissões (da com menos para a com mais privilégios)Permissions (from least to most privileged) Com suporte na versãoSupported in version
Delegado (conta corporativa ou de estudante)Delegated (work or school account) ChannelMessage.Read.AllChannelMessage.Read.All beta, v1.0beta, v1.0
Delegado (conta pessoal da Microsoft)Delegated (personal Microsoft account) Sem suporte.Not supported. Sem suporte.Not supported.
AplicativoApplication ChannelMessage.Read.All, ChannelMessage.Read.Group*ChannelMessage.Read.All, ChannelMessage.Read.Group* beta, v1.0beta, v1.0

Observação: ChannelMessage.Read.Group é suportado como parte do consentimento específico do recurso.Note: ChannelMessage.Read.Group is supported as part of resource-specific consent.

Exemplo 1: assinar em todas as mensagens (e respostas) em um canalExample 1: Subscribe to all messages (and replies) in a channel

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{id}/channels/{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 textoExample 2: Subscribe to messages (and replies) in a channel that contain certain text

A solicitação a seguir enviará mensagens que contêm Hello ao banco de dados do assinante.The following request will send messages that contain Hello to the subscriber.

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{id}/channels/{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 recursosExample 3: Subscribe to messages (and replies) in a channel without resource data

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{id}/channels/{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íficoExample 4: Subscribe to messages (and replies) in a channel that mention a specific user

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.To get notifications only for messages where a specific user has been mentioned, you can specify the user's ID (9a6eb4d1-826b-48b1-9627-b50836c8fee9 in this example) in the query.

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{id}/channels/{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 chatSubscribe to messages in a chat

Para acompanhar mensagens em um chat, você pode criar uma assinatura de notificação de alteração em um nível de chat.To track messages in a chat, you can create a change notification subscription at a chat level. Para fazer isso, assine em /chats{id}/messages.To do this, subscribe to /chats{id}/messages. Este recurso oferece suporte à inclusão de dados de recursos na notificação no modo somente de aplicativo.This resource supports including resource data in the notification in application-only mode.

As assinaturas no nível do chat também oferecem suporte à pesquisa baseada em palavras-chave por meio do parâmetro de consulta $search.Chat-level subscriptions also support keyword-based search via the $search query parameter.

Observação:Note. assinar para receber mensagens em um chat que esteja atualmente em pré-visualização.Subcribing to messages in a chat is currently in preview.

PermissõesPermissions

Tipo de permissãoPermission type Permissões (da com menos para a com mais privilégios)Permissions (from least to most privileged) Com suporte na versãoSupported in version
Delegada (conta corporativa ou de estudante)Delegated (work or school account) Chat.ReadChat.Read beta, v1.0beta, v1.0
Delegado (conta pessoal da Microsoft)Delegated (personal Microsoft account) Sem suporte.Not supported. Sem suporte.Not supported.
AplicativoApplication Chat.Read.AllChat.Read.All beta, v1.0beta, v1.0

Exemplo 1: assinar para receber mensagens em um chatExample 1: Subscribe to messages in a chat

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{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 textoExample 2: Subscribe to messages in a chat that contain certain text

A solicitação a seguir enviará mensagens que contêm Hello ao banco de dados do assinante.The following request will send messages that contain Hello to the subscriber.

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{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 recursosExample 3: Subscribe to messages (and replies) in a chat without resource data

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{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 mencionadoExample 4: Subscribe to message in a chat in which a specific user is mentioned

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.To get notifications only for messages in which a specific user has been mentioned, you can specify the user's ID (9a6eb4d1-826b-48b1-9627-b50836c8fee9 in this example) in the query.

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{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}"
}

Notificação de conteúdoNotification payloads

Dependendo da sua assinatura, você pode receber a notificação com dados de recursos ou sem ele.Depending on your subscription, you can either get the notification with resource data, or without it. 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.Subscribing with resource data allows you to get the message payload along with the notification, removing the need to call back and get the content.

Notificações com dados de recursosNotifications with resource data

Para notificações com dados de recursos, a carga se parece com a seguinte.For notifications with resource data, the payload looks like the following. Este conteúdo é para uma mensagem enviada em um bate-papo.This payload is for a message sent in a 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 obter detalhes sobre como validar tokens e descriptografar a carga útil, consulte Definir notificações de alteração que incluem dados de recursos.For details about how to validate tokens and decrypt the payload, see Set up change notifications that include resource data.

A carga de notificação descriptografada parece com a seguinte.The decrypted notification payload looks like the following. A carga está de acordo com o esquema chatMessage.The payload conforms to the chatMessage schema. A carga é semelhante à devolvida pelas operações GET.The payload is similar to that returned by GET operations.

{
  "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 recursosNotifications without resource data

Notificações sem dados de recursos dão informações suficientes para fazer chamadas GET para obter o conteúdo da mensagem.Notifications without resource data give you enough information to make GET calls to get the message content. As assinaturas para notificações sem dados de recursos não exigem um certificado de criptografia (porque os dados reais dos recursos não são enviados).Subscriptions for notifications without resource data do not require an encryption certificate (because actual resource data is not sent over).

A carga parece ser a seguinte.The payload looks like the following. Este conteúdo é para uma mensagem enviada em um canal.This payload is for a message sent in a channel.

 {
  "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.The resource and @odata.id properties can be used to make calls to Microsoft Graph to get the payload for the message. As chamadas GET sempre retornarão o estado atual da mensagem.GET calls will always return the current state of the message. 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.If the message is changed between when the notification is sent and when the message is retrieved, the operation will return the updated message.

Confira tambémSee also