chatMessages: delta

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported.

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.

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 calendar 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 nextLink (that contains a URL with a delta function call and a skipToken), or
  • A deltaLink (that contains a URL with a delta function call and deltaToken).

State tokens are completely opaque to the client. To proceed with a round of change tracking, simply copy and apply the nextLink or deltaLink URL returned from the last GET request to the next delta function call for that same calendar view. A deltaLink returned in a response signifies that the current round of change tracking is complete. You can save and use the deltaLink URL when you begin the next round.

For more information, see the delta query documentation.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission Type Permissions (from least to most privileged)
Delegated (work or school account) Group.Read.All, Group.ReadWrite.All
Delegated (personal Microsoft account) Not Supported
Application Group.Read.All, Group.ReadWrite.All

Note

Before calling this API with application permissions, you must request access. For details, see Protected APIs in Microsoft Teams.

HTTP request

GET /teams/{id}/channels/{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 nextLink or deltaLink URL provided in the response.

You only need to specify any query parameters once upfront.

In subsequent requests, copy and apply the nextLink or 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 deltaLink URL of the previous delta function call, indicating the completion of that round of change tracking. Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that collection.
$skiptoken string A state token returned in the 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 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 is lastModifiedDateTime, and only the gt and ge operators are supported. For example, ../messages/delta?$filter=lastModifiedDateTime ge 2019-02-27T07:13:28.000z will fetch any messages created or changed after the specified date time.

Request headers

Header Value
Authorization Bearer {token}. Required.
Content-Type application/json

Request Body

Do not 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 nextLink URL or a 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.

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'll do in the next round.

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 will return all the events in that calendar view.

The request specifies the optional request header, odata.top, returning 2 events at a time.

GET /teams/{id}/channels/{id}/messages/delta?$top=2

Initial request response

The response includes two messages and a @odata.nextLink response header with a skipToken. The nextLink URL indicates there are more messages in the channel to get.

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
    "@odata.context": "/$metadata#Collection(Microsoft.Teams.GraphSvc.chatMessage)",
    "@odata.nextLink": "/teams('id')/channels('id')/messages/delta?$skiptoken=c3RhcnRUaW1lPTE1NTEyMTUzMjU0NTkmcGFnZVNpemU9MjA%3d",
    "value": [
		{
			"id": "id-value",
			"replyToId": "id-value",
			"from" : {
				"user": { 
					"id": "id-value",
					"displayName": "John Doe"
				}  
			},
			"etag": "id-value",
			"messageType": "message",
			"createdDateTime": "2019-03-06T07:40:20.152Z",
			"lastModifiedDateTime": "2019-03-06T07:40:20.152Z",
			"body": {
				"content": "Hello World",
				"contentType": "Text"
			},
			"attachments": [],
			"mentions": [],
			"importance": "normal",
			"reactions": [],
			"locale": "en-us"
		},
		{
			"id": "id-value",
			"replyToId": "id-value",
			"from" : {
				"user": { 
					"id": "id-value",
					"displayName": "John Doe"
				}  
			},
			"etag": "id-value",
			"messageType": "message",
			"createdDateTime": "2019-03-06T08:40:20.152Z",
			"lastModifiedDateTime": "2019-03-06T08:40:20.152Z",
			"body": {
				"content": "Hello World",
				"contentType": "Text"
			},
			"attachments": [],
			"mentions": [],
			"importance": "normal",
			"reactions": [],
			"locale": "en-us"
		}
	]
}

Second request

The second request specifies the 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 nextLink URL encodes and includes them.

GET /teams/{id}/channels/{id}/messages/delta?$skiptoken=c3RhcnRUaW1lPTE1NTEyMTUzMjU0NTkmcGFnZVNpemU9MjA%3d

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.

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
    "@odata.context": "/$metadata#Collection(Microsoft.Teams.GraphSvc.chatMessage)",
    "@odata.nextLink": "/teams('id')/channels('id')/messages/delta?$skiptoken=c3RhcnRUaW1lPTE1NTEyODcyMzY2NzgmcGFnZVNpemU9MjA%3d",
    "value": [
		{
			"id": "id-value",
			"replyToId": "id-value",
			"from" : {
				"user": { 
					"id": "id-value",
					"displayName": "John Doe"
				}  
			},
			"etag": "id-value",
			"messageType": "message",
			"createdDateTime": "2019-03-06T09:40:20.152Z",
			"lastModifiedDateTime": "2019-03-06T09:40:20.152Z",
			"body": {
				"content": "Hello World",
				"contentType": "Text"
			},
			"attachments": [],
			"mentions": [],
			"importance": "normal",
			"reactions": [],
			"locale": "en-us"
		},
		{
			"id": "id-value",
			"replyToId": "id-value",
			"from" : {
				"user": { 
					"id": "id-value",
					"displayName": "John Doe"
				}  
			},
			"etag": "id-value",
			"messageType": "message",
			"createdDateTime": "2019-03-06T09:50:20.152Z",
			"lastModifiedDateTime": "2019-03-06T09:50:20.152Z",
			"body": {
				"content": "Hello World",
				"contentType": "Text"
			},
			"attachments": [],
			"mentions": [],
			"importance": "normal",
			"reactions": [],
			"locale": "en-us"
		}
	]
}

Third request

The third request continues to use the latest nextLink returned from the last sync request.

GET /teams/{id}/channels/{id}/messages/delta?$skiptoken=c3RhcnRUaW1lPTE1NTEyODcyMzY2NzgmcGFnZVNpemU9MjA%3d

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 deltaLink URL to query for any new messages starting from this point in the next round.

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
    "@odata.context": "/$metadata#Collection(Microsoft.Teams.GraphSvc.chatMessage)",
    "@odata.deltaLink": "/teams('id')/channels('id')/messages/delta?$deltatoken=c3RhcnRUaW1lPTE1NTEyODc1ODA0OTAmcGFnZVNpemU9MjA%3d",
    "value": [
		{
			"id": "id-value",
			"replyToId": "id-value",
			"from" : {
				"user": { 
					"id": "id-value",
					"displayName": "John Doe"
				}  
			},
			"etag": "id-value",
			"messageType": "message",
			"createdDateTime": "2019-03-06T10:40:20.152Z",
			"lastModifiedDateTime": "2019-03-06T10:40:20.152Z",
			"body": {
				"content": "Hello World",
				"contentType": "Text"
			},
			"attachments": [],
			"mentions": [],
			"importance": "normal",
			"reactions": [],
			"locale": "en-us"
		}
	]
}

Example 2: Retrieving additional changes

Using the deltaLink from the last request in the last round, you will be able to get only those messages that have changed (by being added, or updated) in that channel since then. Your request will look like the following, assuming you prefer to keep the same maximum page size in the response:

Request

GET /teams/{id}/channels/{id}/messages/delta?$deltatoken=c3RhcnRUaW1lPTE1NTEyODc1ODA0OTAmcGFnZVNpemU9MjA%3d

Response

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
    "@odata.context": "/$metadata#Collection(Microsoft.Teams.GraphSvc.chatMessage)",
    "@odata.deltaLink": "/teams('id')/channels('id')/messages/delta?$deltatoken=c3RhcnRUaW1l5Ti1NTEyODc1ODB0OTAyXGFdZVNpemU9MjA%3d",
    "value": [
		{
			"id": "id-value",
			"replyToId": "id-value",
			"from" : {
				"user": { 
					"id": "id-value",
					"displayName": "John Doe"
				}  
			},
			"etag": "id-value",
			"messageType": "message",
			"createdDateTime": "2019-03-06T10:40:20.152Z",
			"lastModifiedDateTime": "2019-03-06T10:40:20.152Z",
			"body": {
				"content": "Hello World",
				"contentType": "Text"
			},
			"attachments": [],
			"mentions": [],
			"importance": "normal",
			"reactions": [],
			"locale": "en-us"
		}
	]
}