mssgs Game SDK

Overview

The mssgs desktop app runs a small local HTTP bridge that a game on the same machine talks to. Your game never talks to our servers, never sees an account password or token, and can never post as the player. It talks to the copy of mssgs the player is already signed in to, and that copy decides what to answer.

What you can do with it:

• Detect that mssgs is installed and somebody is signed in.
• Read who the player is: user_guid, username, avatar.
• Ask "is this player in community X?" and what role they hold there.
• Publish a "Playing …" status with a Join now button for others.
• Receive a join hand-off when somebody presses that button.

Finding the client

The bridge listens on 127.0.0.1 only, on the first free port in a small range. Try them in order until one answers: 7440, 7441, 7442, 7443. Development builds of mssgs listen on 7540–7543 instead, so a test build never answers a real game's calls.

{
  "product": "mssgs",
  "api": 1,
  "client": "desktop",
  "version": "14.2.20015",
  "platform": "darwin",
  "signed_in": true,
  "scopes": ["identity", "staff", "membership.query", "servers.list", "presence.write"]
}

Check product === "mssgs" and api before going further. If none of the four ports answer, mssgs is not running. Just offer your normal experience rather than making the player wait.

Asking permission

Everything except /hello needs a token, and a token only exists after the player approved your game in a dialog inside the app. Ask only for the scopes you actually use: the player sees each one separately, explained, and can untick them individually.

curl -X POST http://127.0.0.1:7440/mssgs/v1/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "com.acme.spacegame",
    "name": "Space Raiders",
    "scopes": ["identity", "membership.query", "presence.write"]
  }'

You get back {"status":"pending","request_id":"…","poll_after_ms":1000} and the player sees the dialog. Then poll until they answer (the request expires after 3 minutes):

curl http://127.0.0.1:7440/mssgs/v1/authorize/<request_id>

# {"status":"approved","token":"…","scopes":["identity","presence.write"],"game_id":"com.acme.spacegame"}

Store the token and send it as Authorization: Bearer <token>. It survives restarts, so a player approves your game once rather than every session. If you later re-authorize with scopes that were already granted, you get the same token straight back with no dialog.

Scopes & privacy

The five scopes give away very different amounts. That is not incidental; it is the whole design. Ask for as little as you can, working down this table.

Checking membership

This is the alternative to "give me the whole list". You name the server_guid of your own community (which you already know) and get an answer about that alone.

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:7440/mssgs/v1/membership?server_guid=ca94ecc…f4g02"

# a member:
# {"server_guid":"ca94ecc…","member":true,"name":"Acme Fans","is_owner":false,
#  "roles":[{"guid":"0aa32…","name":"Pro"}]}

# not a member, and nothing else:
# {"server_guid":"…","member":false}

A "no" is exactly that and nothing more. You may pass up to 10 guids per call (repeat server_guid or comma-separate them), which returns a results array. The @everyone group is never in roles: it is true of every member, so it tells you nothing.

Publishing a playing status

One PUT puts the "Playing …" line under the player's name, everywhere their communities see them.

{
  "name":    "Space Raiders",
  "details": "Sector 7",
  "state":   "In a raid",
  "role":    "Gunner",
  "started_at": 1755859200000,
  "party":   { "size": 3, "max": 4, "kind": "party" },
  "join":    { "secret": "raid-42" }
}

Only name is required. The response tells you how long the status lives and how often to heartbeat:

{ "ok": true, "expires_in_ms": 90000, "heartbeat_every_ms": 30000 }

Player count and role

party.kind decides which sentence is rendered, because the same two numbers do not mean the same thing. A squad of four is not a server with four players on it.

role (up to 48 characters) is what the player is playing as: a job, class or character. It gets its own field rather than another sentence in state, because it is shown as a label beside the player count.

details and state are capped at 128 characters each, name at 64. Line breaks and control characters are stripped. An icon URL is deliberately not supported: it would be fetched by every client that renders the line, which turns a status into a beacon reporting every member of every community the player is in back to your server.

The Join now button

Put a join block in your activity and other members get a Join now button beside the status. There are two ways, and you can combine them.

1. A secret (for native games)

Set {"join":{"secret":"raid-42"}}. When somebody presses Join now, that secret is delivered to their own copy of your game, on their own machine, matched by the same game_id. No URL is opened and no scheme handler is invoked. Your game collects it with:

{
  "events": [
    { "seq": 1, "type": "join", "secret": "raid-42",
      "from": { "user_guid": "62e377…", "username": "mssgs-test-1" } }
  ],
  "cursor": 1
}

Poll with ?since=<cursor> so you see each event once. If the presser's game is not running, nothing is delivered, which is a good reason to also offer a URL.

2. An https URL (for web games and lobby links)

Set {"join":{"url":"https://play.example.com/s/abc"}} and the button opens that link. Only https is accepted. A custom scheme (steam://, mygame://, file://) is refused: that block lands on every member's screen, and such a URL is a way to make somebody else's machine invoke a local handler with arguments you chose.

FiveM

FiveM has no HTTP in its client-side Lua runtime, so a resource talks to the bridge through NUI, a CEF view, which sends an Origin. The bridge accepts those origins explicitly: https://cfx-nui-<resource> and the older nui://<resource>. Ordinary web pages stay refused, and a page on the open web cannot claim that origin; the browser sets it itself.

-- The NUI page does the HTTP; Lua only sends it the data.
CreateThread(function()
  while true do
    SendNUIMessage({
      action  = 'mssgs:publish',
      players = GetActivePlayers and #GetActivePlayers() or 0,
      maxPlayers = GetConvarInt('sv_maxclients', 100),
      job     = exports['qb-core'] and 'Police' or nil
    })
    Wait(30000) -- heartbeat: the status expires after 90s
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // try 7440-7443
let token = null;

async function authorize () {
  const res = await fetch(`${BASE}/authorize`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      game_id: 'fivem.lossantos.rp',
      name: 'Los Santos Roleplay',
      scopes: ['presence.write']          // nothing more is needed here
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // The player now sees the permission dialog in mssgs.
  for (let i = 0; i < 180; i += 1) {
    await new Promise((r) => { setTimeout(r, 1000); });
    const poll = await (await fetch(`${BASE}/authorize/${started.request_id}`)).json();
    if (poll.status === 'approved') { return poll.token; }
    if (poll.status !== 'pending') { return null; }
  }
  return null;
}

window.addEventListener('message', async (event) => {
  if (event.data.action !== 'mssgs:publish') { return; }
  if (!token) { token = await authorize(); }
  if (!token) { return; }

  await fetch(`${BASE}/activity`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
    body: JSON.stringify({
      name: 'FiveM',
      details: 'Los Santos Roleplay',
      role: event.data.job,                       // "Police"
      party: { size: event.data.players, max: event.data.maxPlayers, kind: 'server' },
      join: { url: 'https://cfx.re/join/abc123' } // your cfx.re link
    })
  });
});

The result: Playing FiveM · Los Santos Roleplay · 4/100 players · Police, with a Join now button that opens your cfx.re link.

Browser and phone games: linking through your backend

A game in a browser tab or on a phone cannot reach the bridge above. It runs on the player's desktop, and three walls stand in between: the bridge refuses every request carrying a browser Origin, Chrome puts a permission prompt in front of a public page fetching 127.0.0.1 and Safari refuses outright, and a phone has no path to a desktop's loopback at all.

So the direction flips. Your own backend already knows who is playing, and it tells mssgs, for players who linked their mssgs account to your game. The link is approved in the mssgs app, never in your game, and it creates a link, never a session: nothing below can sign anyone in or act as the player. Your game client never sees a key and never talks to mss.gs. The first game on this path is CozyCity, a city builder that ships as a WebGL page and an iPhone app with no desktop build; the examples below are its own.

1. Register your game

Registration goes through us, not a portal: send us your game_id (for example com.deverence.cozycity), the name and icon the player should see on the approve sheet, and your backend hostnames via the contact page. You get one backend key back, shown once; we keep only a digest. The key belongs on your server and nowhere else. It can be rotated at any time, and the old one stays valid for 24 hours so a deploy can roll.

The name and icon on the sheet always come from the registration, never from the request. Otherwise a phishing link could dress a link request up as any game it liked. The hostnames bound where a join.url may point, see below.

2. Link a player

The player picks Connect mssgs in your game. Your game asks your backend, and your backend asks us:

curl -X POST https://ams1-gateway.mss.gs/game-sdk/v1/link/start \
  -H "Authorization: Bearer $BACKEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "player_ref": "player-8812", "player_name": "René\u2019s city" }'

# {"link_code":"K7PQ2XM4","device_code":"…","qr_url":"https://mss.gs/gl/K7PQ2XM4",
#  "deep_link":"mssgs://link-game/K7PQ2XM4","expires_in":600,"interval":5}

player_ref is your own stable id for that player (up to 128 characters), not for a session or a match; player_name (up to 64) is what the sheet shows as "Player: …". Hand your game client only link_code, qr_url and deep_link. device_code is your polling handle and stays on the server.

Your game then shows three things at once, because the player could be anywhere:

• The QR of qr_url. A phone with mssgs opens it straight into the app's approve sheet. Without the app it lands on a page on mss.gs that shows the code and offers the download.
• An "Open in mssgs" button with deep_link, for a desktop browser sitting next to the desktop app. It is the only external URL your game ever needs to open.
• The code itself, in two groups of four, to type under Settings → Game Activity → Link a game. The alphabet has no 0/O or 1/I, so typing it rarely goes wrong.

What the player sees in mssgs, drawn by the app from the registration:

Meanwhile your backend polls every interval seconds (faster answers 429 SLOW_DOWN) until the status flips. A code works once and expires after ten minutes:

curl -X POST https://ams1-gateway.mss.gs/game-sdk/v1/link/poll \
  -H "Authorization: Bearer $BACKEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "…" }'

# {"status":"pending"}
# {"status":"denied"}      # the player chose Not now
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Store link_guid against your player; from now on it is the address you publish for. The answer carries only the user_guid; a username is added only when your registration holds the identity.link scope, and there is nothing beyond that. A second approval for the same player_ref replaces the earlier link, so one player of your game is one mssgs account. The same mssgs account may link to several games and to several player_refs of one game (a family iPad).

3. Publish the playing status

The same block as on the bridge, with the same rules and the same caps, only now per link and with your backend key:

{
  "activity": {
    "name":       "CozyCity",
    "details":    "Lantern Hollow",
    "state":      "Day 12 · 34 residents",
    "started_at": 1788901000000,
    "party":      { "size": 6, "max": 40, "kind": "server" },
    "join":       { "url": "https://cozycity.net/game/?share=…" }
  }
}

200 {"published":true,"changed":true}     # the block changed and was broadcast
200 {"published":true,"changed":false}    # identical to what was stored; only the TTL was refreshed
204                                        # stored, but the player is not online in mssgs right now
410 {"error":"LINK_REVOKED"}               # the player disconnected: drop the link

Treat 200 and 204 the same: stored. { "activity": null } clears the block, send that when the player leaves. One difference from the bridge: the host of join.url must be one of your registered backends (or a subdomain of one), or you get 400 INVALID_PAYLOAD. So a backend cannot put a Join now button on a player's status that leads somewhere that player never played.

With hundreds of players online, heartbeat in one call, up to 100 items at a time. Each item gets its own status, so one player who disconnected in mssgs never stops the other ninety-nine:

{ "items": [ { "link_guid": "…", "activity": { "name": "CozyCity", "details": "Lantern Hollow" } },
             { "link_guid": "…", "activity": null } ] }

// → 200 { "results": [ { "link_guid": "…", "status": 200, "changed": false },
//                      { "link_guid": "…", "status": 410 } ] }

How the status is shown

• Identical to a bridge status: Playing CozyCity · Lantern Hollow · 6/40 players, with Join now when there is a join.url. The block is stamped via: "backend" server-side, so a client can add "Shared by the game's server".
• Only while the player is online in mssgs. With no mssgs client open, the account is offline and stays offline; your backend cannot make somebody look present. That also stops this route from becoming an "is René at his computer" beacon.
• Precedence: an in-app game > a game on the bridge > your backend. If the player sits down to chess inside mssgs while your backend keeps heartbeating, chess wins, not whoever wrote last.

Disconnecting

The player sees every link under Settings → Game Activity → Linked games, with your icon and name, the player name from your game, when it was linked and when it last published, and a Disconnect button. After that your next publish answers 410 LINK_REVOKED; that is how your game learns. Drop the link_guid and offer "Connect mssgs" again. From your side, end a link with DELETE /game-sdk/v1/links/{link_guid}.

Endpoint reference: the bridge

Base URL http://127.0.0.1:<port>. Everything but the first three requires Authorization: Bearer <token>.

Endpoint reference: linked backends

Base URL https://ams1-gateway.mss.gs. Every route requires Authorization: Bearer <backend key> and the activity.write scope on your registration; answers go out with Cache-Control: no-store. Call these from your server, never from the game client.

Error codes

Errors come back as {"error":"CODE","message":"…"} with a matching HTTP status.

Linked backends

The backend routes use the same shape. Inside a batch the status comes back per item in results, so one ended link never fails the whole call.

Security

Native games only

Requests carrying a web page Origin are refused with 403 ORIGIN_NOT_ALLOWED. Any web page being able to detect that you run mssgs and raise a permission dialog is a fingerprinting and phishing surface, not a feature. A native game sends no Origin at all, so it is unaffected, and a game's own embedded browser is allowed by name, see FiveM. If you are building a browser or phone game, you do not talk to the bridge: your own backend publishes for linked players, see Browser and phone games.

What the player keeps hold of

• The player can switch the bridge off in Settings → Game Activity, after which no game can see mssgs at all.
• Every approved game is listed there with exactly the permissions it holds, when it was last active, and a Remove button. Removing is immediate: the token dies at once.
• A linked browser or phone game is listed under Linked games with a Disconnect button. Disconnecting is immediate too: that backend's next publish gets a 410.
• The bridge listens on 127.0.0.1 only, never on the network.
• Direct messages are never disclosed, not even with servers.list.
• There is a 120-requests-per-minute budget per game.

Being a good citizen

• Ask for scopes when you need them, not all at once on first launch.
• Work without mssgs: the player does not have to have it.
• Clear your status when play stops rather than waiting for the TTL.
• Treat a refused scope as a normal outcome, not an error.