Live updates
How the web app and the companion stay current without asking again and again, and the stream a program can read the same way.
Modbot's screens change as things happen. When somebody joins an instance, a moderator bans someone, a review opens or an alert is raised, the Live page, the audit log, the member lists, the open popup and the badges redraw within a moment, without the page being reloaded and without the browser asking the server on a timer. The companion's overlay follows the instance the same way.
Behind that is one live stream: every event Modbot records, sent to the web app and the companion as it is written. This page describes what the stream carries and how it is read, for anyone who wants to read it from a program of their own, or who wants to know what their browser is doing.
What the stream carries
Every event is one of Modbot's events, with the same id, so what the
stream sends and what the audit log shows are the same records. A few
kinds are named, because a screen does something particular with them; everything else is a
fact whose type says what it is.
kind | From | What it means |
|---|---|---|
person_joined | vrchat.instance.join | Somebody walked into an instance. |
flagged_join | the same, by somebody one of the flag rules matches | Sent instead of person_joined, with a reason. |
person_left | vrchat.instance.leave | Somebody left. |
person_here | vrchat.instance.presence | Somebody was already there when a moderator started watching. |
watch_stopped | vrchat.instance.log-stopped | A moderator's client stopped seeing the instance. |
instance_opened, instance_closed, instance_changed | vrchat.group.instance.* | A group instance opened, closed or changed. |
voice_changed | discord.voice.join, .move, .leave | Somebody joined, moved between or left Discord voice channels. |
alert | modbot.insight.alert | Unusual activity, from the alert watchers. |
review_opened, review_closed | modbot.review.* | A review opened or closed. |
fact | anything else | A ban, a join, a role change, a sign-in, a settings change, and so on. |
Until 2026-09-17 the three group instance kinds were room_opened, room_closed and
room_changed. A client written against those names needs the new ones.
Until 2026-09-27 Discord voice changes came as fact, with the same type.
{
"id": "81234",
"cursor": "81234",
"kind": "flagged_join",
"type": "vrchat.instance.join",
"typeRaw": null,
"category": "moderation",
"label": "Joined an instance",
"source": "Client",
"at": "2026-09-16T20:14:07+00:00",
"occurredBefore": null,
"observedAt": "2026-09-16T20:14:09.2+00:00",
"subject": { "platform": "VRChat", "id": "usr_…", "kind": "Person" },
"actor": null,
"instanceId": "39911",
"worldId": "wrld_…",
"worldName": "The Black Cat",
"person": {
"id": "usr_…",
"displayName": "…",
"trustRank": "KnownUser",
"standing": "Flagged",
"priorActions": 2,
"flags": ["2 kicks or bans", "Nuisance"]
},
"flagged": true,
"reason": "2 kicks or bans · Nuisance",
"byThisDevice": false,
"data": { }
}| Field | |
|---|---|
id, cursor | The event's id, the same one the audit log uses, as text. Store the last cursor you handled and send it back to carry on from there; treat it as text with no meaning of its own. |
kind, type | The table above, and the event's own type. |
category, label, source | Which log it belongs to, a short English label, and where Modbot learned of it, as on the event. |
at, occurredBefore, observedAt | When it happened (a window when it is not exact), and when Modbot learned of it. |
subject, actor | Who or what it happened to, and who did it, or null. |
instanceId, worldId | Where it happened, for events inside a VRChat instance. |
person | For the person kinds: the person as the Live page describes them, with their VRChat trust rank when Modbot knows it (trustRank is null until then). |
flagged, reason | Set on a flagged_join. |
byThisDevice | For the companion: whether this client reported the event itself. Always false in a browser. |
data | Everything else Modbot recorded about the event. Left out for the companion. |
Who receives what
The same rules as the screens that show these things, decided event by event from the permissions the person holds at that moment:
- Presence, instances and Discord voice need See live instances.
- Alerts need See analytics.
- Reviews need Review tickets.
- Every other event follows the audit log's rules: moderation events need See the audit log, operational events need See the operational log, and presence events additionally need See live instances (as on the event WebSocket).
Somebody with none of these cannot open the stream (403). If a permission is taken away while
connected, the events it allowed stop from then on; if none are left, the connection closes with
4003.
The companion is sent presence in the one instance it is standing in. When it connects with
moderation=true and its owner holds See the audit log, it is also sent the audit log's facts
about that instance and about the people seen in it since the moderator arrived, by the owner's
audit-log visibility, each with the audit log's sentence and its origin (VRChat, Discord or
Modbot). Nothing else reaches it, and an owner who loses that permission stops receiving them at
the next check. It names that instance by its number (instanceId) and its world (worldId),
because a number is only unique inside one world. A companion that names no world is matched by the number alone.
Two ways to read it
The WebSocket
wss://modbot.example.com/api/live/ws?ticket=…&after=…A browser cannot set headers on a WebSocket and a session cookie on its own is not accepted
(for the same reason as the event WebSocket), so the web app
first asks POST /api/live/tickets for a one-use ticket, then connects with it. A program can
connect with an API key in the Authorization header instead.
after is the cursor to carry on from. Without it, the stream starts from now.
The conversation is the event WebSocket's, with one difference: there is nothing to subscribe to, because what you are sent is decided by who you are.
| The server sends | |
|---|---|
{ "kind": "hello", "version": 1, "heartbeatSeconds": 30, "cursor": "81230" } | On connect. cursor is where reading starts. |
{ "kind": "event", "event": { … } } | One event, as above. |
{ "kind": "heartbeat", "cursor": "81290" } | About every thirty seconds. Store the cursor. |
{ "kind": "notice", "code": "history_trimmed", "message": "…" } | Your cursor was older than anything still kept. |
{ "kind": "error", "message": "…" } | A message you sent could not be used. |
{ "kind": "pong" } | The answer to { "op": "ping" }. |
{ "kind": "changed", "what": "heads_ups" } | Companion only: the heads-ups where it stands changed. It carries no news; read the roster again. Ignore a what you do not know. |
You may send { "op": "subscribe", "cursor": "…" } to move the reading position. The close codes
are the event WebSocket's; an unexpected failure on the
server closes with 1011, and reconnecting with your cursor is the right answer to it.
Long polling, the backup
GET /api/live/poll?after=81230&wait=30&limit=100With the web app's session, or an API key in the Authorization header. It answers at once when
there are events after after, and otherwise waits up to wait seconds (default 30, at most 60)
for one:
{ "events": [ … ], "cursor": "81234", "more": false, "notice": null }Send cursor back as after. more means there is more already: ask again straight away. The
same events, in the same order, chosen by the same rules as the socket.
A waiting poll and an open socket from the same person share the same five connection places; a
sixth is refused with 429 and a Retry-After.
How the web app and the companion choose
Both follow one rule:
- The socket first. Every event and heartbeat carries a cursor, and a reconnect by either route asks for events after it, so a dropped connection costs a moment and never an event.
- Back off between attempts, doubling from one second up to thirty.
- Three failed connections or drops within two minutes means polling for five minutes. A quiet poll is the ordinary answer and changes nothing; a failed one backs off like a failed connection.
- Then the socket again, from where polling got to. A proxy or captive portal that will not carry WebSockets therefore slows the updates a little and never stops them, and one that starts carrying them later is noticed within minutes.
- A refusal that trying again cannot fix stops the stream:
4003, a 401 or 403, a rejected companion token. Reload the page, or pair the companion again.
The state is shown in one word: Live, Polling, Connecting, Off or Stopped -- at the top of the Live page, and on the companion's Servers page next to each server.
The web app keeps one connection per open tab, however many screens are reading it, and only while the tab is on screen: a tab in the background holds nothing open and comes back with its cursor when you look at it again.
What updates live in the web app
| Screen | Redraws when |
|---|---|
| Live | Somebody joins, leaves or was already there; an instance opens, closes or changes. (It also reads again every thirty seconds, because head counts come from Modbot's own syncs rather than from events.) |
| Audit log | Any event that passes the filters in the bar. At the top of the list, the row appears; scrolled down, a N new button appears in the bar and inserts them when pressed. |
| Members, Discord members | A join, a leave, a ban, a kick, a role change, a profile change (trust rank included), an account link. The counts come from the same read. |
| Bans | A ban or an unban. |
| Reviews, and the count beside Reviews in the sidebar | A review opens or closes. |
| Flags, and the count beside Flags in the sidebar | A rule raises or settles a flag. |
| Case files | A report or its evidence changes. |
| Repeat offenders | Somebody is banned, kicked or removed. |
| Calendar | An event is planned, changed, opened or finished, or VRChat's calendar changes. |
| Alerts (on the VRChat analytics page and Health) | An alert is raised. |
| The open person, world or instance popup | Any event about that person (as its subject or as the one who acted), in that world, or in that instance -- every tab, including Overview, Activity and Profile changes. |
Each screen reads its own data again rather than applying the event by hand: the server has already written the change, so reading it back is the one way the screen and the server cannot disagree. A burst of events is one read, not one each.
Screens that show numbers the syncs produce rather than events -- Health, the status rows, the analytics pages -- keep their own timing.