sync method

Future<SyncUpdate> sync({ String? filter, String? since, bool? fullState, PresenceType? setPresence, int? timeout, bool? useStateAfter, })

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?>);
}