Realtime events

The Socket.IO events that keep every screen live: names, scopes and payload shapes.

The screens of everyone on an instance stay in step through a live connection. When somebody adds a note, moves an area or sends a message, the server pushes the change to every device that has that part of the map or that channel open. This page lists the events, who receives them and what they carry. It is meant for people building a wall display, a monitor or another integration on top of an instance. Requests that create and change data are described in REST API.

Connecting#

The connection is a Socket.IO connection to the instance's own address. The transport is WebSocket, with long polling as fallback.
Pass the access token in the handshake: io(origin, { auth: { token } }). A missing, invalid or revoked token is refused with an Unauthorized error.
Two namespaces exist. The default one carries content, presence and chat. /loc carries live positions. Both take the same token.
An access token lasts 15 minutes and so does the right to stay connected. About a minute before it runs out the server sends auth:expiring; answer with auth:renew and a fresh token to stay connected. If you do not, the server closes the connection after a short grace period, and a normal reconnect signs in again. Guest sessions cannot be extended past their fixed window.
If a session is revoked, for example after a password reset or a refresh token replay, the server disconnects its connections immediately.
Reconnect with a jittered back-off, and after every reconnect load the current state through the REST API before trusting the stream again.

Where events are sent#

The server does not broadcast everything to everyone. Each connection joins rooms, and each event is sent to the rooms it concerns.

Scope	How you join	Used for
Map region	Send `rooms:join_by_bounds` with `{ south, west, north, east }`. The server answers `rooms:joined` with the region keys. Joining again replaces the previous set.	Notes, areas, tasks
Chat channel	Send `chat:subscribe` with `{ channelIds: [...] }` (at most 200). Only channels the caller may read are joined.	Messages, typing, receipts
Personal	Automatic	Events addressed to one person, such as read state and geofence warnings
Location cell	On `/loc`, send `viewport:update` with the same bounds. The answer is `viewport:rooms`.	Live positions
Everyone	Automatic	Presence (except guests), building annotations and model placements

Map regions are cells of 0.1 degrees. A very large or invalid rectangle joins no rooms, so ask for the area the screen really shows. Restrictions apply on top of rooms: a restricted user is only sent items of their own groups, and person-private tasks go only to the people entitled to them. See Roles and permissions matrix. Guests receive only the events for notes marked visible to guests.

Notes, areas and tasks#

These events follow one pattern: the noun, then what happened. created and updated carry the full record as the REST API returns it. Removal events carry the identifier and the acting user's name.

Event	Payload	Sent when
`note:created`	the note	A note is created, restored, or moves into a region you watch.
`note:updated`	the note	Text, position, attachments or checklist ticks change.
`note:deleted`	`{ id, username }`	Deleted, or moved out of your region.
`note:archived`, `note:unarchived`	identifier and actor, the full note on unarchive	Archive state changes.
`zone:created`, `zone:updated`	the area	Sent to every region the area overlaps.
`zone:deleted`	`{ id }`	An area is removed.
`task:created`, `task:updated`	the task or incident	Any change, including status, assignment and acknowledgement.
`task:deleted`	identifier and actor	Deleted, or moved out of your region.
`task:archived`, `task:unarchived`	identifier, the full task on unarchive	Archive state changes.
`task:unplaced`	the task	A task lost its location, so it leaves the map but stays in lists.

Presence#

Event	Direction	Payload
`presence:delta`	Server to client, at most once per second	`{ connected: [{ userId, username, connectedAt }], disconnected: [{ userId, username }] }`
`get_online_users`	Client to server	Asks for the current roster.
`users:online_list`	Server to client	The roster as `[{ userId, username }]`.
`presence:active`	Client to server	`{ active: true }` while the app is in the foreground. The server then skips redundant push notifications.

Guests receive neither the roster nor the deltas, and do not appear in them.

Live location#

Positions travel on the /loc namespace and are only sent for people who chose to share.

Event	Direction	Payload
`loc:enable`, `loc:disable`	Client to server	Starts or stops sharing for this connection. Guests cannot share.
`loc:update`	Client to server	`{ lat, lng, acc, speed, heading, ts }`. At most 10 a second per connection. Extra updates are dropped.
`viewport:update`	Client to server	Bounds of what the screen shows, so the server sends positions for that area only.
`loc:batch`	Server to client	A list of the latest position of everyone who moved in your area. One batch every 500 milliseconds per cell, and a batch is dropped rather than queued when your connection is slow, because the next one replaces it.
`loc:leave`	Server to client	`{ userId }` when someone stops sharing or disconnects.

Each entry of a batch holds userId, username, the coordinates and the accuracy, speed and heading when the device provided them. Stored positions expire about ten minutes after the last update; see Security and privacy.

Chat#

Event	Payload	Sent to
`chat:message`	`{ channelId, message }`	Everyone subscribed to the channel.
`chat:message:updated`	`{ channelId, message }`	The same room, after an edit.
`chat:message:deleted`	`{ channelId, id }`	The same room.
`chat:channel`	`{ channel }`	A person who was added to a new channel, such as the other side of a new direct message.
`chat:read`	`{ channelId, lastReadAt }`	The reader's own other devices, to clear their unread counter.
`chat:receipt`	`{ channelId, userId, lastReadAt }`	The channel, to show read ticks.
`chat:typing`	`{ channelId, userId, username, isTyping }`	The channel, except the sender. Sent as an occasional hint: a typing event may be dropped without notice.
`chat:channels:resync`	none	The client should reload its channel list, since membership changed.
`chat:error`	message	A subscribe request failed.

Clients send chat:subscribe and chat:unsubscribe with { channelIds }, and chat:typing with { channelId, isTyping }. Typing hints are limited per connection. Guests have no chat and are not subscribed.

Areas with geofencing#

When an area has geofencing switched on, the server watches shared positions against it. These events are sent to the person concerned and to administrators.

Event	Meaning
`zone:enter`, `zone:exit`	A person entered or left the area. The person sees a warning on entering a high or critical area.
`zone:occupancy`	The current head count of the area, with its capacity when it has one.
`zone:overflow`	The head count exceeded the capacity.

Other events#

Event	Who receives it	Meaning
`building:updated`, `building:deleted`	Every connection	A building annotation changed. Carries the building identifier. See 3D buildings and models.
`model:placements`	Every connection	3D drawing models were placed or moved.
`admin:account_request`	Administrators who can review it	A new access request is waiting. See Invitations, QR codes and access requests.
`ping` and `pong`	Client and server	A latency check: send `ping`, and the server answers `pong`.

Practical advice#

Connect, then join the regions and channels you need.
Load the current data through the REST API for the same area.
Apply events on top, keyed by identifier. An event for an item you already have replaces it.
On a reconnect, or after chat:channels:resync, load again. Events sent while you were away are not replayed.
Renew the token when auth:expiring arrives, so a wall display never drops off.