We’re on Product Hunt (opens in a new tab)

Messaging

Send events over your socket.

Exchange typing indicators, cursor movements and room messages through an existing connection. Each sender needs an explicit, short-lived permission from your backend.

Enable and authorize

In your application’s App keys page, enable Client events. It is off by default. Public channels remain read-only for client publishing. Only subscribed private and presence channels can receive client publications.

Your backend authenticates the user, checks access to the exact channel and selects the allowed event names. A subscription signature alone never grants publishing. Return a separate publish_token alongside auth and, for presence, channel_data. Presence publishing must use the same user ID as the subscription.

Permission covers one application, socket, channel, user and 1–8 exact client- event names. It lasts 1–300 seconds. No wildcard or multi-channel client publishing is supported. Keep the application secret on your server. Never accept a client-supplied user ID or event allowlist without checking it.

Client events are user input. A verified sender is not proof that a payment, role change or other business action is valid. Keep those decisions in trusted server logic.

JavaScript and TypeScript

Install @pubb/[email protected] from npm. The server helper calls pubb when issuing a permission; subsequent publications use WebSocket without an HTTP request per event.

Your backend authorization endpoint
// Your authenticated backend; application-specific checks are required.
const user = await requireUser(request);
const { socket_id, channel_name } = await request.json();
await requireChannelAccess(user, channel_name);

const subscription = pubb.authenticatePrivateChannel(socket_id, channel_name);
const permission = await pubb.authorizeClientEvents(socket_id, channel_name, {
  userId: user.id,
  events: ["client-message", "client-typing"], // chosen by your backend
  ttlSeconds: 300,
});
return Response.json({ ...subscription, ...permission });
Browser: send and receive
const pubb = new Pubb(APP_KEY, { authEndpoint: "/api/pubb/auth" });
const room = pubb.subscribe("private-room-123");
room.bind("client-message", (data, metadata) => {
  console.log(metadata?.user_id, data); // identity added by pubb
});
room.onSubscribed(async () => {
  try {
    const receipt = await room.send("client-message", { text: "Hello" });
    console.log(receipt.publicationId); // accepted, not a delivery receipt
  } catch (error) {
    console.error(error.code, error.id);
  }
});
pubb.connect();

// Renew permissions when your session/access allows it; no resubscription needed.
// await room.refreshPublishAuthorization();

For presence channels, use authenticatePresenceChannel with the verified user’s ID. The browser receives events from other senders; pubb excludes the originating socket. Render your own optimistic update if needed.

.NET backend and Unity client

.NET server: permission
var grant = await pubb.AuthorizeClientEventsAsync(
    socketId, channelName, verifiedUserId,
    new[] { "client-message" }, ttlSeconds: 300);
// Return grant.PublishToken as publish_token with your subscription auth.
Unity: after subscription acknowledgement
room.BindWithMetadata("client-message", (data, metadata) => {
    Debug.Log(metadata?["user_id"]);
});
var receipt = await room.SendAsync("client-message", new { text = "Hello" });
// Renew through your IChannelAuthorizer when needed:
await room.RefreshPublishAuthorizationAsync();

Unity’s HttpChannelAuthorizer reads publish_token from your auth response. Continue calling Tick() in Update to send queued commands and process acknowledgements. Other SDK versions can use the wire protocol below; do not assume they expose these new helpers.

Wire protocol

Trusted backend: issue permission
POST https://api.pubb.io/api/apps/YOUR_APP_ID/client-events/grants
Authorization: Bearer YOUR_APP_SECRET
Content-Type: application/json

{"socket_id":"0123456789abcdef0123456789abcdef","channel_name":"private-room-123","user_id":"42","events":["client-message"],"ttl_seconds":300}

The response contains publish_token (opaque signed permission) and expires_at (Unix seconds). Auth failures use HTTP 401; disabled client events use 403; invalid scopes use 400.

Client → socket: publish after subscribing
{
  "action": "publish",
  "id": "a-unique-message-id",
  "channel": "private-room-123",
  "name": "client-message",
  "data": {
    "text": "Hello"
  },
  "publish_token": "TOKEN_FROM_YOUR_BACKEND"
}
Socket → sender: acceptance
{
  "event": "pubb:publish_succeeded",
  "id": "a-unique-message-id",
  "channel": "private-room-123",
  "data": {
    "accepted": true,
    "publicationId": "PUBLICATION_ID",
    "duplicate": false
  }
}
Socket → sender: rejection
{
  "event": "pubb:publish_error",
  "id": "a-unique-message-id",
  "channel": "private-room-123",
  "data": {
    "code": "publish_forbidden",
    "message": "Publish permission does not cover this event"
  }
}
Socket → other subscribers
{
  "channel": "private-room-123",
  "data": "{\"name\":\"client-message\",\"data\":{\"text\":\"Hello\"},\"metadata\":{\"source\":\"client\",\"user_id\":\"42\",\"socket_id\":\"0123456789abcdef0123456789abcdef\"}}"
}

Use the outer event’s metadata.user_id, not a user ID inside data. Metadata is produced by pubb from the verified permission. Client packets cannot choose another application, sender or internal system event.

Expiry, revocation and delivery

Every publication checks the permission and current application policy. Disabling Client events or choosing Revoke publishing permissions invalidates previously issued tokens, including after the feature is enabled again. Already accepted publications may still arrive. Renewing a token requires your backend to check access again. Removing a user in your own database does not automatically notify pubb: revoke application permissions for immediate invalidation, or let their existing token expire within five minutes.

A reconnect gets a new socket ID and requires fresh subscription auth and publishing permission. SDKs clear old tokens, fail pending sends and never automatically replay publications on a new connection.

An acknowledgement confirms transactional acceptance and usage accounting, not subscriber delivery or read status. On a timeout, acceptance is unknown. Retry with the same ID and identical data on the same connection to deduplicate for 24 hours. A reused ID with different data is rejected. Across reconnects, use application-level idempotency for business actions.

Payloads are limited to 10 KiB of UTF-8 JSON; the entire command must fit 16 KiB. IDs use 8–64 letters, digits, underscores or hyphens. Channel suffixes use 1–190 ASCII letters, digits or _=@,.;-; event suffixes use 1–93 letters, digits or _.- after client-. Each connection accepts 20 commands/second; publishing also has a shared 20/second limit per verified user within an application. Existing workspace connection, operation, bandwidth and monthly quotas still apply. SDK pending queues are bounded at 32 publications.

Handle publish_forbidden, client_events_disabled and not_subscribed by fixing authorization. Use bounded backoff for busy, policy_unavailable, publish_unavailable and rate limits. publish_timeout may mean the event was accepted. No offline replay or message history is provided.

Within pubb, socket admission uses Redis-backed policy. The internal publication worker keeps PostgreSQL quota/accounting and the durable outbox consistent with server publishing. This removes per-event HTTP calls; it does not bypass accounting or promise a particular latency.