chatMessage: delta

Namespace: microsoft.graph

Obtenha a lista de mensagens de todos os chats dos quais um usuário é participante, incluindo chats individuais, chats em grupo e chats de reunião. Ao usar a consulta delta, você pode obter mensagens novas ou atualizadas.

Observação: Delta só retorna mensagens nos últimos oito meses. Você pode usar GET /users/{id | user-principal-name}/chats/getAllMessages para recuperar mensagens mais antigas. A consulta delta suporta a sincronização completa que obtém todas as mensagens de todos os chats dos quais um usuário é um participante e a sincronização incremental que obtém mensagens adicionadas ou alteradas desde a última sincronização. Normalmente, você faz uma sincronização completa inicial e, em seguida, obtém alterações incrementais nessa exibição de mensagens periodicamente.

Para obter as respostas para uma mensagem, use a lista de respostas de mensagens ou as operações de obter resposta de mensagem .

Uma solicitação GET com a função delta retorna um dos seguintes:

  • Um @odata.nextLink que contém uma URL com uma chamada de função delta e um skipToken
  • Um @odata.deltaLink que contém uma URL com uma chamada de função delta e um deltaToken

Os tokens de estado são opacos para o cliente. Para prosseguir com uma rodada de controle de alterações, copie e aplique a URL @odata.nextLink ou @odata.deltaLink retornada da última solicitação GET para a próxima chamada de função delta . Um @odata.deltaLink retornado em uma resposta significa que a rodada atual de controle de alterações foi concluída. Você pode salvar e usar a URL @odata.deltaLink quando começar a recuperar mais alterações (mensagens alteradas ou postadas após a aquisição de @odata.deltaLink).

Para obter mais informações, consulte a documentação da consulta Delta.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global Governo dos EUA L4 US Government L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

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

Solicitação HTTP

GET /users/{id | user-principal-name}/chats/getAllMessages/delta

Parâmetros de consulta

O acompanhamento de alterações em mensagens incorre em uma rodada de uma ou mais chamadas de função delta . Se você usar qualquer parâmetro de consulta (diferente de $deltatoken e $skiptoken), especifique-o na primeira solicitação delta. O Microsoft Graph codifica automaticamente todos os parâmetros especificados na parte do token da URL @odata.nextLink ou @odata.deltaLink fornecida na resposta.

Você só precisa especificar os parâmetros de consulta uma vez.

Em solicitações subsequentes, copie e aplique a URL @odata.nextLink ou @odata.deltaLink da resposta anterior, pois essa URL já inclui os parâmetros codificados.

Parâmetro de consulta Tipo Descrição
$deltatoken Cadeia de caracteres Um token de estado retornado na URL @odata.deltaLink da chamada de função delta anterior que indica que a conclusão dessa rodada de controle de alterações. Salve e aplique toda a URL @odata.deltaLink , incluindo esse token, na primeira solicitação da próxima iteração de controle de alterações para essa coleção.
$skiptoken Cadeia de caracteres Um token de estado retornado na URL @odata.nextLink da chamada de função delta anterior que indica que outras alterações estão disponíveis para serem controladas.

Parâmetros de consulta OData opcionais

Essa API dá suporte aos seguintes parâmetros de consulta OData:

  • $top Representa o número máximo de mensagens a serem buscadas em uma chamada. O limite superior é 50.
  • $skip Representa quantas mensagens ignorar no início da lista.
  • $filter Retorna mensagens que atendem a determinados critérios. A única propriedade que dá suporte a filtros é lastModifiedDateTime e apenas o gt operador tem suporte. Por exemplo, ../messages/delta?$filter=lastModifiedDateTime gt 2024-08-27T07:13:28.000z busca qualquer mensagem criada ou alterada após a data e hora especificadas.

Cabeçalhos de solicitação

Cabeçalho Valor
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.

Corpo da Solicitação

Não forneça um corpo de solicitação para esse método.

Resposta

Se bem sucedido, este método retorna um código de resposta 200 OK e uma coleção de objetos chatMessage no corpo da resposta. A resposta também inclui uma URL @odata.nextLink ou uma URL @odata.deltaLink .

Exemplos

Exemplo 1: sincronização inicial

O exemplo a seguir mostra uma série de três solicitações para sincronizar as mensagens. A resposta consiste em três mensagens:

Para resumir, as respostas de exemplo mostram apenas um subconjunto das propriedades de uma mensagem. Em uma chamada real, a maioria das propriedades da mensagem é retornada.

Veja também o que você pode fazer na próxima rodada para obter mais mensagens.

Solicitação inicial

Neste exemplo, as mensagens de chat são sincronizadas pela primeira vez e a solicitação de sincronização inicial não inclui nenhum token de estado.

A solicitação especifica o parâmetro de consulta opcional $top que retorna duas mensagens por vez.

GET https://graph.microsoft.com/v1.0/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$top=2

Resposta inicial da solicitação

A resposta inclui duas mensagens e um cabeçalho de resposta @odata.nextLink com um skipToken. A URL @odata.nextLink indica que mais mensagens nos chats estão disponíveis para recuperação.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$skiptoken=a-5fqdzHFr_L_cc7C0q1F-HCB8Z9SjwOsMN37XV5yfSnYgK4jVGVGEl25GFlxKWq0Wv6quL-5qcNg4nUnxzof6namZ_DM5no-hcL515cSrRGDoRLn38fZE1AXoDugSTOohOq3YRCYLqJbFGIoovMPTar32oLuoltHixme-Bf1lZtscv1wv5uu-MtkpYZIT0uDw-umQUK7mLNjMcyhNaifDrdemGUDMaQ25_QuHukNbkXcxsKMJdJ288p9IkaSeEyJHX5a6T_kEdAmuffsdzOGY8mLbLc7VEsUL75rGdt2aiKkywaPHsT9bDGV7MBo7WM2g_kdPeLdRPSdSxxhkGpNA.y_WMscy7negz0HZPhgjH-YyzsdeXzr2UDSfNrdzC78A",
  "value": [
    {
      "replyToId": null,
      "etag": "1727366299993",
      "messageType": "message",
      "createdDateTime": "2024-09-26T15:58:19.993Z",
      "lastModifiedDateTime": "2024-09-26T15:58:19.993Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1727366299993",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<div>\n<div itemprop=\"copy-paste-block\">reply 9&nbsp;to new conv</div>\n</div>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    },
    {
      "replyToId": null,
      "etag": "1727216579286",
      "messageType": "message",
      "createdDateTime": "2024-09-24T22:22:59.286Z",
      "lastModifiedDateTime": "2024-09-24T22:22:59.286Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:2a247d5dadc24f408d009e4ae84502cf@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1727216579286",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<div>\n<div itemprop=\"copy-paste-block\">reply 10 to new conv</div>\n</div>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}

Segunda solicitação

A segunda solicitação especifica a URL @odata.nextLink retornada da resposta anterior. Observe que ele não precisa mais especificar o mesmo $top parâmetro da solicitação inicial, pois o URL do @odata.nextLink codifica skipToken e inclui esses parâmetros.

GET https://graph.microsoft.com/v1.0/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?&%24skiptoken=a-5fqdzHFr_L_cc7C0q1F-HCB8Z9SjwOsMN37XV5yfSnYgK4jVGVGEl25GFlxKWq0Wv6quL-5qcNg4nUnxzof6namZ_DM5no-hcL515cSrRGDoRLn38fZE1AXoDugSTOohOq3YRCYLqJbFGIoovMPTar32oLuoltHixme-Bf1lZtscv1wv5uu-MtkpYZIT0uDw-umQUK7mLNjMcyhNaifMIVTT-htmEOClLVwgcyWLR-sl9Qb73uTTtPXdFdMK6FDE4gpwvvKxvo2ChsW2c4eo77LDh6ZL_WQ8Luq00koQ6vHIrLBHPMUdOAxDxu-U7N7H4hsFn9aRDRdwRky7067A.V2a-J-86yXTd9SJMA4CHP6enI-Ab-bQzRgYujwsIwDo

Resposta da segunda solicitação

A segunda resposta retorna as próximas duas mensagens e um cabeçalho de resposta @odata.nextLink com um skipToken que indica que mais mensagens estão disponíveis para recuperação.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$skiptoken=yJQeoV00BlfhYsCMsrn1GnNz7v5S39NShp1U4rzLZnPsraIATwnnsvbdv52hvKp7AAG-Bcwdu7dA7UweXHvGYQ2M5eysh-cNz6EZICZp7kM9HtmQHu7JU-_sX5S1edvEQxyAgm1R2HXk4R9_TWn9ZAu1BRQ-elS9hg0f8BlwKLCIluuSPS2ZuNVnQTOOYMMpmzKGX4wVVQUv0UlrIFZIPWTeriNpg5sJFd91n2GHSMnS7WaRTh3NSmvJE08ww-2CjGml2RjPyHfLHSqywuNt5BGNVj_vqsLbjetdDIYZFa_yaQqV_Bp5DaWM_nXD8RjVULH7H4ATXoUiG3Etsd_Nhd_GIYoxV6x2_rmbh928WPGSsenCOa352tyFxmuyTH0ozDmU4onVbGnOBQEYJDKZjuIeNVW-E19VHthjZ9GvYGE.NHJkfAbRu3Qoozl699AinriiHvWofLVnWkB5wEJmZlk",
  "value": [
    {
      "replyToId": null,
      "etag": "1726706286844",
      "messageType": "message",
      "createdDateTime": "2024-09-19T00:38:06.844Z",
      "lastModifiedDateTime": "2024-09-19T00:38:06.844Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1726706286844",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<p>Not one message, but several combined together to give you the full picture</p>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    },
    {
      "replyToId": null,
      "etag": "1726706276201",
      "messageType": "message",
      "createdDateTime": "2024-09-19T00:37:56.201Z",
      "lastModifiedDateTime": "2024-09-19T00:37:56.201Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1726706276201",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<p>Dive into the possibilities of incorporating context into ML evaluations by looking at entire conversations</p>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}

Terceira solicitação

A terceira solicitação continua a usar o @odata.nextLink mais recente retornado da última solicitação de sincronização.

GET  https://graph.microsoft.com/v1.0/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$skiptoken=8UusBixEHS9UUau6uGcryrA6FpnWwMJbuTYILM1PArHxnZzDVcsHQrijNzCyIVeEauMQsKUfMhNjLWFs1o4sBS_LofJ7xMftZUfec_pijuT6cAk5ugcWCca9RCjK7iVj.DKZ9w4bX9vCR7Sj9P0_qxjLAAPiEZgxlOxxmCLMzHJ4

Resposta da terceira solicitação

A terceira resposta retorna as únicas mensagens restantes e um cabeçalho de resposta @odata.deltaLink com um deltaToken que indica que todas as mensagens são retornadas. Salve e use a URL @odata.deltaLink para consultar novas mensagens adicionadas ou alteradas a partir deste ponto.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_y_eMWVQtBO_ejzzyIxl00ji-tQ3HzAbW4liZAVG88lO3nG_6-MBFoHY1n8y21YUzjocG-Cn1tCNeeLPLTzIe5Dw.EP9gLiCoF2CE_e6l_m1bTk2aokD9KcgfgfcLGqd1r_4",
  "value": [
    {
      "replyToId": null,
      "etag": "1726706340932",
      "messageType": "message",
      "createdDateTime": "2024-09-19T00:39:00.932Z",
      "lastModifiedDateTime": "2024-09-19T00:39:00.932Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1726706340932",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<p>let's get started!</p>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}

Exemplo 2: a próxima rodada para obter mais mensagens

Usando o @odata.deltaLink da última solicitação na última rodada, você pode obter apenas as mensagens que foram alteradas (adicionadas ou atualizadas) desde que o @odata.deltaLink foi adquirido. Sua solicitação deve ter a seguinte aparência, supondo que você queira manter o mesmo tamanho máximo de página na resposta.

Solicitação

O exemplo a seguir mostra uma solicitação.

GET https://graph.microsoft.com/v1.0/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_y_eMWVQtBO_ejzzyIxl00ji-tQ3HzAbW4liZAVG88lO3nG_6-MBFoHY1n8y21YUzjocG-Cn1tCNeeLPLTzIe5Dw.EP9gLiCoF2CE_e6l_m1bTk2aokD9KcgfgfcLGqd1r_4

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(chatMessage)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_yjz2nsMoh1gXNtXii7s78HapCi5woifXqwXlVNxICh8wUUnvE2gExsa8eZ2Vy_ch5rVIhm067_1mUPML3iYUVyg.3o0rhgaBUduuxOr98An5pjBDP5JjKUiVWku3flSiOsk",
  "value": [
    {
      "replyToId": null,
      "etag": "1727366299999",
      "messageType": "message",
      "createdDateTime": "2024-09-26T15:58:19.993Z",
      "lastModifiedDateTime": "2024-09-26T17:58:19.993Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1727366299999",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "newly added content"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}
  • Last updated on