Concepts
A whirlwind tour of the things you’ll be working with. If you’ve used Pusher Channels, every term here means exactly what it does there.
Apps
An app is a logical container with its own credentials and limits. One Mawjly account can have many apps (your plan caps how many). Each app has:
- App ID — public numeric identifier (e.g.
6855671). - Key — public, ships in client-side code.
- Secret — server-only, signs HTTP API calls and channel auth tokens. Never expose it in a browser bundle.
- Cluster — the region the app’s WebSocket cluster runs in (currently always
sa).
You manage apps from the dashboard at /dashboard/apps.
Connections
Every browser tab, mobile app, or server-side socket that opens a WebSocket to Mawjly counts as one connection. Your plan limits the maximum number of concurrent connections.
A connection is just transport — it doesn’t do anything on its own. To send and receive events, the connection has to subscribe to a channel.
Channels
A channel is a named pub/sub topic. Anyone subscribed to a channel receives every event published to it.
Channel name conventions determine behavior:
| Prefix | Type | Auth | Use case |
|---|---|---|---|
| (none) | Public | None | Open broadcasts, public chat rooms, live tickers |
private- | Private | Server signs subscription | Per-user inboxes, paid features |
presence- | Presence | Server signs subscription + provides member info | Multiplayer games, “who’s online” lists |
private-encrypted- | Encrypted | Server signs + payloads E2E encrypted | HIPAA / PII / secrets where Mawjly should never see content |
Events
An event is a message published to a channel. Anyone subscribed receives it within ~50ms (Riyadh region) or whatever WebSocket round-trip your client is from the cluster.
Events have:
- Channel — where it’s published.
- Event name — your application-defined string (e.g.
message,typing,order.shipped). Names must match[A-Za-z0-9_\-:.]+. - Data — JSON payload. Pusher’s HTTP API requires it be a string; the SDKs serialize it for you.
Triggers
Events are published from your backend via the HTTP API (or via an SDK that wraps it). Browsers can publish too via client events if your app has them enabled, but only on private- and presence- channels.
Webhooks
Mawjly can POST events back to your server when interesting things happen — a channel becomes occupied, a user joins/leaves a presence channel, a client publishes a client event. You configure webhooks per app in the dashboard. Each delivery is HMAC-signed; verify the signature before trusting the payload.
What’s outside the scope of this protocol
- Persistent message history — Pusher Channels (and Mawjly) don’t replay past events to new subscribers by default. If you need history, store events in your own database and let new subscribers fetch the backlog before connecting.
- Mobile push notifications — separate product (Pusher Beams). Mawjly doesn’t ship this.
- Native client SDKs by us — we don’t ship our own SDK; the official Pusher SDK in every supported language works unchanged.