Docs

Pushefy documentation

Pushefy speaks the Pusher Channels protocol. Every Pusher library works: you only change the host and keys. This guide covers connecting, sending, channels, the HTTP API, limits and troubleshooting.

Quick start

  1. Create a free account and confirm your email.
  2. In Apps, click New app. You get an app ID, a key and a secret.
  3. In the browser, connect with the key (never the secret) and subscribe to a channel.
  4. On your server, send events with the app ID, key and secret.
  5. Open the app in your dashboard and use Send a test to check everything works.

Connection settings

Use these values wherever a Pusher library asks for them.

Hostws.pushefy.comReplaces cluster / api-mt1.pusher.com.
Port443For both websockets and the HTTP API.
TLSon (wss / https)Always encrypted on our servers.
Clustermt1Some libraries require a value. Any value works; it isn't used.

Browser (pusher-js)

Load pusher-js 8 from Pusher's CDN or npm (npm i pusher-js), then connect with your app key:

const pusher = new Pusher('YOUR_APP_KEY', {
  cluster: 'mt1',
  wsHost: 'ws.pushefy.com',
  wsPort: 443,
  wssPort: 443,
  forceTLS: true,
  enabledTransports: ['ws', 'wss'],
});

const channel = pusher.subscribe('orders');
channel.bind('order.created', (data) => {
  console.log('New order', data);
});

enabledTransports keeps pusher-js on websockets (Pushefy doesn't offer the old HTTP fallback transports).

Laravel Echo

Use Echo's pusher broadcaster with your key and our host:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';
window.Pusher = Pusher;

window.Echo = new Echo({
  broadcaster: 'pusher',
  key: import.meta.env.VITE_PUSHER_APP_KEY,
  cluster: 'mt1',
  wsHost: 'ws.pushefy.com',
  wsPort: 443,
  wssPort: 443,
  forceTLS: true,
  enabledTransports: ['ws', 'wss'],
});

Echo.channel('orders').listen('.order.created', (e) => console.log(e));

Laravel (sending)

Laravel's built-in Pusher driver works as it is. In .env:

BROADCAST_CONNECTION=pusher
PUSHER_APP_ID=YOUR_APP_ID
PUSHER_APP_KEY=YOUR_APP_KEY
PUSHER_APP_SECRET=YOUR_APP_SECRET
PUSHER_HOST=ws.pushefy.com
PUSHER_PORT=443
PUSHER_SCHEME=https
PUSHER_APP_CLUSTER=mt1

Then broadcast as usual, for example broadcast(new OrderCreated($order)); with an event that implements ShouldBroadcast.

PHP (sending)

With the official library, composer require pusher/pusher-php-server:

$pusher = new Pusher\Pusher('YOUR_APP_KEY', 'YOUR_APP_SECRET', 'YOUR_APP_ID', [
    'host'   => 'ws.pushefy.com',
    'port'   => 443,
    'scheme' => 'https',
    'useTLS' => true,
]);

$pusher->trigger('orders', 'order.created', ['id' => 1042, 'total' => 89.5]);

Node.js (sending)

With the official library, npm i pusher:

const Pusher = require('pusher');

const pusher = new Pusher({
  appId: 'YOUR_APP_ID',
  key: 'YOUR_APP_KEY',
  secret: 'YOUR_APP_SECRET',
  host: 'ws.pushefy.com',
  port: '443',
  useTLS: true,
});

await pusher.trigger('orders', 'order.created', { id: 1042 });

Any other Pusher server library (Python, Ruby, Go, Java, .NET) works the same way: set host, port and TLS instead of the cluster.

Channels

TypeName starts withWho can subscribe
PublicanythingAnyone with your key. Use for public data only.
Privateprivate-Only users your server signs in (see below).
Presencepresence-Like private, plus everyone sees who else is subscribed.
Cachecache-, private-cache-, presence-cache-New subscribers immediately get the last event sent.

Channel names can use letters, numbers and _ - = @ , . ;. Event names starting with pusher: are reserved.

Private & presence auth

When the browser subscribes to a private- or presence- channel, pusher-js calls your server (default /pusher/auth, or /broadcasting/auth with Laravel). Your server checks the user may join and returns a signature made with your secret. Pushefy never sees your users' sessions.

// PHP: your auth endpoint
$socketId = $_POST['socket_id'];
$channel  = $_POST['channel_name'];
// ... check the logged-in user may use $channel ...
echo $pusher->authorizeChannel($channel, $socketId);

// Presence channel: include who the user is
echo $pusher->authorizePresenceChannel($channel, $socketId, $userId, ['name' => $userName]);

With Laravel, define the rules in routes/channels.php and Echo handles the rest.

Client events

Browsers can send events straight to other subscribers of a private or presence channel, for example "user is typing". The event name must start with client-:

const channel = pusher.subscribe('private-chat.42');
channel.bind('pusher:subscription_succeeded', () => {
  channel.trigger('client-typing', { user: 'Ana' });
});

Client events count as messages like any other event.

HTTP API

Server libraries call these for you. Requests are signed with your secret (Pusher's standard auth_signature). Base URL: https://ws.pushefy.com

MethodPathWhat it does
POST/apps/{app_id}/eventsSend one event to one or more channels.
POST/apps/{app_id}/batch_eventsSend several events in one request.
GET/apps/{app_id}/channelsChannels that have subscribers.
GET/apps/{app_id}/channels/{name}One channel: occupied, subscription count.
GET/apps/{app_id}/channels/{name}/usersUsers in a presence channel.
POST/apps/{app_id}/users/{user_id}/terminate_connectionsDisconnect every connection of a user.
GET/apps/{app_id}/connectionsNumber of open connections.

An event's data can be up to 10 KB.

Limits & usage

  • Messages: each event delivered to one connected browser counts as one message. An event sent to a channel with 50 subscribers is 50 messages. Pings and subscription replies are free.
  • Daily messages are counted per account, across all your apps, and reset at midnight. We email you at 80% and 100%. At 100%, the HTTP API refuses new events until midnight; connected browsers stay connected. Upgrading lifts the limit within seconds.
  • Connections at once are one total for all apps in your account (you can also set a lower limit per app). New connections over the limit are refused with error 4004; you can also set a lower limit per app in its settings.
  • Apps per account depend on your plan.
  • Usage is shown in Plan & usage and updates about every 10 seconds.

See the limits of each plan →

Security

  • Never put the secret in browser or mobile code. Only your servers use it.
  • Allowed websites: in your app's settings, list the domains that may connect with your key (for example example.com and *.example.com). Other sites are refused.
  • New secret: if a secret leaks, click Create a new secret. The old one stops working within 10 seconds; update your servers.
  • Use private channels for anything personal, and check permissions in your auth endpoint.

Moving from Pusher

  1. Create an app here and copy its ID, key and secret.
  2. In the browser: add wsHost, wsPort, wssPort, forceTLS and enabledTransports as above, and use the new key.
  3. On the server: set host, port and TLS instead of cluster, and use the new ID, key and secret.
  4. Keep your channel names, event names and auth endpoint as they are.
  5. Deploy, open your app's page here, and check connections appear.

Pusher webhooks and the Pusher debug console aren't available. Use the live test and connection count on your app's page instead.

Errors & troubleshooting

You seeWhyFix
4001 Application does not existWrong key, the app is off, deleted, or the account is suspended.Check the key and that the app is on.
4004 Over connection quotaThe app reached its connection limit.Raise the app's limit or upgrade your plan.
4009 Origin not allowedThe website isn't in the app's allowed websites.Add the domain in the app's settings.
4009 Connection is unauthorizedYour auth endpoint's signature is wrong.Sign with the app's current secret.
HTTP 401 when sendingWrong secret, or the server clock is far off.Use the current secret; sync the server clock.
HTTP 404 when sendingWrong app ID, app off, daily messages used up, or (with a path) the path has no trailing slash.Check the app ID and usage.
pusher-js stays "connecting"Wrong host or port, or a firewall blocks websockets.Check host, port and forceTLS.

Still stuck? Use Send a test on your app's page: if that works, the problem is in your code's settings.