Channel Subscriptions

Subscribe and unsubscribe from channels via WebSocket

Subscription Protocol

To receive events on a channel, clients must first subscribe to it by sending a pusher:subscribe event.

Subscribe to Channel

Send a JSON message over the WebSocket:

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "my-channel"
  }
}

event · string · required

Must be pusher:subscribe

data · object · required

Subscription details

data.channel · string · required

Name of the channel to subscribe to (max 200 characters)

Channel Types

Sockudo supports multiple channel types based on the channel name prefix:

Public Channels

No prefix required. No authentication needed.

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "news-updates"
  }
}

Private Channels

Prefix: private-

Requires authentication signature:

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "private-user-123",
    "auth": "app-key:signature"
  }
}

data.auth · string · required

Authentication signature in format {appKey}:{hmacSignature}

Presence Channels

Prefix: presence-

Requires authentication signature and channel data with user information:

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "presence-chat-room",
    "auth": "app-key:signature",
    "channel_data": "{\"user_id\":\"123\",\"user_info\":{\"name\":\"Alice\"}}"
  }
}

data.channel_data · string · required

JSON-encoded string containing user ID and optional user info

Private Encrypted Channels

Prefix: private-encrypted-

Similar to private channels but with end-to-end encryption:

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "private-encrypted-secrets",
    "auth": "app-key:signature"
  }
}

Authentication for Private Channels

Private and presence channels require HMAC-SHA256 authentication.

Signature Generation

The signature is generated by signing a string with your app secret:

For private channels:

string_to_sign = socket_id + ":" + channel_name
signature = HMAC-SHA256(app_secret, string_to_sign)
auth = app_key + ":" + signature

For presence channels:

string_to_sign = socket_id + ":" + channel_name + ":" + channel_data
signature = HMAC-SHA256(app_secret, string_to_sign)
auth = app_key + ":" + signature

Example: Node.js Signature Generation

const crypto = require('crypto');

function generateSignature(socketId, channelName, appSecret, channelData = null) {
  let stringToSign = `${socketId}:${channelName}`;
  
  if (channelData) {
    // For presence channels
    stringToSign += `:${channelData}`;
  }
  
  const hmac = crypto.createHmac('sha256', appSecret);
  hmac.update(stringToSign);
  return hmac.digest('hex');
}

// For private channel
const signature = generateSignature(
  '123456.789012',
  'private-user-123',
  'your-app-secret'
);
const auth = `your-app-key:${signature}`;

// For presence channel
const channelData = JSON.stringify({
  user_id: '123',
  user_info: { name: 'Alice' }
});
const presenceSignature = generateSignature(
  '123456.789012',
  'presence-chat',
  'your-app-secret',
  channelData
);
const presenceAuth = `your-app-key:${presenceSignature}`;

Subscription Success

When subscription succeeds, the server sends a pusher_internal:subscription_succeeded event:

Public/Private channels:

{
  "event": "pusher_internal:subscription_succeeded",
  "channel": "private-user-123",
  "data": "{}"
}

Presence channels:

{
  "event": "pusher_internal:subscription_succeeded",
  "channel": "presence-chat-room",
  "data": "{\"presence\":{\"ids\":[\"123\",\"456\"],\"hash\":{\"123\":{\"name\":\"Alice\"},\"456\":{\"name\":\"Bob\"}},\"count\":2}}"
}

data.presence.ids · string[]

Array of user IDs currently in the channel

data.presence.hash · object

Map of user IDs to their user_info objects

data.presence.count · integer

Total number of users in the channel

Unsubscribe from Channel

To stop receiving events from a channel:

{
  "event": "pusher:unsubscribe",
  "data": {
    "channel": "my-channel"
  }
}

event · string · required

Must be pusher:unsubscribe

data.channel · string · required

Name of the channel to unsubscribe from

No response is sent for unsubscribe events.

Subscription Errors

If subscription fails, the server sends a pusher:error event:

{
  "event": "pusher:error",
  "data": {
    "code": 4009,
    "message": "Channel requires authentication"
  },
  "channel": "private-user-123"
}

Channel Naming Rules

• Maximum length: 200 characters
• Allowed characters: a-z, A-Z, 0-9, _, -, =, @, ,, ., ;
• Channel names are case-sensitive
• Regex pattern: ^[a-zA-Z0-9_\-=@,.;]+$

Example: Subscribe with pusher-js

import Pusher from 'pusher-js';

const pusher = new Pusher('your-app-key', {
  wsHost: 'localhost',
  wsPort: 6001,
  forceTLS: false,
  enabledTransports: ['ws'],
  cluster: '',
  
  // For private/presence channels, provide auth endpoint
  authEndpoint: '/pusher/auth'
});

// Subscribe to public channel
const publicChannel = pusher.subscribe('news-updates');

// Subscribe to private channel
const privateChannel = pusher.subscribe('private-user-123');

// Subscribe to presence channel
const presenceChannel = pusher.subscribe('presence-chat-room');

presenceChannel.bind('pusher:subscription_succeeded', (members) => {
  console.log('Members:', members.count);
  members.each((member) => {
    console.log(member.id, member.info);
  });
});

// Unsubscribe
pusher.unsubscribe('news-updates');

Advanced: Tag Filtering

Sockudo supports server-side filtering by tags (if enabled):

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "sports-updates",
    "filter": {
      "eq": ["sport", "soccer"]
    }
  }
}

See Tag Filtering for details.

Advanced: Delta Compression

Clients can negotiate delta compression per-channel:

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "ticker:BTC",
    "delta": {
      "enabled": true,
      "algorithm": "fossil"
    }
  }
}

See Delta Compression for details.