Quickstart

Get realtime events flowing in under 5 minutes.

Host and port below come from RELAY_PUBLIC_WS_HOST and RELAY_PUBLIC_WS_PORT (or defaults) on this deployment — copy the snippets from your own Relay dashboard for values that match your environment.

Relay runs your WebSocket server; cluster is only a placeholder required by pusher-js (Relay does not use Pusher regions).

1. Create an App

After signing up, go to your dashboard and create a new app. You'll get three credentials:

  • App ID — identifies your app
  • Key — public key used by client connections
  • Secret — private key for server-side API calls (never expose to clients)

2. Connect from the Browser

Include the Relay JS client (or use pusher-js — they're compatible):

<script src="/js/relay.js"></script>
<script>
const relay = new Relay('your-app-key', {
    wsHost: 'server.relayio.dev',
    wsPort: 6001,
    wssPort: 443,
    forceTLS: typeof relayPublicWebSocketForceTls === 'function' ? relayPublicWebSocketForceTls() : (location.protocol === 'https:'),
    cluster: 'mt1',
});

const channel = relay.subscribe('notifications');
channel.bind('new-message', (data) => {
    console.log('Received:', data);
});
</script>

Or with pusher-js (zero code changes):

<script src="https://js.pusher.com/8.0/pusher.min.js"></script>
<script>
const pusher = new Pusher('your-app-key', {
    wsHost: 'server.relayio.dev',
    wsPort: 6001,
    wssPort: 443,
    forceTLS: typeof relayPublicWebSocketForceTls === 'function' ? relayPublicWebSocketForceTls() : (location.protocol === 'https:'),
    enabledTransports: ['ws', 'wss'],
    cluster: 'mt1',
});

pusher.subscribe('notifications').bind('new-message', (data) => {
    console.log(data);
});
</script>

Raw WebSocket URL

This documentation site loads window.relayPublicWebSocketUrl(key) (same helper as the app dashboard). It uses the same host and port rules as above:

<script>
const url = window.relayPublicWebSocketUrl('your-app-key');
const ws = new WebSocket(url);
</script>

3. Trigger Events from Your Server

Use the REST API to send events:

curl -X POST http://relayio.dev/api/v1/apps/YOUR_APP_ID/events \
  -H "X-Relay-Key: YOUR_KEY" \
  -H "X-Relay-Secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-message",
    "channels": ["notifications"],
    "data": "{\"text\": \"Hello from the server!\"}"
  }'

Or with a Bearer token:

curl -X POST http://relayio.dev/api/v1/apps/YOUR_APP_ID/events \
  -H "Authorization: Bearer YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-message",
    "channels": ["notifications"],
    "data": "{\"text\": \"Hello!\"}"
  }'

4. See it Live

Open the Debug Console in your app dashboard to see events flowing in real-time.

Next Steps