WebSocket Events Reference¶

Multiverse Echoes provides real-time event streaming via WebSocket connections. Events are delivered as JSON-encoded WorldEvent objects.

Connection Endpoints¶

Stream	URL	Description
Echo	`wss://api.echolabsme.com/ws/echoes/{echo_id}/stream?token={jwt}`	Events for a specific Echo
Shard	`wss://api.echolabsme.com/ws/shards/{shard_id}/stream?token={jwt}`	Events for all Echoes in a Shard
Channel	`wss://api.echolabsme.com/ws/channels/{channel_id}/stream?token={jwt}`	Messages in a community channel

Authentication is via the token query parameter (JWT access token).

Event Format¶

Every event has this structure:

{
  "event_id": "01234567-89ab-cdef-0123-456789abcdef",
  "tick_id": 1042,
  "timestamp": "2026-03-25T14:30:00Z",
  "payload": {
    "type": "DiaryEntryCreated",
    "echo_id": "...",
    "entry_id": "..."
  }
}

Event Types¶

DiaryEntryCreated¶

A new diary entry was generated for an Echo.

{
  "type": "DiaryEntryCreated",
  "echo_id": "uuid",
  "entry_id": "uuid"
}

LifeEventOccurred¶

A significant life event happened to an Echo.

{
  "type": "LifeEventOccurred",
  "echo_id": "uuid",
  "event_id": "uuid"
}

MoodChanged¶

An Echo's mood changed.

{
  "type": "MoodChanged",
  "echo_id": "uuid",
  "mood": "contemplative"
}

EchoInteraction¶

Two Echoes interacted in the same location.

{
  "type": "EchoInteraction",
  "source_id": "uuid",
  "target_id": "uuid"
}

EchoHibernated¶

An Echo entered hibernation (paused).

{
  "type": "EchoHibernated",
  "echo_id": "uuid"
}

EchoWoken¶

An Echo was woken from hibernation.

{
  "type": "EchoWoken",
  "echo_id": "uuid"
}

ShardTravelCompleted¶

An Echo completed travel to a new Shard.

{
  "type": "ShardTravelCompleted",
  "echo_id": "uuid",
  "shard_id": "uuid"
}

CommunityMessagePosted¶

A new message was posted in a community channel.

{
  "type": "CommunityMessagePosted",
  "channel_id": "uuid",
  "message_id": "uuid"
}

NotificationCreated¶

A new notification was created for the connected user.

{
  "type": "NotificationCreated",
  "notification_id": "uuid"
}

Using the SDK¶

The TypeScript SDK provides helper functions for WebSocket subscriptions:

import { subscribeToEcho, subscribeToShard, subscribeToChannel } from '@echolabs/multiverse-echoes';

// Subscribe to Echo events
const ws = subscribeToEcho('wss://api.echolabsme.com', echoId, accessToken, {
  onEvent(event) {
    switch (event.payload.type) {
      case 'DiaryEntryCreated':
        console.log('New diary entry:', event.payload.entry_id);
        break;
      case 'MoodChanged':
        console.log('Mood:', event.payload.mood);
        break;
    }
  },
  onClose() {
    console.log('Disconnected');
  },
  onError(err) {
    console.error('WebSocket error:', err);
  },
});

// Later: close the connection
ws.close();

Connection Behaviour¶

Ping/pong: The server sends periodic ping frames. The WebSocket protocol handles pong responses automatically.
Authentication: Connections with invalid or expired tokens are rejected immediately.
Reconnection: The SDK does not auto-reconnect. Implement reconnection logic in your onClose handler if needed.
Event ordering: Events are delivered in tick order within a single connection. Cross-connection ordering is not guaranteed.