NEOLearn

Friends, groups and invites in your game

Read a player's friends and who is playing, check group ranks, invite friends and keep parties together from your game's server; connect a group to your tools with webhooks and API keys.

Updated October 21, 2026

On this page

Your game can use what players already have on NEO: their friends, their groups and their party. A game asks through the platform's game-facing API, GameRuntimeService, with one of two credentials:

  • a server key: your game's own server (a backend, a dedicated server). Create one under Configurations → Secrets in the game's management area. It's shown once. A server key asks about any player who's in one of your game's sessions right now;
  • the game token a player's device gets when it joins: it asks about that player, and the session's host asks about players in its session.

Calls go to https://<api>/neo.platform.v1.GameRuntimeService/<Method> as JSON, with Authorization: Bearer <key or token>. Ids are the ones the platform hands out (usr_…, grp_…).

What a game can ask#

CallRequestAnswers
GetFriendsplayerIdThe player's friends, each with inThisSession (in the session the token is for; with a server key, any of your sessions) and inThisGame. Friends who hide their online status are never shown as playing.
IsFriendsWithplayerId, userIdfriends: true or false.
GetGroupRankplayerId, groupIdmember, rank (1 to 255) and role: gate an admin tool, pick a team colour, open a VIP area.
SendGameInviteplayerId, userIdInvites a friend of the player to the player's session, as the player. The friend gets the same invite as from the app.
GetPartyplayerIdThe player's party (partyId, leader, members), or nothing.

Invites follow the same rules as invites from the app: friends only, nobody who blocked the player or whom they blocked, the host's Who can join setting, and at most 10 invites in 10 minutes per player. Only invite when the player asked to (an "Invite friends" button in your game): NEO doesn't allow invites a player didn't choose.

Example: invite the friends who aren't here#

A script on your game's server, in JavaScript:

invite-friends.js
const API = "https://api.neoengine.io";
const SERVER_KEY = process.env.NEO_SERVER_KEY; // a server key, kept out of your code

async function call(method, body) {
  const res = await fetch(`${API}/neo.platform.v1.GameRuntimeService/${method}`, {
    method: "POST",
    headers: { "content-type": "application/json", authorization: `Bearer ${SERVER_KEY}` },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`${method}: ${res.status} ${await res.text()}`);
  return res.json();
}

// the player pressed "Invite friends" in the game
export async function inviteFriendsWhoArentHere(playerId) {
  const { friends = [] } = await call("GetFriends", { playerId });
  for (const f of friends.filter((f) => !f.inThisSession)) {
    await call("SendGameInvite", { playerId, userId: f.user.id });
  }
}

Groups: webhooks and API keys#

A group's owner connects the group to their own tools in the group's Developers tab.

Webhooks are called when someone joins or leaves the group, a rank changes, someone posts on the wall, or an announcement goes out. Each call is a JSON POST with the event's type, the group, who did it, and what changed. It's signed the same way as game webhooks: check NEO-Signature: t=<time>,v1=<signature>, where the signature is HMAC-SHA256 of <time>.<body> with the webhook's signing secret (shown once). Failed calls are retried for an hour. Send a test event checks your endpoint.

API keys let your own tools (a Discord bot, a ranking center) work with the group through GroupCloudService, with Authorization: Bearer neogk_…. Each key has only the permissions you gave it:

PermissionCalls
Read members (members.read)ListMembers (highest rank first, paged with pageToken), GetMember
Change ranks (members.rank)SetMemberRank: as you, and only to and from ranks below yours. The group's audit log says it was done with an API key.
Read the audit log (audit.read)ListAuditLog

A key stops working when you revoke it, and its rank changes stop working if you leave the group or lose the permission to manage ranks. Keys are shown once, so keep them in your tool's secret settings, never in a page or a game.