MAmatrix
Room participation

Synchronise the client's state and receive new messages.

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.

get/_matrix/client/v3/sync

Request

Query parameters

filterstring

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.

sincestring

A point in time to continue a sync from. This should be the next_batch token returned by an earlier call to this endpoint.

full_stateboolean

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.

set_presence'offline' | 'online' | 'unavailable'

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.

timeoutinteger

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.

use_state_afterboolean

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.

Servers MAY implement this parameter ahead of declaring support for the version of the spec in which it was introduced. Consequently, clients MAY set this parameter to true regardless of the /versions response. If they do, they can infer whether the server actually supports this parameter from the presence of state_after in the response. If state_after is missing, clients MUST behave as if they had not specified the parameter and update their local state with events in state and timeline.

By default, this is false.

Response

The initial snapshot or delta for the client to use to update their state.

device_listsobject

Information on end-to-end device updates, as specified in End-to-end encryption.

device_one_time_keys_countobject

Information on end-to-end encryption keys, as specified in End-to-end encryption.

next_batchstring required

The batch token to supply in the since param of the next /sync request.

to_deviceobject

Information on the send-to-device messages for the client device, as defined in Send-to-Device messaging.

Changes

No recorded changes to this operation across all 1 revision of this API.