sync method
Synchronise the client's state with the latest state on the server. Clients use this API when they first log in to get an initial snapshot of the state on the server, and then continue to call this API to get incremental deltas to the state, and to receive new messages.
Note: This endpoint supports lazy-loading. See Filtering
for more information. Lazy-loading members is only supported on the state
part of a
RoomFilter
for this endpoint. When lazy-loading is enabled, servers MUST include the
syncing user's own membership event when they join a room, or when the
full state of rooms is requested, to aid discovering the user's avatar &
displayname.
Further, like other members, the user's own membership event is eligible
for being considered redundant by the server. When a sync is limited
,
the server MUST return membership events for events in the gap
(between since
and the start of the returned timeline), regardless
as to whether or not they are redundant. This ensures that joins/leaves
and profile changes which occur during the gap are not lost.
Note that the default behaviour of state
is to include all membership
events, alongside other state, when lazy-loading is not enabled.
filter
The ID of a filter created using the filter API or a filter JSON
object encoded as a string. The server will detect whether it is
an ID or a JSON object by whether the first character is a "{"
open brace. Passing the JSON inline is best suited to one off
requests. Creating a filter using the filter API is recommended for
clients that reuse the same filter multiple times, for example in
long poll requests.
See Filtering for more information.
since
A point in time to continue a sync from. This should be the
next_batch
token returned by an earlier call to this endpoint.
fullState
Controls whether to include the full state for all rooms the user
is a member of.
If this is set to true
, then all state events will be returned,
even if since
is non-empty. The timeline will still be limited
by the since
parameter. In this case, the timeout
parameter
will be ignored and the query will return immediately, possibly with
an empty timeline.
If false
, and since
is non-empty, only state which has
changed since the point indicated by since
will be returned.
By default, this is false
.
setPresence
Controls whether the client is automatically marked as online by
polling this API. If this parameter is omitted then the client is
automatically marked as online when it uses this API. Otherwise if
the parameter is set to "offline" then the client is not marked as
being online when it uses this API. When set to "unavailable", the
client is marked as being idle.
timeout
The maximum time to wait, in milliseconds, before returning this
request. If no events (or other data) become available before this
time elapses, the server will return a response with empty fields.
By default, this is 0
, so the server will return immediately
even if the response is empty.
useStateAfter
Controls whether to receive state changes between the previous sync
and the start of the timeline, or between the previous sync and
the end of the timeline.
If this is set to true
, servers MUST respond with the state
between the previous sync and the end of the timeline in
state_after
and MUST omit state
.
If false
, servers MUST respond with the state between the previous
sync and the start of the timeline in state
and MUST omit
state_after
.
Even if this is set to true
, clients MUST update their local state
with events in state
and timeline
if state_after
is missing in
the response, for compatibility with servers that don't support this
parameter.
By default, this is false
.
Implementation
Future<SyncUpdate> sync({
String? filter,
String? since,
bool? fullState,
PresenceType? setPresence,
int? timeout,
bool? useStateAfter,
}) async {
final requestUri = Uri(
path: '_matrix/client/v3/sync',
queryParameters: {
if (filter != null) 'filter': filter,
if (since != null) 'since': since,
if (fullState != null) 'full_state': fullState.toString(),
if (setPresence != null) 'set_presence': setPresence.name,
if (timeout != null) 'timeout': timeout.toString(),
if (useStateAfter != null) 'use_state_after': useStateAfter.toString(),
},
);
final request = Request('GET', baseUri!.resolveUri(requestUri));
request.headers['authorization'] = 'Bearer ${bearerToken!}';
final response = await httpClient.send(request);
final responseBody = await response.stream.toBytes();
if (response.statusCode != 200) unexpectedResponse(response, responseBody);
final responseString = utf8.decode(responseBody);
final json = jsonDecode(responseString);
return SyncUpdate.fromJson(json as Map<String, Object?>);
}