REST API: community and invites

Members can see who is online and invite each other to any game. Invites are platform objects: for multiplayer games (max_players > 1) the game module pairs the two players; for single-player games the invite is a score challenge and the game simply starts.

Presence

Method	Path	Notes
POST	`/me/ping`	Marks the player as online (the portal sends this every 60 s). Returns `pending_invites`.
GET	`/community/online`	Members online in the last 5 minutes who have not hidden themselves, with their current game.

{ "members": [ { "id": 4, "username": "oliver", "display_name": "Oliver", "avatar_url": "…", "online": true, "playing": { "slug": "chess-master", "name": "Chess Master" } } ] }

Privacy: only logged-in members can read the list; email addresses and IPs are never exposed; a member can opt out under Profile → Show me in the Community.

Invites

Method	Path	Body	Notes
GET	`/invites`		`incoming` (pending) and `outgoing` (last 3 days)
POST	`/invites`	`{ to, game, message? }`	`to` is a username or player id. 422 with a readable reason if not possible.
GET	`/invites/{id}`		Participants only. Includes `payload` set by the game module.
POST	`/invites/{id}/accept`		Returns the invite with `play_url` = `/play/{slug}?invite={id}`
POST	`/invites/{id}/decline`		Decline (recipient) or withdraw (sender)

Invites expire after 24 hours. Offline recipients also get an email.

How a game module uses invites

The play shell forwards ?invite={id} to the entry file. Read it with new URLSearchParams(location.search).get('invite').
Your server module (games/{slug}/server/routes.php) loads the invite with App\Models\Invite::find($id), checks Invite::isParticipant($invite, $userId) and status === 'accepted', creates its own match or room, and stores a pointer with Invite::setPayload($id, ['match' => $code]) so both players open the same room.
Invites created inside your game (for example "invite by username" in a lobby) should go through App\Services\Invites::send($fromUser, $toUsername, $slug, $message, $payload) so they appear in the Community and trigger the email.

Chess Master (games/chess-master/server/routes.php) is the reference implementation.

Last updated October 11, 2026.