Friends, presence and invites

The REAN Social API gives your game the player's friends, who is online, what they are doing and a way to invite them into a match.

Friends

GET/api/v1/friendsscope friends.read

Returns the player's accepted REAN friends, sorted by display name. Pending requests are never included, and suspended or deleted accounts are left out. With presence.read each friend also carries a presence object.

json
{
  "friends": [
    {
      "id": "8e2d…",
      "username": "kai",
      "displayName": "Kai",
      "avatarUrl": "https://…/kai.png",
      "friendsSince": "2026-08-02T18:11:04Z",
      "presence": {
        "status": "in_game",
        "activity": {
          "app": { "clientId": "rean_…", "name": "Your Game", "iconUrl": null },
          "details": "Ranked",
          "state": "Round 3",
          "startedAt": "2026-11-22T20:15:00Z",
          "party": { "id": "lobby-7", "size": 2, "max": 5 },
          "joinable": true
        }
      }
    }
  ]
}

Presence and rich presence

A player's status is one of online, away, dnd, in_game or offline. While your game runs, report what the player is doing:

POST/api/v1/presencescope presence.write
NameTypeDescription
statusstringDefault in_game. Also online, away, dnd.
detailsstring ≤ 128What the player is doing, e.g. “Ranked”.
statestring ≤ 128Extra detail, e.g. “Round 3” or “Map: Harbor”.
partyIdstring ≤ 128Your lobby / party id. Shown only to friends in your game.
partySize, partyMaxinteger 0–1000Current and maximum party size.
joinablebooleanWhether friends may ask to join.
startedAtunix seconds or ISO dateWhen the match or session started (for “for 12 min”).

Who sees what

ViewerSees
A friend, in your gameStatus, game name, details, state, start time, party and joinable.
A friend, in another appStatus, your game's name, details, state and start time. No party or join information.
Anyone who is not a friendAlways offline.

To read the presence of specific friends without the whole list:

GET/api/v1/presence?ids=<id>,<id>scope presence.read

Game invites

Invites go between friends, inside one app. The joinSecret is whatever your game needs to join: a lobby id, a server address and ticket, a matchmaking token.

POST/api/v1/invitesscope invites
json
{ "to": "8e2d…", "joinSecret": "lobby:7f3a:ticket:93b1", "message": "Ranked? 🎮" }
  • Only to accepted friends (otherwise 403 not_friends).
  • Invites expire after 10 minutes. A player can send up to 30 every 10 minutes.
  • The join secret is only given to the invited friend, in your app. Treat it as a short-lived ticket, not a permanent password.
POST/api/v1/invites/respondscope invites
json
{ "id": "c51e…", "accept": true }   →   { "ok": true, "joinSecret": "lobby:7f3a:ticket:93b1" }

Events

Your game learns about new invites and answers from the event feed of the signed-in player, in your app:

GET/api/v1/events?after=<cursor>
Typedata
invite.received{ id, from, message, joinSecret, createdAt, expiresAt }
invite.accepted{ id, by }
invite.declined{ id, by }

Poll every 10–15 seconds and pass back the cursor you received. Events are kept for 7 days. The SDKs poll for you while you listen for events.