Channels Overview

Channels are how you organize and control access to real-time data in Hotsock. Clients subscribe to channels to receive messages, and your backend publishes messages to channels to reach those subscribers.

Every channel subscription must be authorized by a claim in the JWT token. This is how you control which clients can access which data — permissions are baked into the token at signing time, not configured globally.

There is no limit to the number of channels your application can use, and channels do not need to be declared ahead of time. When a message is published to a channel, every currently subscribed client receives a copy.

Naming

Channel names can be any string between 1 and 256 characters. The following characters are not allowed in channel names:

• Asterisks (*)
• Number signs (#)
• Commas (,)
• Spaces and newline characters

In JWT claims, channel keys support wildcards (*) and regex patterns (#regex:) for flexible permission matching across multiple channels.

Events

Every message published to a channel must include an event name. Events let you group different types of messages on the same channel so your client code can handle them separately.

For example, a game.123 channel might have move and chat events:

{
  "channel": "game.123",
  "event": "move",
  "id": "01H2BSNHFJXKF2XDFD8KMM36FF",
  "data": { "player": "Jack", "from": "B1", "to": "C3" }
}

{
  "channel": "game.123",
  "event": "chat",
  "id": "01H2C4Z3PFFJR6RG5D6A12HM92",
  "data": "Jack: Good game!"
}

Both arrive on the same channel, but your application can route them to different handlers based on the event name. The message id is generated by Hotsock.

When should you use a different channel instead of a different event?

All events published to a channel are delivered to every subscriber, regardless of whether the client cares about that event. If you find yourself sending many events that most subscribers ignore, consider splitting those into a separate channel.

Use channels to filter what data a client receives. Use events to categorize different message types within the same context.

Channel Types

Type	Use case	Member awareness
Standard	Most situations — delivering real-time updates to clients	No
Presence	Chat rooms, collaboration, multiplayer — clients need to know who else is connected	Yes

Both channel types support the same messaging features (publishing, client messages, storage, message history, etc.). Presence channels add member tracking on top.