Real-time events (WebSockets)

Exowpee pushes some updates to connected clients over WebSockets, served by Laravel Reverb. They are not HTTP webhooks: nothing calls your server. A client opens a WebSocket, subscribes to private channels with its session token, and listens. Live delivery is on only when the deployment sets BROADCAST_CONNECTION=reverb. With the default null connection nothing is pushed. Notifications are also stored, so a client that was offline reads them later with List my notifications.

Channels

Every channel is private. You subscribe with your session token, and the rules below say who may join.

Channel	Who may subscribe	What it carries
`clientRefresh.{company_id}`	Company session of that company	Refresh state, see below
`clientRefresh.client.{client_id}`	Client account session of that client	Refresh state
`clientRefresh.organization.{organization_id}`	Organization session, with a selected profile, of that organization	Refresh state
`notification.user.{id}`	A member (not an agent account) whose user id is `{id}`, in any of their sessions	Notifications about the member’s own account
`notification.user-profile.{id}`	A company session whose selected assignment id is `{id}`	Notifications for that assignment
`notification.agent.{id}`	The company agent account `{id}`	Notifications for that agent
`notification.client-agent.{id}`	The client agent account `{id}`	Notifications for that agent
`notification.organization-agent.{id}`	The organization agent account `{id}`, with a profile	Notifications for that agent

Refresh state

The refresh state tells a client which of its cached lists are still current. The server keeps, for each profile assignment or agent account, the list of refresh keys it has read. Check for data refresh returns that record (meta_data), and creates it empty on the first call. When the read list of an actor changes, the server broadcasts ClientRefreshEvent on the channel of the actor’s space, after a one-second pause that groups close changes into one message. The event runs on the client_refresh queue, so a queue worker for it must be running. Today the list is emptied, and so the event sent, when an agent account signs in and when a member switches profile: see authentication. The event name is the class name Exowpee\Notification\Events\ClientRefreshEvent. Its payload is:

{
  "readKeysByActorId": {
    "<actor id>": ["<refresh key>", "<refresh key:id1,id2>"]
  }
}

readKeysByActorId maps each affected actor id (assignment id for a member, agent id for an agent account) to the refresh keys it has read. A key is a name, optionally followed by : and a comma-separated list of ids. A client compares the list with its own to know what to reload. All actors of the space receive the same message, so a client reads only its own entry.

Notifications

A notification delivered “in app” is stored and also pushed on the channel of its recipient, as a standard Laravel notification broadcast. The data is the payload of the notification, with id and type added by Laravel. type is one of the values below.

Type	Raised when	Payload	Recipients
`awaiting_approval`	An order is created and waits for approval	`order_id`, `order_number`, `requested_by_user_id`, `cta_url` (null)	Members who hold `orders.approve`, as set in the company’s notification settings
`password_changed`	A member changes their password	`changed_at`, `ip`	The member, on `notification.user.{id}`
`invitation_received`	An existing member is invited to a company, client account or organization	`company_name`, `client_name` or `organization_name` (the one that applies), `cta_url`	The invited member, on `notification.user.{id}`

The code also defines stock_alert (configurable per company) and new_device_login, but nothing raises them yet, so no message of these types is sent. System notifications (password_changed, invitation_received) are fixed by the platform: in app and by email, with no setting. Company notifications follow the channels and recipients set with Configure a notification type.

Listen with Laravel Echo

Authorize the channels with the same bearer token as the API.

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

const echo = new Echo({
  broadcaster: 'reverb',
  key: REVERB_APP_KEY,
  wsHost: REVERB_HOST,
  wsPort: REVERB_PORT,
  forceTLS: true,
  authEndpoint: 'https://api.exowpee.com/broadcasting/auth',
  auth: { headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' } },
});

// Refresh state of a company session
echo.private(`clientRefresh.${companyId}`)
  .listen('.Exowpee\\Notification\\Events\\ClientRefreshEvent', (e) => {
    const mine = e.readKeysByActorId[myAssignmentId];
  });

// Notifications of the selected profile (company session)
echo.private(`notification.user-profile.${userProfileId}`)
  .notification((n) => console.log(n.type, n));

Reverb key, host and port come from the deployment.

Limits to plan for

After a profile switch, a sign-out or a renewal, the old token is no longer valid. Close the sockets and subscribe again with the new token. The server does not close a socket whose token was revoked after the subscription.
A subscription is refused when the session does not match the channel: a company session cannot join a client account channel.
Messages are not replayed. A client that was disconnected reads the current state with the HTTP actions above.

Start here

Concepts

Reference

Real-time events (WebSockets)

Channels

Refresh state

Notifications

Listen with Laravel Echo

Limits to plan for

​Channels

​Refresh state

​Notifications

​Listen with Laravel Echo

​Limits to plan for

Channels

Refresh state

Notifications

Listen with Laravel Echo

Limits to plan for