Skip to content
Ballastra
Open Ballastra

Aero developer docs

Realtime gateway and events

Connect your Aero to the realtime gateway and receive events from every Nexus it is installed in.

Connect to the gateway

Connect over Socket.IO with your token in the handshake auth. After connecting, register your own user room so events and command interactions reach you:

Node (socket.io-client)
import { io } from 'socket.io-client';

const socket = io('https://web.ballastra.app', {
  transports: ['websocket'],
  auth: { aeroToken: process.env.AERO_TOKEN },
});

socket.on('connect', async () => {
  // Learn who you are + where you're installed:
  const me = await api('/aero/rt/me');            // see Runtime API
  // Join your own room so events/interactions arrive:
  socket.emit('user:register', { userId: me.aero.user_id });
});

The server pins your identity to the authenticated Aero, so user:register can't impersonate anyone else.

Receiving events

Subscribe to events in the portal. Subscriptions are default-deny: you receive an event only if you subscribed to it, the install was granted the matching permission, and it is in scope. Events arrive as aero:event:

Event payload
socket.on('aero:event', (ev) => {
  // ev = {
  //   id,               // unique — dedupe on this (at-least-once delivery)
  //   type,             // e.g. 'member.joined'
  //   nexus_id,
  //   space_id,         // when the event is space-scoped
  //   installation_id,
  //   data,             // redacted payload, per event type
  // }
  if (ev.type === 'member.joined') {
    const member = ev.data.member;      // { id, name, username, ... }
  }
});

Event catalogue

All 37 events, grouped by what they are about. Each one still needs its matching permission, and the Events tab of your Aero in the portal shows which:

Event catalogue
members   member.joined  member.left  member.kicked  member.role_changed
messages  message.created  message.updated  message.deleted  message.pinned
          reaction.added  thread.replied
spaces    space.created  space.updated  space.deleted  space.moved
          category.created  category.updated  category.deleted
roles     role.created  role.updated  role.deleted  role.reordered
voice     voice.joined  voice.left  voice.state_changed
events    event.created  event.updated  event.cancelled  event.rsvp
nexus     nexus.updated  emoji.created  emoji.deleted  poll.updated
work      opportunity.created  opportunity.updated  opportunity.deleted
          application.created  application.status_changed

opportunity.* and application.* cover the work side of a community: roles and projects a Nexus posts, and the applications members send. voice.state_changed and the event.* family are privileged and need member-level grants.

Delivery is at-least-once and best-effort, so dedupe on ev.id and build your Aero to tolerate a missed event.