Realtime updates
Realtime updates allow you to receive notifications when lists or items are created, updated, or deleted. This can be useful when building collaborative applications, chat applications, or any other application which requires real-time data.
Realtime updates can be enabled or disabled for each list. If a list has realtime capabilities enabled, then you can receive updates for that list and any items within it. You can enable realtime capabilities for a list by setting the realtime field to true.
To receive realtime updates, you need to create a websocket connection to the following URL:
wss://realtime.jsonpad.ioThe websocket connection is secured using TLS, so you need to connect to it using the wss protocol. You can connect using the native WebSocket API or using a library like Socket.IO.
You need to authenticate using a token, included in the x-api-token header. See Token Permissions for help with setting up a token.
You may prefer to use the Realtime SDK since it handles all of the internal logic for you. See Using the SDKs for more information.
When you connect to the websocket, you can specify which types of events you want to receive, and optionally which lists and/or items you want to receive updates for. Use the following parameters:
eventTypesstringA comma-separated list of event types.
The following event types are available:
'list-created': A list was created'list-updated': A list was updated'list-deleted': A list was deleted'item-created': An item was created'item-updated': An item was updated'item-restored': An item was restored to a previous state'item-deleted': An item was deleted
listIdsstringA comma-separated list of List ids or path names.itemIdsstringA comma-separated list of Item ids or alias values.
Here's an example:
wss://realtime.jsonpad.io?eventTypes=list-updated,item-created,item-updated&itemIds=dd7383c8-238f-4d70-bf1a-85c79f63e51bNote that if you don't specify any listIds or itemIds, you will receive updates for all lists and/or items. You can also use * to denote "all lists" or "all items".
When a realtime event occurs, you will receive a message with the following data:
{listId: "dd7383c8-238f-4d70-bf1a-85c79f63e51b"itemId: "94edbcd9-8e5a-4b75-b17e-4a2be1ca626b"model: null}- required
listIdstringThe id of the list that was created / updated / deleted, or the id of the list which contains the item that was created / updated / deleted. - optional
itemIdstringThe id of the Item that was created / updated / deleted (only if this is an item event). - required
modelobjectA copy of the list or item that was created / updated / deleted.
Item data will generally be included in the model field for item events.
However, for performance reasons there is a maximum size limit for realtime events. This means that if an item's data is relatively large (greater than ~50KB), the data will not be included.
In this case, you can still use the realtime API to receive realtime events when an item changes, but you will need to manually re-fetch the item with its data attached via the API or SDK.