Synchronise the client's state and receive new messages.
GET {{baseUrl}}/sync?filter=66696p746572&since=s72594_4483_1934&full_state=false&set_presence=offline&timeout=30000
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 a StateFilter
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.
Request Params
| Key | Datatype | Required | Description |
|---|---|---|---|
filter | string | 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 | string | | 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_state | boolean | | 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 | string | | 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 | number | | 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. |
RESPONSES
status: OK
{"next_batch":"s72595_4483_1934","presence":{"events":[{"$ref":"../../event-schemas/examples/m.presence.yaml"}]},"account_data":{"events":[{"type":"org.example.custom.config","content":{"custom_config_key":"custom_config_value"}}]},"rooms":{"join":{"!726s6s6q:example.com":{"summary":{"m.heroes":["@alice:example.com","@bob:example.com"],"m.joined_member_count":2,"m.invited_member_count":0},"state":{"events":[{"$ref":"../../event-schemas/examples/m.room.member.yaml"}]},"timeline":{"events":[{"$ref":"../../event-schemas/examples/m.room.member.yaml"},{"$ref":"../../event-schemas/examples/m.room.message$m.text.yaml"}],"limited":true,"prev_batch":"t34-23535_0_0"},"ephemeral":{"events":[{"$ref":"../../event-schemas/examples/m.typing.yaml"}]},"account_data":{"events":[{"$ref":"../../event-schemas/examples/m.tag.yaml"},{"type":"org.example.custom.room.config","content":{"custom_config_key":"custom_config_value"}}]}}},"invite":{"!696r7674:example.com":{"invite_state":{"events":[{"sender":"@alice:example.com","type":"m.room.name","state_key":"","content":{"name":"My Room Name"}},{"sender":"@alice:example.com","type":"m.room.member","state_key":"@bob:example.com","content":{"membership":"invite"}}]}}},"knock":{"!223asd456:example.com":{"knock_state":{"events":[{"sender":"@alice:example.com","type":"m.room.name","state_key":"","content":{"name":"My Room Name"}},{"sender":"@bob:example.com","type":"m.room.member","state_key":"@bob:example.com","content":{"membership":"knock"}}]}}},"leave":{}}}