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.

Endpoint reference

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

Error codes

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

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 game, bring players in through a join.url rather than talking to the bridge directly.

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.
• 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.