Select your Platform:
Sync Events
Confused about "Sync Events"?
Let us know how we can improve our documentation:
The Sync endpoint provides a way to fetch a list of events that happened between an RFC3339 timestamp you provide and when Sync is called. At first glance, Sync is very similar to querying for events. The key distinction is that Sync provides a concise summary of the events that happened while offline instead of giving the current state (things deleted, updated etc). These events can help track changes that impacted channels while a client was offline.
Authorization
Copied!Confused about "Authorization"?
Let us know how we can improve our documentation:
Sync endpoint can be used by any authenticated user. It can be used from a user client and from a server client when user_id is provided.
For users to be able to receive results from Sync endpoint users do not need to have any specific permissions. However, to get useful results from the endpoint, the user must have read permissions for the target channels. Channels the user does not have read permissions to will yield notification.removed_from_channel as the returned events.
Request schema
Copied!Confused about " Request schema"?
Let us know how we can improve our documentation:
| name | type | description | default | optional |
|---|---|---|---|---|
| channel_cids | string | List of Channel CIDs to sync. | - | |
| Last_sync_at | string - RFC3339 timestamp | The timestamp indicating the starting point for the sync. | - | |
| With_inaccessible_cids | boolean | Set to true to add inaccessible_cids to response | False | |
| User_id | string | Server-side only. User ID which server acts upon | - |
Returned Events
Copied!Confused about "Returned Events"?
Let us know how we can improve our documentation:
Event Type | Description |
|---|---|
channel.created | Emitted when a channel is created. |
channel.deleted | Emitted when a channel is deleted. |
channel.hidden | Emitted when a channel is hidden. |
channel.truncated | Emitted when a channel is truncated. |
channel.updated | Emitted when a channel is successfully updated. |
channel.visible | Emitted when a channel is shown. |
message.deleted | Emitted when a message is deleted. |
message.new | Emitted when a message was successfully sent or when a message became visible after command execution. |
message.updated | Emitted when an event is updated with translation data or When message is updated. |
notification.added_to_channel | Sent to unsubscribed users when that user added to a channel. |
notification.removed_from_channel | Sent to unsubscribed users when that user removed from channel. |
reaction.deleted | Emitted when a reaction is deleted. |
reaction.new | Emitted when a new reaction is created. |
reaction.updated | Emitted when a reaction is updated. |
Notification events are a special case and are available to track new users being added or removed from a channel. When there have been multiple events on the same entity since a user last synced, this endpoint will return one event representing the current state of the entity.
For example, if sync were called on a message that had emitted three update events:
Sync would return one event representing the current state of the message.
Updating entities to the latest state also means when there are multiple different events contributing to the current state of an entity, sync will return a single event for the parent entity and nest contributing events within it.
For example, say Sync is called and the following events happened after its designated timestamp:
User Toly creates
message_1.User Laura adds a “like” reaction to
message_1.
Sync endpoint will return a new message event with a message object inside containing the reactions.
In this case Sync endpoint return events like this (pseudo-code):
Returned events will contain the same data as the entities they correspond with. For example, message.new and message.updated will contain the same message object that the messages endpoint would return.
Constraints
Copied!Confused about "Constraints"?
Let us know how we can improve our documentation:
There are a few constraints to keep in mind when using the sync endpoint.
Limited Number of Returned Events
Copied!Confused about "Limited Number of Returned Events"?
Let us know how we can improve our documentation:
Sync endpoint will return a maximum of 2000 events. If there are more than 2000 events between the designated timestamp and when Sync is called, Sync will return an error.
In the even that this error is returned, retry sync with a more recent timestamp.
Limited Timeframe for Sync
Copied!Confused about "Limited Timeframe for Sync"?
Let us know how we can improve our documentation:
Sync endpoint maxes out at 30 days. This means that generated more than 30 days prior to sync.
Limited Subset of Events
Copied!Confused about "Limited Subset of Events"?
Let us know how we can improve our documentation:
If you are familiar with the full list of events supported by Stream Chat, you might notice that many of those events are missing from the events returned by Sync.
Asynchronous Event Availability
Copied!Confused about "Asynchronous Event Availability"?
Let us know how we can improve our documentation:
Events become available in the Sync endpoint asynchronously. This means that recent(less than 15 minutes ago) events may be missing for a short period of time in response of the Sync endpoint. Because of asynchronous nature it is also possible that events that happened later may be present before earlier events are present.
Sync always returns events sorted in the order of their creation and not in the order that they became available to the Sync endpoint.