Realtime subscriptions over WebSocket

How the widget receives live updates through GraphQL subscriptions, and the list of client_* subscription fields.

When you publish, edit or archive content in the admin app, widgets that are already open can update without a reload. This works through GraphQL subscriptions on wss://api.hubbo.io/graphql.

Connecting

The widget uses the graphql-ws client. A minimal subscription looks like this:

import { createClient } from 'graphql-ws';

const client = createClient({ url: 'wss://api.hubbo.io/graphql' });

const unsubscribe = client.subscribe(
  { query: 'subscription { client_notificationUpdated { notification { id title state } } }' },
  {
    next: (result) => console.log(result.data),
    error: (error) => console.error(error),
    complete: () => console.log('closed'),
  },
);

The project key is read from the hubbo_api_key cookie (which the browser sends with the WebSocket handshake) or from the Hubbo-Project-Key header. Subscription events are filtered to the account that owns the key.

Available client subscriptions

Subscription	Fires when
client_accountUpdated	Account name, origin or appearance changes. Delivered to Hubbo-hosted origins such as admin previews.
client_accountCreated / client_accountDeleted	Account lifecycle. Same delivery rule as above.
client_notificationCreated	A notification is created.
client_notificationUpdated	A notification is edited, published or archived.
client_notificationDeleted	A notification is deleted.
client_npsSettingsUpdated	NPS settings are saved.
client_surveyUpdated / client_surveyDeleted	A survey is saved or deleted.
client_roadMapUpdated / client_roadMapDeleted	A roadmap is saved or deleted.
client_messageCreated(chatId, guestToken)	A new chat message arrives in the given chat. Guests must pass a valid guestToken from createChat.

Behavior to expect

Payloads are the same objects as the matching queries. Fields not included in the subscription payload keep their last known value in the widget (for example, the account usageAllowed flag).
Page views are counted when a browser session first loads Hubbo, not per subscription message.
The widget subscribes only after usageAllowed is true. When your plan limit is hit, no widgets (and no subscriptions) start.

Keep connections modest

Each open browser tab with the widget holds a WebSocket. Do not open extra subscriptions from your own code for the sake of mirroring content, since your visitors’ browsers do the connecting.