Rooms

A room is a virtual environment where users can interact by sending and receiving events. Rooms allow for various types of functionality, such as managing presence, subscribing to specific events, and publishing messages.

In a room, you can handle presence updates, subscribe or unsubscribe to events, and manage event history, among other actions. This powerful mechanism enables you to organize real-time interactions and event handling within a structured context, where each room serves as a dedicated space for its participants.

join()

Asynchronous function to join or create a "room" in which to send or recieve events.

await relayBox.join();

Returns Room object for optional chaining

class Room {
  constructor(roomId: string, socketManager: SocketManager, presencefactory: PresenceFactory, metricsFactory: MetricsFactory);
  readonly roomId: string;
  connect(): void;
  disconnect(): void;
  presence: Presence | null;
  metrics: Metrics | null;
  subscribe(eventOrHandler: string | SocketEventHandler, eventHandler?: SocketEventHandler): Promise<this>;
  unsubscribe(eventOrHandler?: string | SocketEventHandler, eventHandler?: SocketEventHandler): Promise<this>;
  publish<T>(event: string, userData: T): Promise<any>;
  leave(): Promise<void>;
}
ArgumentDescriptionType
1

Room Name: Specify the name of the room you want to join or create. If the room already exists, you will join it; if not, it will be created.

string

Example:

const room = relayBox.join('myRoomName');

room.subscribe()

Asynchronous function to subscribe to all or individual events that are broadcast to a room.

  • Requires subscribe permission
await room.subscribe();

Returns Room object for optional chaining

ArgumentDescriptionType
1

Event Name or Handler (optional): The first argument can be the name of the event you wish to subscribe to or an event handler function.

string / function
2

Event Handler (optional): The second argument can be an event handler function. If provided, it will be subscribed to the event.

function

Example:

// Subscribe to all room events
await room.subscribe((data: any) => {});

// Subscribe to events matching 'myEventName'
await room.subscribe('myEventName', (data: any) => {});

room.unsubscribe()

Asynchronous function to unsubscribe from all or individual event(s)

await room.subscribe();

Returns Room object

ArgumentDescriptionType

1
(optional)

Event Name or Handler (optional): The first argument can be the name of the event you wish to unsubscribe from or an event handler function. If you provide a specific event handler function, only that handler will be removed from the event.

string / function

2
(optional)

Event Handler (optional): The second argument can be an event handler function. If provided, it will be removed from the specified event.

function

Example:

// Unsubscribe from a specific event by name
await room.unsubscribe('message');

// Unsubscribe a specific event handler from an event
const handler = (data) => console.log(data);
await room.unsubscribe('message', handler);

// Unsubscribe from all events
await room.unsubscribe();

room.publish()

Asynchronous function to publish an event to a subscribers at room level.

  • Requires publsh permission
await room.publish();

Returns Room object for optional chaining

ArgumentDescriptionType
1

Event Name (required): The name of the event you wish to publish to subscribers of this event.

string
2

User data (required): The second argument must be the data you wish to attach to the event for processing by subscribers.

function

Example:

const data = {
  hello: 'room'
};

// publish 'myEventName' containing data to subscribers in room
await room.publish('myEventName', data);

room.presence.join()

Asynchronous function to join a presence set.

  • Requires "presence" permission
  • Requires connection clientId
await room.presence.join();

Returns void

ArgumentDescriptionType

1
(optional)

User Data (optional): Additional arbitrary data to be transmitted with join eventstring / object / array / blob / buffer

Example:

const userData = {
  name: 'foo'
};

// Send additional user data to "join" event subscribers
await room.presence.join(userData)

room.presence.leave()

Asynchronous function to leave a presence set.

  • Requires "presence" permission
  • Requires connection clientId
await room.presence.leave();

Returns void

ArgumentDescriptionType

1
(optional)

User Data (optional): Additional arbitrary data to be transmitted with leave event

string / object / array / blob / buffer

Example:

const userData = {
  name: 'foo'
};

// Send additional user data to "leave" event subscribers
await room.presence.leave(userData)

room.presence.update()

Asynchronous function to update arbitrary user data associated with a presence set connection.

  • Requires "presence" permission
  • Requires connection clientId
await room.presence.update();

Returns void

ArgumentDescriptionType

1
(optional)

User Data (optional): Updated arbitrary user data tp be published to presence update subscribers

string / object / array / blob / buffer

Example:

const userData = {
  latitude: 0.15652,
  longitude: 0.1435
};

// Send additional user data to "update" event subscribers
await room.presence.update(userData)

room.presence.subscribe()

Asynchronous function to subscribe to presence events for a room.

  • Requires "presence" permission
await room.presence.subscribe();

Returns void

ArgumentDescriptionType
1

Event Name or Handler (optional): The first argument can be the name of the presence event you wish to subscribe to or an event handler function.

string (join | leave | update) / function
2Event Handler (optional): The second argument can be an event handler functionfunction

Example:

// Subscribe to all room events
await room.presence.subscribe((data: any) => {});

// Subscribe to events matching 'join'
await room.presence.subscribe('join' | 'leave' | 'update', (data: any) => {});

room.presence.unsubscribe()

Asynchronous function to unsubscribe from all or individual presence event(s)

await room.presence.unsubscribe();

Returns void

ArgumentDescriptionType

1
(optional)

Event Name or Handler (optional): The first argument can be the name of the presence event you wish to unsubscribe from or an event handler function. If you provide a specific event handler function, only that handler will be removed from the event.

string (join | leave | update) / function

2
(optional)

Event Handler (optional): The second argument can be an event handler function. If provided, it will be removed from the specified event.

function

Example:

// Unsubscribe from a specific presence event by name
await room.presence.unsubscribe('join');

// Unsubscribe a specific presence event handler from an event
const handler = (data) => console.log(data);
await room.presence.unsubscribe('join', handler);

// Unsubscribe from all events
await room.presence.unsubscribe();

room.presence.get()

Asynchronous function to fetch all presence connections for a given room.

  • Requires "presence" permission
await room.presence.get<T>();

Returns array of PresenceEvent

interface PresenceEvent<T = any> {
  id: string;
  timestamp: string;
  data: T;
}

Example:

// fetch active presence connections for a room
const presenceUsers = await room.presence.get();

// Recomended usage...
await room.presence.subscribe((data: any) => {
  const presenceUsers = await room.presence.get();
});

room.presence.getCount()

Asynchronous function to fetch count of presence connections for a given room.

  • Requires "presence" permission
await room.presence.getCount();

Returns number

Example:

// fetch active presence connections for a room
const presenceCount = await room.presence.getCount();

// Recomended usage...
await room.presence.subscribe((data: any) => {
  const presenceCount = await room.presence.getCount();
});

room.metrics.subscribe()

Asynchronous function to subscribe to metrics events for a room.

  • Requires "metrics" permission
await room.metrics.subscribe();

Returns void

ArgumentDescriptionType
1Event Handler (optional): An event handler functionfunction

Example:

// Subscribe to all metrics events
await room.metrics.subscribe((data: any) => {});

room.metrics.unsubscribe()

Asynchronous function to unsubscribe from all metrics events

await room.metrics.unsubscribe();

Returns void

ArgumentDescriptionType

1
(optional)

Event Handler (optional): An event handler function. If you provide a specific event handler function, only that handler will be removed from the event.

function

Example:

// Unsubscribe a specific metrics event handler
const handler = (data) => console.log(data);
await room.metrics.unsubscribe(handler);

// Unsubscribe from all metrics events
await room.metrics.unsubscribe();

room.history.get()

  • Requires "history" permission

Asynchronous function to retrieve up to 24 hours of message history for a given room.

await room.history.get();

The get() methos takes a single argument, a history options object. The following options are available:

ArgumentDescriptionType

1
(optional)

History options: The first argument can be an object containing the room history query paramters. When no options are provided, the last 100 messages will be retrieved along with an iterator function to retrieve the next batch of messages.

object

Returns list of items along with a batch iterator function (if applicable).

{
  items: any[];
  next: () => Promise<HistoryResponse>;
}

Example:

The example below will retrieve 24 hours of message history for a room in batches of 100 messages beginning with the most recent message.

const room = await relaybox.join('myRoom');

let history = await room.history.get({
  items: number,
  start: number,
  end: number,
  seconds: number,
  order: 'asc' | 'desc', // default: 'desc'
  limit: number // default: 100
});

To apply a filter to the retrieved messages, you can pass a filter object to to the get() method. The following options are available:

KeyDescriptionType
items

Number of items to retrieve. Requests containing over 100 messages will be returned in batches of 100 messages along with an iterator function.

number
startMilliseconds since the Unix epoch. Only messages after this time will be returned.number
endMilliseconds since the Unix epoch. Only messages before this time will be returned.number
secondsNumber of seconds of message history to retrieve.number
order

Specify the order of the messages. The default order is 'desc', which means the most recent messages will be returned first. Set the order to 'asc' to return the oldest messages first. If 'asc' passed, 'start' or 'seconds' must also be specified.

string


'asc' | 'desc'

limit

Number of items to include in each batch. The default limit is 100. This parameter is useful for lazy loading message history.

number
1 - 100

room.history.next()

  • Requires "history" permission

Asynchronous iterator function to retrieve the next batch of message history for a given room.

// const history = await room.history.get();
await history.next();

Returns list of items along with a batch iterator function (if applicable).

{
  items: any[];
  next: () => Promise<HistoryResponse>;
}

Example:

The example below will retrieve 24 hours of message history for a room in batches of 100 messages beginning with the most recent message.

const room = await relaybox.join('myRoom');

let history = await room.history.get();

while (history.next) {
  history = await history.next();
  console.log(history.items);
}

    On this page

      © 2024 Relaybox Ltd. All rights reserved.
      • Slack logo
      • Discord logo