Skip to content

Server-side subscriptions


This is a documentation for Centrifugo v2. The latest Centrifugo version is v3. Go to the for v3 docs.

Starting from v2.4.0 Centrifugo supports server-side subscriptions.


Before v2.4.0 only client could initiate subscription to channel calling Subscribe method. While this is actually the most flexible approach as client side usually knows well which channels it needs to consume in concrete moment – in some situations all you need is to subscribe your connections to several channels on server side at the moment of connection establishement. So client effectively starts receiving publications from those channels without explicitly call Subscribe method.

You can set a list of channels for connection in two ways at moment:

  • over connection JWT using channels claim, which is an array of strings
  • over connect proxy returning channels field in result (also an array of strings)

On client side you need to listen for publications from server-side channels using top-level client event handler. At this moment server-side subscriptions only supported by centrifuge-js client. With it all you need to do on client side is sth like this:

var centrifuge = new Centrifuge(address);

centrifuge.on('publish', function(ctx) {
    const channel =;
    const payload = JSON.stringify(;
    console.log('Publication from server-side channel', channel, payload);


I.e. listen for publications without any usage of subscription objects. You can look at channel publication relates to using field in callback context as shown in example.

In future this mechanism will be supported by all our clients. Hopefully with community help this will happen very soon.

Server-side subscription limitations

Such subscriptions do not fit well for dynamic subscriptions – as Centrifugo does not have subscribe server API at moment. Also the same rules about best practices of working with channels and client-side subscriptions equally applicable to server-side subscription.

Automatic personal channel subscription

v2.4.0 also introduced some sugar on top of server-side subscriptions. It's possible to automatically subscribe user to personal server-side channel.

To enable this you need to enable user_subscribe_to_personal boolean option (by default false). As soon as you do this every connection with non-empty user ID will be automatically subscribed to personal user-limited channel. Anonymous users with empty user ID won't be subscribed to any channel.

For example, if you set this option and user with ID 87334 connects to Centrifugo it will be automatically subscribed to channel #87334 and you can process personal publications on client side in the same way as shown above.

As you can see by default generated personal channel name belongs to default namespace (i.e. no explicit namespace used). To set custom namespace name use user_personal_channel_namespace option (string, default "") – i.e. the name of namespace from configured configuration namespaces array. In this case if you set user_personal_channel_namespace to personal for example – then the automatically generated personal channel will be personal:#87334 – user will be automatically subscribed to it on connect and you can use this channel name to publish personal notifications to online user.

Maintain single user connection

Available since v2.8.0

Usage of personal channel subscription also opens a road to enable one more feature: maintaining only a single connection for each user globally around all Centrifugo nodes.

user_personal_single_connection boolean option (default false) turns on a mode in which Centrifugo will try to maintain only a single connection for each user in the same moment. As soon as the user establishes a connection other connections from the same user will be closed with connection limit reason (client won't try to automatically reconnect).

This feature works with a help of presence information inside a personal channel. So presence should be turned on in a personal channel.

Example config:

  "v3_use_offset": true,
  "user_subscribe_to_personal": true,
  "user_personal_single_connection": true,
  "user_personal_channel_namespace": "personal",
  "namespaces": [
      "name": "personal",
      "presence": true


Centrifugo can't guarantee that other user connections will be closed – since Disconnect messages distributed around Centrifugo nodes with at most once guarantee. So don't add critical business logic based on this feature to your application. Though this should work just fine most of the time if the connection between Centrifugo node and PUB/SUB broker is OK.

Mark namespace as server-side

v2.4.0 also introduced a new channel namespace boolean option called server_side (default false). When on then all client-side subscription requests to channels in namespace will be rejected with PermissionDenied error.