Real-Time Subscriptions

How to use GraphQL subscriptions with the Timerise API to receive real-time updates on bookings and notifications.

Updated June 19, 2026

The Timerise API offers robust features for real-time data interaction, especially useful for applications requiring instant updates on bookings and notifications. This guide provides an overview of how to use GraphQL subscriptions to track changes in real-time, ensuring your application stays responsive and up-to-date.

How It Works

Subscriptions are transported over graphql-ws WebSockets. On the server, there is no third-party real-time provider and no central PubSub broker - each GraphQL subscription is an inline async generator that wraps a per-document Firestore onSnapshot listener. When the underlying document changes, Firestore pushes the update straight through the generator to your subscription, so you receive changes the moment they are written, with no intermediate fan-out layer.

Best Practices

Handling Connection Stability: Ensure stable WebSocket connections for subscriptions. Implement reconnection strategies in case of network interruptions.
Optimizing Data Load: Subscribe only to necessary fields to reduce network load and improve performance.
Error Handling: Implement robust error handling to catch and manage subscription errors or interruptions gracefully.
Security Considerations: Secure your WebSocket connections and validate authentication tokens if required.
Efficient Resource Use: Unsubscribe from updates when not needed to conserve server and client resources.
Testing: Regularly test subscriptions to ensure they respond correctly to real-time changes and handle edge cases.

Booking Updates Subscription

GraphQL Subscription Query:

subscription {
  booking(bookingId: "YOUR_BOOKING_ID") {
    bookingId
    createdAt
    dateTimeFrom
    dateTimeTo
    duration
    # Include other fields as needed
  }
}

Node.js with Apollo Client:

import { ApolloClient, InMemoryCache, gql, HttpLink, split } from "@apollo/client";
import { getMainDefinition } from "@apollo/client/utilities";
import { GraphQLWsLink } from "@apollo/client/link/subscriptions";
import { createClient } from "graphql-ws";

// graphql-ws link for subscriptions
const wsLink = new GraphQLWsLink(
  createClient({
    url: "wss://api.timerise.io/v1",
  }),
);

// HTTP link for queries and mutations
const httpLink = new HttpLink({
  uri: "https://api.timerise.io/v1",
});

// Split links for appropriate operations
const link = split(
  ({ query }) => {
    const definition = getMainDefinition(query);
    return definition.kind === "OperationDefinition" && definition.operation === "subscription";
  },
  wsLink,
  httpLink,
);

// Apollo Client setup
const client = new ApolloClient({
  link,
  cache: new InMemoryCache(),
});

// Booking Subscription GraphQL Query
const BOOKING_SUBSCRIPTION = gql`
  subscription Booking($bookingId: ID!) {
    booking(bookingId: $bookingId) {
      bookingId
      createdAt
      dateTimeFrom
      dateTimeTo
      duration
      # Include other fields as needed
    }
  }
`;

// Executing the subscription
client
  .subscribe({
    query: BOOKING_SUBSCRIPTION,
    variables: { bookingId: "YOUR_BOOKING_ID" },
  })
  .subscribe({
    next(data) {
      console.log(data);
    },
    error(err) {
      console.error("Error:", err);
    },
  });

Notifications Updates Subscription

GraphQL Subscription Query:

subscription {
  notifications(projectId: "YOUR_PROJECT_ID", roles: ["ROLE1", "ROLE2"]) {
    notificationId
    title
    body
    # Include other fields as needed
  }
}

Node.js with Apollo Client:

Similar to the booking updates subscription - set up the Apollo Client with the graphql-ws and HTTP links as shown above, then replace BOOKING_SUBSCRIPTION with the notifications query.

Summary

This guide demonstrates how to subscribe to real-time booking and notification updates using the Timerise API. Replace YOUR_BOOKING_ID and YOUR_PROJECT_ID with your actual booking ID and project ID.

The Apollo Client in Node.js, with the graphql-ws transport, is used for managing GraphQL WebSocket subscriptions, as CURL or Axios do not support this functionality.