chatMessage: delta
Namespace: microsoft.graph
Retrieve the list of messages (without the replies) in a channel of a team. By using delta query, you can get new or updated messages in a channel.
Note: Delta will only return messages within the last eight months. You can use GET /teams/{team-id}/channels/{channel-id}/messages to retrieve older messages.
Delta query supports both full synchronization that retrieves all the messages in the specified channel, and incremental synchronization that retrieves those messages that have been added or changed in the channel since the last synchronization. Typically, you would do an initial full synchronization, and then get incremental changes to that messages view periodically.
To get the replies for a message, use the list message replies or the get message reply operation.
A GET request with the delta function returns either:
- A
@odata.nextLink
(that contains a URL with a delta function call and askipToken
), or - A
@odata.deltaLink
(that contains a URL with a delta function call anddeltaToken
).
State tokens are opaque to the client. To proceed with a round of change tracking, copy and apply the @odata.nextLink
or @odata.deltaLink
URL returned from the last GET request to the next delta function call for that same calendar view. A @odata.deltaLink
returned in a response signifies that the current round of change tracking is complete. You can save and use the @odata.deltaLink
URL when you begin to retrieve more changes (messages changed or posted after acquiring @odata.deltaLink
).
For more information, see the delta query documentation.
This API is available in the following national cloud deployments.
Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
Permission type | Least privileged permissions | Higher privileged permissions |
---|---|---|
Delegated (work or school account) | ChannelMessage.Read.All | Group.Read.All, Group.ReadWrite.All |
Delegated (personal Microsoft account) | Not supported. | Not supported. |
Application | ChannelMessage.Read.Group | ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All |
Note
The ChannelMessage.Read.Group permission uses resource-specific consent.
HTTP request
GET /teams/{team-id}/channels/{channel-id}/messages/delta
Query parameters
Tracking changes in channel messages incurs a round of one or more delta function calls. If you use any query parameter (other than $deltatoken
and $skiptoken
), you must specify it in the initial delta request. Microsoft Graph automatically encodes any specified parameters into the token portion of the @odata.nextLink
or @odata.deltaLink
URL provided in the response.
You only need to specify any query parameters once upfront.
In subsequent requests, copy and apply the @odata.nextLink
or @odata.deltaLink
URL from the previous response, as that URL already includes the encoded parameters.
Query parameter | Type | Description |
---|---|---|
$deltatoken |
string | A state token returned in the @odata.deltaLink URL of the previous delta function call, indicating the completion of that round of change tracking. Save and apply the entire @odata.deltaLink URL including this token in the first request of the next iteration of change tracking for that collection. |
$skiptoken |
string | A state token returned in the @odata.nextLink URL of the previous delta function call, indicating that there are further changes to be tracked. |
Optional OData query parameters
The following OData query parameters are supported by this API:
$top
represents the maximum number of messages to fetch in a call. The upper limit is 50.$skip
represents how many messages to skip at the beginning of the list.$filter
allows returning messages that meet a certain criteria. The only property that supports filtering islastModifiedDateTime
, and only the gt operator is supported. For example,../messages/delta?$filter=lastModifiedDateTime gt 2019-02-27T07:13:28.000z
will fetch any reply chain (each channel post message and associated reply messages) created or changed after the specified date time.$expand
allows expanding properties for each channel message. Only replies is supported. If a channel message contains more than 1000 replies,replies@odata.nextLink
is provided for pagination.
Note: For
$expand
query parameter, please refer to List Channel Messages.
Request headers
Header | Value |
---|---|
Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
Request Body
Don't supply a request body for this method.
Response
If successful, this method returns a 200 OK
response code and a collection of chatMessage objects in the response body. The response also includes a @odata.nextLink
URL or a @odata.deltaLink
URL.
Examples
Example 1: Initial synchronization
The following example shows a series of three requests to synchronize the messages in the given channel. There are five messages in the channel.
- Step 1: initial request and response.
- Step 2: second request and response
- Step 3: third request and final response.
For brevity, the sample responses show only a subset of the properties for an event. In an actual call, most event properties are returned.
See also what you do to retrieve additional changes.
Initial request
In this example, the channel messages are being synchronized for the first time, so the initial sync request does not include any state token. This round returns all the events in that calendar view.
The request specifies the optional request header, odata.top, returning 2 events at a time.
GET https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$top=2
Initial request response
The response includes two messages and a @odata.nextLink
response header with a skipToken
. The @odata.nextLink
URL indicates there are more messages in the channel to get.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(chatMessage)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$skiptoken=-FG3FPHv7HuyuazNLuy3eXlzQGbEjYLUsW9-pYkmXgn5KGsaOwrCoor2W23dGNNM1KtAX4AyvpFQNVsBgsEwUOX9lw8x9zDumgJy-C-UbjZLlZDQACyC9FyrVelZus9n.--rshdLwy_WBFJd8anPXJPbSUtUD7r3V4neB5tcrG58",
"value": [
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1606515483514",
"messageType": "message",
"createdDateTime": "2020-11-27T22:18:03.514Z",
"lastModifiedDateTime": "2020-11-27T22:18:03.514Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1606515483514?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1606515483514&parentMessageId=1606515483514",
"policyViolation": null,
"eventDetail": null,
"id": "1606515483514",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "Test"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
},
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1606691795113",
"messageType": "message",
"createdDateTime": "2020-11-29T23:16:35.113Z",
"lastModifiedDateTime": "2020-11-29T23:16:35.113Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1606691795113?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1606691795113&parentMessageId=1606691795113",
"policyViolation": null,
"eventDetail": null,
"id": "1606691795113",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 11/29/2020 3:16:31 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
]
}
Second request
The second request specifies the @odata.nextLink
URL returned from the previous response. Notice that it no longer has to specify the same top parameters as in the initial request, as the skipToken
in the @odata.nextLink
URL encodes and includes them.
GET https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$skiptoken=-FG3FPHv7HuyuazNLuy3eXlzQGbEjYLUsW9-pYkmXgn5KGsaOwrCoor2W23dGNNM1KtAX4AyvpFQNVsBgsEwUOX9lw8x9zDumgJy-C-UbjZLlZDQACyC9FyrVelZus9n.--rshdLwy_WBFJd8anPXJPbSUtUD7r3V4neB5tcrG58
Second request response
The second response returns the next 2 messages and a @odata.nextLink
response header with a skipToken
, indicates there are more messages in the channel to get.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(chatMessage)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$skiptoken=8UusBixEHS9UUau6uGcryrA6FpnWwMJbuTYILM1PArHxnZzDVcsHQrijNzCyIVeEauMQsKUfMhNjLWFs1o4sBS_LofJ7xMftZUfec_pijuT6cAk5ugcWCca9RCjK7iVj.DKZ9w4bX9vCR7Sj9P0_qxjLAAPiEZgxlOxxmCLMzHJ4",
"value": [
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1606691812117",
"messageType": "message",
"createdDateTime": "2020-11-29T23:16:52.117Z",
"lastModifiedDateTime": "2020-11-29T23:16:52.117Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1606691812117?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1606691812117&parentMessageId=1606691812117",
"policyViolation": null,
"id": "1606691812117",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 11/29/2020 3:16:51 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
},
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1606691846203",
"messageType": "message",
"createdDateTime": "2020-11-29T23:17:26.203Z",
"lastModifiedDateTime": "2020-11-29T23:17:26.203Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1606691846203?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1606691846203&parentMessageId=1606691846203",
"policyViolation": null,
"id": "1606691846203",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 11/29/2020 3:17:25 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
]
}
Third request
The third request continues to use the latest @odata.nextLink
returned from the last sync request.
GET https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$skiptoken=8UusBixEHS9UUau6uGcryrA6FpnWwMJbuTYILM1PArHxnZzDVcsHQrijNzCyIVeEauMQsKUfMhNjLWFs1o4sBS_LofJ7xMftZUfec_pijuT6cAk5ugcWCca9RCjK7iVj.DKZ9w4bX9vCR7Sj9P0_qxjLAAPiEZgxlOxxmCLMzHJ4
Third request response
The third response returns the only remaining messages in the channel and a @odata.deltaLink
response header with a deltaToken
which indicates that all messages in the channel have been read. Save and use the @odata.deltaLink
URL to query for any new messages starting from this point onwards.
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/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_y_eMWVQtBO_ejzzyIxl00ji-tQ3HzAbW4liZAVG88lO3nG_6-MBFoHY1n8y21YUzjocG-Cn1tCNeeLPLTzIe5Dw.EP9gLiCoF2CE_e6l_m1bTk2aokD9KcgfgfcLGqd1r_4",
"value": [
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1611351582080",
"messageType": "message",
"createdDateTime": "2021-01-22T21:39:42.08Z",
"lastModifiedDateTime": "2021-01-22T21:39:42.08Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1611351582080?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1611351582080&parentMessageId=1611351582080",
"policyViolation": null,
"id": "1611351582080",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 1/22/2021 1:39:39 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
},
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1611351603178",
"messageType": "message",
"createdDateTime": "2021-01-22T21:40:03.178Z",
"lastModifiedDateTime": "2021-01-22T21:40:03.178Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1611351603178?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1611351603178&parentMessageId=1611351603178",
"policyViolation": null,
"id": "1611351603178",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 1/22/2021 1:40:00 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
]
}
Example 2: Retrieving additional changes
Using the @odata.deltaLink
from the last request in the last round, you can get only those messages that changed (by being added, or updated) in that channel since then. Your request should look like the following, assuming you prefer to keep the same maximum page size in the response:
Request
GET https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_y_eMWVQtBO_ejzzyIxl00ji-tQ3HzAbW4liZAVG88lO3nG_6-MBFoHY1n8y21YUzjocG-Cn1tCNeeLPLTzIe5Dw.EP9gLiCoF2CE_e6l_m1bTk2aokD9KcgfgfcLGqd1r_4
Response
Note: The response object shown here might be shortened for readability.
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/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_yjz2nsMoh1gXNtXii7s78HapCi5woifXqwXlVNxICh8wUUnvE2gExsa8eZ2Vy_ch5rVIhm067_1mUPML3iYUVyg.3o0rhgaBUduuxOr98An5pjBDP5JjKUiVWku3flSiOsk",
"value": [
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1616989510408",
"messageType": "message",
"createdDateTime": "2021-03-29T03:45:10.408Z",
"lastModifiedDateTime": "2021-03-29T03:45:10.408Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1616989510408?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1616989510408&parentMessageId=1616989510408",
"policyViolation": null,
"id": "1616989510408",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "Hello World 28th March 2021"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
]
}