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
/api/v1/friendsReturns 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.
{
"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:
/api/v1/presence| Name | Type | Description |
|---|---|---|
status | string | Default in_game. Also online, away, dnd. |
details | string ≤ 128 | What the player is doing, e.g. “Ranked”. |
state | string ≤ 128 | Extra detail, e.g. “Round 3” or “Map: Harbor”. |
partyId | string ≤ 128 | Your lobby / party id. Shown only to friends in your game. |
partySize, partyMax | integer 0–1000 | Current and maximum party size. |
joinable | boolean | Whether friends may ask to join. |
startedAt | unix seconds or ISO date | When the match or session started (for “for 12 min”). |
Who sees what
| Viewer | Sees |
|---|---|
| A friend, in your game | Status, game name, details, state, start time, party and joinable. |
| A friend, in another app | Status, your game's name, details, state and start time. No party or join information. |
| Anyone who is not a friend | Always offline. |
To read the presence of specific friends without the whole list:
/api/v1/presence?ids=<id>,<id>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.
/api/v1/invites{ "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.
/api/v1/invites/respond{ "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:
/api/v1/events?after=<cursor>| Type | data |
|---|---|
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.