Docs.
Ten sections. Read the first three and you can send a message.
Concepts.
| App | One product of yours. It has a key, a secret, allowed origins, schemas and settings. An account can have three. |
| App key | A public id that starts with rhk_. Your backend sends it when it asks for a token. |
| Secret | A private value that starts with rhs_. It is shown once when you create the app. It lives on your backend and nowhere else. |
| User id | The id of a signed-in user in your own system. 1 to 128 characters from A-Z a-z 0-9 _ - . : @. |
| Token | Proof that one user belongs to one app. Valid for one hour unless you ask for a different time. Your frontend gets it from your backend. |
| Event | The name of a kind of message, such as chat or typing. Up to 100 characters from A-Z a-z 0-9 _ - . :. |
Quick start.
- Create an account, confirm your email, and create an app in the dashboard. Copy the key and the secret.
- Put both on your backend as configuration. The secret never goes to a browser.
- Add a route that asks the hub for a token for the signed-in user (section 03).
- Load the browser client and connect with that token (section 04).
- Call
sendand listen withonEvent(section 05).
The app page in the dashboard has a Quickstart tab with these steps filled in with your own key and app id.
Get a token.
Your backend calls the hub with the secret and names the user. The hub returns a token for that user.
curl -X POST https://realtimehub.raheelshan.com/api/token \
-H "Authorization: Bearer YOUR_APP_SECRET" \
-H "Content-Type: application/json" \
-d '{"appKey":"YOUR_APP_KEY","userId":"42"}'
{"token":"eyJhbGciOi...","expiresAtUtc":"2026-11-21T10:00:00Z"}
ttlSecondsis optional. The default is 3600. The minimum is 60 and the maximum is 86400.- The token is checked when a connection opens. A connection that is already open keeps working after the token expires. A reconnect needs a fresh token, which the browser client fetches on its own.
- A wrong secret, an unknown app key and an inactive app all return
401. A bad user id returns400. More than 300 requests a minute from one address returns429.
// config/hub.php
return [
'url' => env('HUB_URL', 'https://realtimehub.raheelshan.com'),
'key' => env('HUB_KEY'), // YOUR_APP_KEY
'secret' => env('HUB_SECRET'), // the secret shown once in the dashboard
];
// routes/web.php
use Illuminate\Support\Facades\Http;
Route::get('/hub-token', function () {
$hub = config('hub');
return Http::withToken($hub['secret'])
->post($hub['url'].'/api/token', [
'appKey' => $hub['key'],
'userId' => (string) auth()->id(),
])->throw()->json();
})->middleware('auth');
app.get('/hub-token', requireLogin, async (req, res) => {
const r = await fetch(`${process.env.HUB_URL}/api/token`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HUB_SECRET}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
appKey: process.env.HUB_KEY,
userId: String(req.user.id),
}),
});
res.status(r.status).json(await r.json());
});
Take the user id from your own session, never from the request. Whoever controls the user id controls who they appear to be.
Browser client.
The hub serves a small wrapper around the SignalR browser library. It caches the token, reconnects with backoff, and retries a first connection that fails.
<script src="https://cdn.jsdelivr.net/npm/@microsoft/signalr@8.0.7/dist/browser/signalr.min.js"></script>
<script type="module">
import { createRealtimeClient } from 'https://realtimehub.raheelshan.com/sdk/realtimehub-client.js';
const client = createRealtimeClient({
hubUrl: 'https://realtimehub.raheelshan.com/hub/chat',
fetchToken: () => fetch('/hub-token').then((r) => r.json()),
onEvent: (m) => console.log(m.from, m.event, m.payload),
onStatus: (s) => console.log('status', s),
});
await client.start();
const sent = await client.send('bob', 'chat', { text: 'hello' });
console.log(sent.id, sent.persisted);
</script>
| Option or method | What it does |
|---|---|
hubUrl | The hub address followed by /hub/chat. |
fetchToken | Returns { token, expiresAtUtc }. Usually a call to your /hub-token route. |
onEvent(message) | Called for every message addressed to this user. |
onStatus(status, error) | connecting, connected, reconnecting or disconnected. |
start() | Resolves when connected. |
send(userId, event, payload) | Resolves with { id, timestampUtc, persisted }. Rejects with the reason when the hub refuses the message. |
stop() | Closes the connection and stops reconnecting. |
React Native and other non-browser apps can use the official SignalR client for their platform with the same URL and token.
Send and receive.
A message goes from one user to one user in the same app. The hub sets from from the token, so a client cannot send as someone else.
{
"id": "9f2c6e1a4b7d4c0a8e3d5b6a7c8d9e0f",
"from": "alice",
"to": "bob",
"event": "chat",
"payload": { "text": "hello" },
"timestampUtc": "2026-11-21T09:00:32.296Z"
}
- Every open connection of the recipient receives it, so a user with two tabs sees it in both.
- A user who is offline does not receive it later. Turn on persistence (section 08) if you need a record.
- A message to your own user id reaches your own connections, so you can test with one account.
- Users in other apps never receive it, even with the same user id.
Allowed origins.
A browser can only connect from a website you list on the app: scheme, host and port, no path. For example https://app.example.com or http://localhost:3000. An app can list 20.
Mobile apps and servers send no Origin header and are accepted on the strength of the token alone.
Schemas.
Give an event a JSON Schema and every payload for that event is checked before delivery. A payload that does not match is rejected, and the sender gets the reason.
{
"type": "object",
"required": ["text"],
"properties": {
"text": { "type": "string", "minLength": 1, "maxLength": 500 },
"replyTo": { "type": "string" }
},
"additionalProperties": false
}
Payload does not match the schema for 'chat': /text: Value is "integer" but should be "string"
- Define schemas in the dashboard, under the app's Schemas tab. The tester there runs the same check the hub runs.
- An event with no schema accepts any payload. Turn on strict mode and an event with no schema is rejected.
- A schema can be up to 64 KB and an app can describe up to 50 events.
$refworks for references inside the same schema, such as#/$defs/name. References to other URLs are refused.- The regular expression keywords
patternandpatternPropertiesare not supported yet. Useenum,const,minLength,maxLength,minimum,maximumortype.
Save messages.
With persistence on, every message is also written to a Redis stream that belongs to your app. A Laravel command reads the stream and stores each message in your database.
- Turn on persistence for the app. Open its Persistence tab and create the Redis user. The password is shown once.
- Download the Laravel package: realtimehub-laravel.zip.
# 1. Put the downloaded realtimehub-laravel.zip in a folder called packages/
# (on Windows, add this repository to composer.json by hand instead of using the next command)
composer config repositories.realtimehub '{"type":"artifact","url":"packages/"}'
composer require ohad/realtimehub-laravel
php artisan vendor:publish --tag=realtimehub-config
php artisan vendor:publish --tag=realtimehub-migrations
php artisan migrate
REALTIMEHUB_APP_ID=YOUR_APP_ID
REALTIMEHUB_REDIS_CONNECTION=realtimehub
REALTIMEHUB_REDIS_HOST=<host from the Persistence page>
REALTIMEHUB_REDIS_USERNAME=<username from the Persistence page>
REALTIMEHUB_REDIS_PASSWORD=<password from the Persistence page>
// config/database.php, inside 'redis' => [ ... ]
'realtimehub' => [
'host' => env('REALTIMEHUB_REDIS_HOST'),
'username' => env('REALTIMEHUB_REDIS_USERNAME'),
'password' => env('REALTIMEHUB_REDIS_PASSWORD'),
'port' => 6379,
'database' => 0,
'read_timeout' => 15,
],
php artisan rt:consume
- Each message fires a
RealtimeEventReceivedevent in Laravel and, by default, is saved to therealtime_eventstable. - Delivery is at least once. The saved row is keyed by the message id, so a repeat never creates a second row.
- A failed message is retried up to five times, about 30 seconds apart, then moved to the
rt:{appId}:deadstream. - The hub keeps about 100,000 messages per app in the stream. A worker that is offline for long can lose the oldest ones.
Errors and limits.
Message from send | Cause |
|---|---|
| Not connected to the hub. | Call start() first, or wait for connected. |
| Rate limit exceeded. | One connection sent more than 10 messages a second (burst 20). |
| App rate limit exceeded. | All connections of the app together passed the app limit (100 a second, burst 200, by default). |
| Invalid toUserId. / Invalid eventName. | The id or the name uses characters outside the allowed set. |
| Payload exceeds 32768 bytes. | The payload JSON is larger than 32 KB. |
| Payload does not match the schema for '<event>': ... | The payload failed the schema. The text after the colon says where. |
| Event '<event>' has no schema and this app requires one. | Strict mode is on and the event is not described. |
| App is not active. | The app was paused or the account was suspended. |
Limits
| Apps per account | 3 |
| Open connections per app | 1,000 |
| Messages per second per app | 100, burst 200 |
| Messages per second per connection | 10, burst 20 |
| Payload | 32 KB of JSON |
| Event schemas per app | 50, each up to 64 KB |
| Allowed origins per app | 20 |
| Token requests | 300 a minute per address |
The operator can raise the connection and message limits for an app. They are not editable from the dashboard.
Security.
- The secret stays on your backend. If it leaks, rotate it in the dashboard. The old one stops working at once.
- Only the hash of the secret is stored. We cannot show it again, so keep a copy.
- Use HTTPS for the hub and for your own site.
- Take the user id for a token from your session. Never trust one sent by the browser.
- List only the origins you use. Remove
http://localhostentries from a live app. - Redis users are limited to your app's two streams. They cannot read any other key.