Sync Events

LAST EDIT Mar 19 2024

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!

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!
nametypedescriptiondefaultoptional
channel_cidsstringList of Channel CIDs to sync.-
Last_sync_atstring - RFC3339 timestampThe timestamp indicating the starting point for the sync.-
With_inaccessible_cidsbooleanSet to true to add inaccessible_cids to responseFalse
User_idstringServer-side only. User ID which server acts upon-

Returned Events

Copied!

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!

There are a few constraints to keep in mind when using the sync endpoint.

Limited Number of Returned Events

Copied!

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!

Sync endpoint maxes out at 30 days. This means that generated more than 30 days prior to sync.

Limited Subset of Events

Copied!

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!

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.