WebGame Connect - mssgs | Build Mini Games for mssgs

Overview

Mini games are web pages loaded inside the mssgs client via an iframe. The platform handles all session management, player tracking, and lifecycle - your game just needs to respond to webhooks and render a web UI.

How it works

A user creates a game session inside a server, players join, and each player's client loads your game's URL with session parameters. Your backend receives webhooks as players join or leave.

How It Works

1

Session created

A user creates a game session inside a server.

2

Players join

Players join the session via the mssgs client.

3

Game loads

Each player's client loads your game's web_url with session parameters.

4

Webhooks fire

Your backend receives webhooks as players join or leave.

5

Cleanup

When all players leave, the session is cleaned up automatically.

Game Registration

Each game is registered with the following fields:

Field	Description
`name`	Display name of the game (e.g. "Trivia")
`icon_url`	URL to the game icon
`web_url`	Base URL of the game's web page
`max_players`	Maximum number of players allowed
`min_players`	Minimum number of players required
`webhook_join_url`	Called when a player joins
`webhook_leave_url`	Called when a player leaves

Web URL

When a player joins a game session, the mssgs client loads your web_url with query parameters appended:

URL Format

{web_url}?session={session_id}&game_user={game_user_id}

Parameter	Description
`session`	The game session UUID - identifies which game session this player belongs to
`game_user`	A unique 8-character ID assigned to this player for this session

Example

If your web_url is https://games.example.com/trivia, a player's browser will load:

Example URL

https://games.example.com/trivia?session=a1b2c3d4-e5f6-7890-abcd-ef1234567890&game_user=de875d3a

Your web page should:

Read session and game_user from the URL query params
Connect to your own backend using these identifiers
Render the game UI

Important

The game_user is a short, opaque identifier. It does not contain any personal information. Player display names and usernames are only sent via webhooks to your backend - never expose them to the client-side game code unless your backend provides them.

Webhooks

Your backend receives POST requests with a JSON body from the mssgs platform as players interact with the game session. These are fire-and-forget - failures do not affect the game session.

Webhook JSON body

Request Body

{
  "session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "player1",
  "display_name": "Player One",
  "game_user": "de875d3a",
  "host": true
}

Field	Type	Description
`session`	string	The game session UUID
`username`	string	The player's mssgs username
`display_name`	string	The player's display name (falls back to username if not set)
`game_user`	string	The player's unique 8-character game user ID (same ID the client receives)
`host`	boolean	Only present on join/leave webhooks when the player is the session host

Join Webhook

Called when a player joins the session.

POST {webhook_join_url}

The host field is only present when the joining player is the one who created the session. Use this to identify the game host (e.g. for starting the game, managing settings).

Leave Webhook

Called when a player explicitly leaves the session.

POST {webhook_leave_url}

The host field is only present when the leaving player is the session host. You may want to handle host migration or end the game when the host leaves.

Disconnects

Players are not automatically removed when they disconnect (e.g. refresh, background, connection drop). They remain in the session and can rejoin. Stale sessions are cleaned up after 1 hour of inactivity.

Security

Use game_user for player identity

The game_user ID is the only player identifier sent to the client-side game (via the web URL). It is:

Unique per player per session
An opaque 8-character string
Not reused across sessions

Player usernames and display names are only sent to your backend via webhooks, never to the client-side game. This prevents players from spoofing identities and personal information from leaking to the browser.

Validate session and game_user on your backend

Your game's web page will send session and game_user to your backend (e.g. via WebSocket or API calls). Always validate that:

The session is a known, active session on your backend (received via a join webhook)
The game_user was registered via a join webhook for that session
The game_user has not already left (received via a leave webhook)

Webhook origin

Webhooks originate from the mssgs gateway servers. Consider validating the source if your webhook endpoints are publicly accessible.

Game Lifecycle

Event	What Happens
Session created	A game channel appears in the server
Player joins	Join webhook fires, player count updates in channel
Player leaves	Leave webhook fires, player count updates
All players leave	Session is deleted, game channel is removed
1 hour inactivity	Session is cleaned up automatically

Architecture

Your backend maintains the game state. The mssgs platform only handles session lifecycle and player tracking - all game logic lives on your side.

Example Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  mssgs Client   │     │  mssgs Gateway   │     │  Your Backend   │
│  (loads iframe) │     │  (orchestrator)  │     │  (game logic)   │
└────────┬────────┘     └────────┬─────────┘     └────────┬────────┘
         │                       │                         │
         │  Player joins session │                         │
         │──────────────────────>│                         │
         │                       │  POST webhook_join_url  │
         │                       │────────────────────────>│
         │                       │                         │ Store player
         │  Load web_url?session=&game_user=               │
         │<──────────────────────│                         │
         │                       │                         │
         │  Connect to your backend with session+game_user │
         │────────────────────────────────────────────────>│
         │                       │                         │ Validate
         │                       │                         │ game_user
         │  Game data (via your own WebSocket/API)         │
         │<────────────────────────────────────────────────│
         │                       │                         │

Best Practices

Don't trust the client

Validate session and game_user on your backend against webhook data.

Handle disconnects

Players may leave unexpectedly. Always handle the leave webhook gracefully.

Host detection

Use the host: true webhook parameter to identify who controls the game.

Stateless web page

Your game page should initialize purely from URL params. Don't rely on cookies or local storage for session identity.

Responsive design

Games are loaded in a webview. Ensure your UI works on mobile and desktop.

Questions?

We're happy to help you with your game integration.

developers@mss.gs