Quick Start Guide
Get up and running with RelayGrid in minutes.
1
Create a Notification User
A Notification User represents a recipient in your system. To send notifications, you first need to register your users with RelayGrid. We recommend using your own internal user ID as the external_user_id.
Shell
curl -X POST "https://relaygrid.dev/api/v1/notification_users" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"notification_user": {
"external_user_id": "user_12345",
"first_name": "Alice",
"last_name": "Smith"
}
}'Response201 Created
{
"notification_user": {
"id": 42,
"first_name": "Alice",
"middle_name": "",
"last_name": "Smith",
"external_user_id": "user_12345",
"created_at": "2026-06-08T10:15:30.000Z",
"updated_at": "2026-06-08T10:15:30.000Z"
}
}2
Obtain a Channel Token
For secure real-time connections, your frontend needs a short-lived channel_token. You should request this token from your backend server using your RelayGrid API Key.
Shell
curl -X POST "https://relaygrid.dev/api/v1/channel_tokens" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_user_id": "user_12345"
}'Response200 OK
{
"token": "eyJhbGciOiJIUzI1NiJ...",
"expires_in": 3600
}3
Connect to WebSocket
Finally, use the channel_token to connect your frontend to the real-time notification channel using ActionCable.
Register your origin first. For security, RelayGrid only accepts WebSocket connections from domains you have allow-listed. Before connecting, add the exact origin of the site that will connect (for example
https://app.yourcompany.com) under Settings → Server Configuration → Allowed Origins. Origins take effect immediately — connections from an unlisted origin are rejected.JavaScript
import { createConsumer } from "@rails/actioncable";
const consumer = createConsumer("wss://relaygrid.dev/cable");
const subscription = consumer.subscriptions.create(
{
channel: "MessagesChannel",
channel_token: "YOUR_CHANNEL_TOKEN"
},
{
received(data) {
console.log("New notification received:", data.message);
// Show a toast or update your UI
},
connected() {
console.log("Connected to RelayGrid!");
}
}
);