Docs/Channels
Presence Channels
Presence channel specification, member awareness protocol, and roster limits.
Specification
Presence channels build on private channels by tracking and synchronizing online participant rosters. All presence channel names must begin with the presence- prefix (e.g. presence-chat-room).
Subscriptions require an authorization payload containing both an HMAC signature and serialized user identity (channel_data).
Authorization Token Specification
The backend authorizes subscriptions and supplies member identity:
plaintext
String to sign: ${socket_id}:${channel_name}:${channel_data}
Signature: HMAC-SHA256(secret, string_to_sign)
Payload: { "auth": "${app_key}:${signature}", "channel_data": "${channel_data}" }Channel Data JSON Schema
channel_data must be a serialized JSON string containing:
json
{
"user_id": "user_42",
"user_info": {
"name": "Alice",
"role": "admin"
}
}| Property | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | Unique user identifier (max 128 characters). |
user_info | object | No | Arbitrary member metadata (max 1 KiB total size). |
Presence Protocol Events
| Wire Frame | Client SDK Event | Trigger Condition | Payload Properties |
|---|---|---|---|
pusher_internal:subscription_succeeded | pusher:subscription_succeeded | Initial channel subscription succeeds | { presence: { ids, hash, count } } |
pusher_internal:member_added | pusher:member_added | New member joins channel | { user_id, user_info } |
pusher_internal:member_removed | pusher:member_removed | Member leaves or disconnects | { user_id } |
Multi-Tab De-duplication
If a single user_id establishes multiple concurrent connections to the same presence channel:
- The member count increments only once.
member_addedbroadcasts only when the user's first socket joins.member_removedbroadcasts only after the user's final socket closes.
Presence Limits
| Resource | Threshold | Behavior When Exceeded |
|---|---|---|
| Max Members per Channel | 100 unique user IDs | Subscription rejected with wire error 4300 |
Max user_id Length | 128 characters | Subscription rejected with wire error 4300 |
| Max User Object Size | 1 KiB (1,024 bytes) | Subscription rejected with wire error 4300 |
Client SDK Reference
ts
const presenceChannel = pusher.subscribe('presence-chat-room')
// Initial online members roster
presenceChannel.bind('pusher:subscription_succeeded', (members: any) => {
console.log('Online count:', members.count)
members.each((member: { id: string; info: Record<string, any> }) => {
console.log('Member:', member.id, member.info)
})
})
// Member joined
presenceChannel.bind('pusher:member_added', (member: { id: string; info: Record<string, any> }) => {
console.log('Joined:', member.id)
})
// Member left
presenceChannel.bind('pusher:member_removed', (member: { id: string }) => {
console.log('Left:', member.id)
})