Presence relay

The UDP presence relay keeps users online, updates their current game presence, and tells clients when presence notifications are ready to pull over HTTP.

Relay address

The UDP server binds to UDP_PORT and defaults to port 8081.

Production

prod.bluesphere.live:8081

Call POST /api/loginAuth first and use the returned udpToken in every heartbeat packet.

Heartbeat packet

Send a UTF-8 JSON datagram every 2 seconds while the client should appear online.

UDP

heartbeat

{
  "type": "heartbeat",
  "udpToken": "64_character_hex_udp_token",
  "game": "Grand Theft Auto V 1.53"
}

Name
type
Type
string
Description
Must be heartbeat. Other packet types are ignored by the current relay.
Name
udpToken
Type
string
Description
UDP session token returned by POST /api/loginAuth. The relay uses this token to look up the user.
Name
game
Type
string
Description
Current game name. Known values such as Grand Theft Auto V 1.52 and Grand Theft Auto V 1.53 are mapped to PS4 title metadata. Unknown values are stored with titleId: "unknown".

Relay responses

The first accepted heartbeat can update presence without returning a response. After the user is cached, the relay returns one of these JSON datagrams.

Heartbeat acknowledged

{
  "type": "heartbeat_ack",
  "timestamp": "2026-05-03T20:00:00.000Z"
}

Notifications available

{
  "type": "notificationsAvailable"
}

Invalid token or packet

{
  "type": "error",
  "message": "Error."
}

When notificationsAvailable is received, call the notification pull endpoint with the user's authCode.

GET

/api/:accountId/checkNotifications

curl https://prod.bluesphere.live/api/123456/checkNotifications \
  -H "Authorization: Bearer base64url_signed_auth_code"

Presence lifecycle

On a valid heartbeat, the relay marks the user online, updates currentGame, currentGameTitle, currentGameVersion, and gameStatus, then creates presence notifications for online friends.

If no heartbeat is received for 30 seconds, the relay removes the user from its in-memory cache, marks the user offline, and creates offline status notifications for online friends.

Notification payloads

Presence notifications use the presence service name. Online/offline and game updates are queued for friends and delivered through GET /api/:accountId/checkNotifications.

Name
np:service:friendlist:friend
Type
dataType
Description
Friend online or offline status changed.
Name
np:service:friendlist:friendOnline
Type
dataType
Description
Friend game presence changed. The notification payload contains the current game string.