Channels
A channel is a named stream of events. Clients subscribe to it, your server publishes to it, and every subscriber receives each event.
Channel types
The prefix of the name decides the type.
| Name starts with | Type | Who can subscribe |
|---|---|---|
nothing, e.g. news | Public | Anyone who has your app key |
private- | Private | Clients your server authorizes |
presence- | Presence | Clients your server authorizes; also tells everyone who is online |
private-encrypted- | Private, end-to-end encrypted | Like private, and event data is encrypted so the service cannot read it |
cache-, private-cache-, presence-cache- | Cache | Like the type after the prefix; new subscribers immediately get the last event |
Private, presence and encrypted channels need an authorization endpoint. Encrypted and cache channels are supported by the underlying server but are not covered by our own tests.
Subscribe and listen
js
const channel = pusher.subscribe("my-channel");
channel.bind("my-event", (data) => {
console.log("received", data);
});Bind to the special event pusher:subscription_succeeded to know when the subscription is active, and pusher:subscription_error if it was refused (for private channels, usually a failed authorization).
Publish
From your server, with any Pusher library:
js
await pusher.trigger("my-channel", "my-event", { hello: "world" });You can publish to up to 100 channels in one request, and send up to 10 events in one batch request. A publish to several channels counts once per channel against your publish rate limit. See HTTP API.
Presence channels
A presence channel keeps a list of who is subscribed. When a client joins it receives everyone currently there, and then gets an event whenever someone arrives or leaves:
js
const channel = pusher.subscribe("presence-room-1");
channel.bind("pusher:subscription_succeeded", (members) => {
console.log(`${members.count} online`);
members.each((member) => console.log(member.id, member.info));
});
channel.bind("pusher:member_added", (member) => console.log("joined", member.info));
channel.bind("pusher:member_removed", (member) => console.log("left", member.info));Your authorization endpoint supplies each member's user_id and user_info, see Authentication. Members are identified by user_id, so the same user in two tabs counts once.
A presence channel holds 100 members by default (more on higher plans), and each member's user_info can be about 2 KB. See Limits and quotas.
Naming
Channel and event names can be up to 200 characters. Stick to letters, digits and _ - = @ , . ;. The Pusher libraries reject names that are too long before sending anything.