Skip to main content

Messaging – Fetch Past Messages

Overview​

Fetching past messages allows a NodeJS application to retrieve historical messages that were previously published to a topic. This API is used when real-time delivery alone is not sufficient, such as during application startup, recovery after downtime, or when running analytics over earlier events.

Unlike subscriptions, fetching message history does not create a live stream. It is a point-in-time query against messages that are still retained by RelayX. The result is a finite list of messages that match the query criteria at the time the request is executed.

This API interacts with RelayX’s message storage layer. It is constrained by message retention limits, topic validity rules, and connection state. It is designed to complement subscriptions, not replace them.

How This Works​

When history() is called, the NodeJS SDK sends a request to the RelayX backend to retrieve messages that match the provided topic and time range.

RelayX immediately evaluates the request against:

  • The topic or wildcard pattern
  • The specified start and end timestamps
  • The current retention window of the account

If the client is connected, RelayX returns all matching messages that still exist. If the client is disconnected or reconnecting, the SDK returns an empty array. No retry or buffering is performed for history requests.

A history request is considered successful if it returns an array. An empty array does not necessarily indicate an error. It may mean there were no messages, the messages have expired, or the client was not connected at the time of the request.

API Usage​

Method​

history(topic, startTime, endTime)

Parameters​

  • topic (string, required)
    A valid topic name or wildcard pattern. Topic rules and restrictions apply.

  • startTime (Date, required)
    The beginning of the time range for fetching messages.

  • endTime (Date, optional)

    • The end of the time range for fetching messages. This must be later than startTime.
    • If not specified, history from startTime to now will be returned

Return Value​

  • Returns an array of message objects
  • Returns an empty array if:
    • No messages match
    • Messages have expired
    • The client is disconnected or reconnecting

Code Example​

import { Realtime } from "relayx-js";

const client = new Realtime({
  api_key: process.env.RELAYX_API_KEY,
  secret: process.env.RELAYX_API_SECRET,
});

await client.connect();

var now = new Date();

// Set start date to 4 days ago
var past = start.setDate(now.getDate() - 4)
var startDate = new Date(past)

// Set end date to 2 days ago 
var past = end.setDate(now.getDate() - 2)
var endDate = new Date(past)

var history = await client.history("chat.room1", startDate, endDate)

// OR

// This will return messages from $startDate to now()
var history = await client.history("chat.room1", startDate)

Structure of $history,

[
    {
        "id": "<MESSAGE UUID>",
        "topic": "<TOPIC MATCHING TOPIC / WILDCARD TOPIC>",
        "message": "<Actual message as string, number or json>",
        "timestamp": "<Timestamp UTC>"
    }
]

Failure & Edge Cases​

Disconnected Client​

If history() is called while the client is disconnected or reconnecting, the SDK returns an empty array. No exception is thrown.

Invalid Topics​

An error is thrown if:

  • The topic name is invalid
  • A reserved system topic is used

Invalid Time Range​

An error is thrown if:

  • endTime is earlier than startTime

Expired Messages​

Messages that exceed their TTL are permanently deleted. Fetching outside the retention window always returns an empty array.

Common Mistakes​

  1. Assuming history waits for reconnection
    History requests do not retry. Call history only after a successful connection.

  2. Treating empty results as an error
    An empty array is a valid response in many scenarios.

  3. Using history instead of subscriptions
    History does not stream new messages. Use subscriptions for live data.

  4. Requesting data outside retention limits
    Messages older than the plan’s retention window cannot be fetched.

Notes & Limitations​

  • History requests are bounded by message retention and plan limits.
  • Large time ranges may return large arrays and impact memory usage.
  • History does not participate in reconnect replay logic.
Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️