Lobby and WebSockets

Last updated on October 24, 2024

Overview

The AccelByte Gaming Services (AGS) WebSocket messaging protocol is a simple messaging protocol focusing on fast object-message conversion on the server side and simplicity on the client side. This protocol is a subset of the YAML data serialization language.

Basic structure

The structure supported by this protocol is a string key-value object. The keys and the values are separated by a colon followed by a white space. Objects are separated by newlines.

keyA: [valueA1	valueA2	valueAn	]\n
keyB: [valueB1	valueB2	valueBn	]

Each message must come with a type object defining the message type.

type:	messageType\n
keyA:	valueA\n
keyB:	[valueB1,valueB2,valueBn,]

Date-time-based values must be represented by date time ISO-8601 up to the second field.

type:	messageType\n
keyA:	valueA\n
keyB:	[valueB1,valueB2,valueBn,]\n
time:	2018-11-09T03:51:18Z

Message types

There are three types of messages in the Lobby server implementation.

Request

A request message is a message from a client to a server. The request message type should have a "-Request" suffix. A request message must have an object ID generated by the client and the object ID must be placed after the object type. Each request must be responded to by the server with the same object ID. The object type must be at the top of any object.

type:	fooRequest\n
id:	`878a0f51bedd4825cf46827fd1478224\n`
keyA:	valueA\n
keyB:	[valueB1,valueB2,valueBn,]

Response

A response message is a message from a server to a client corresponding to a client's request. A response message type should have a "-Response" suffix, and the response object ID must correspond with the request. Responses must have an object code identifying a response code. Successful requests must be responded to with status 0. Unsuccessful requests must be responded to with a non-0 status code--preferably, an error event ID. When the code is non-0, the other field should be ignored.

type:	fooResponse\n
id:	`878a0f51bedd4825cf46827fd1478224\n`
code:	0\n
keyA:	valueA\n
keyB:	[valueB1,valueB2,valueBn,]

Notification

A notification is a message sent from the server to a client without a user request. The notification message type should have a "-Notif" suffix.

type:	fooNotif\n
keyA:	valueA\n
keyB:	[valueB1,valueB2,valueBn,]

note

Currently, there is a known issue on PlayStation where the Lobby WebSocket connection will close ungracefully after the following occurs:

A player opens a game on PlayStation and connects to the AccelByte Lobby WebSocket.
The player goes to the PlayStation home screen and opens another game.

The Lobby WebSocket will be disconnected and the AGS backend will log the disconnection with the 3121 close code.

{
  "Code": "3121",
  "CodeName": "DisconnectReaderUnexpectedEOF",
  "Text": "Disconnect WS due to server-side unexpected EOF",
  "Attributes": [],
  "Section": "disconnect with reconnect (reader)",
  "Service": "lobby disconnect (with reconnect)"
 }

Lobby server usage

Friends

Command	Request Payload	Async Response Payload	Unreal	Unity
Request Friend	type: requestFriendsRequest\n id: message123\n friendId: user123	type: requestFriendsResponse\n id: message123\n code: 0	Lobby::RequestFriend(FString UserId)	RequestFriend(string userId, ResultCallback callback)
Request Friends By PublicID	type: RequestFriendsByPublicID\n		Lobby::RequestFriendByPublicId(FString PublicId)	RequestFriendByPublicId(string publicId, ResultCallback callback)
Friend request notification		type: requestFriendsNotif\n friendId: user123	SetOnIncomingRequestFriendsNotifDelegate(const FRequestFriendsNotif& OnRequestFriendsNotif)	OnIncomingFriendRequest
Unfriend	type: unfriendRequest\n id: message123\n friendId: user123	type: unfriendResponse\n id: message123\n code: 0	Lobby::Unfriend(FString UserId)	Unfriend(string userId, ResultCallback callback)
List of Friends Request V2	type: ListFriendsRequestV2\n id: message123		N/A	N/A
List outgoing friend request	type: listOutgoingFriendsRequest\n id: message123	type: listOutgoingFriendsResponse\n id: message123\n code: 0\n friendsId: [user123,user456,]\n	Lobby::ListOutgoingFriends()	ListOutgoingFriends(`ResultCallback<Friends>` callback)
Cancel outgoing friend request	type: cancelFriendsRequest\n id: message123\n friendId: user123	type: cancelFriendsResponse\n id: message123\n code: 0	Lobby::CancelFriendRequest(FString UserId)	CancelFriendRequest(string userId, ResultCallback callback)
List incoming friend request	type: listIncomingFriendsRequest\n id: message123	type: listIncomingFriendsResponse\n id: message123\n code: 0\n friendsId: [user123,user456,]	Lobby::ListIncomingFriends()	ListIncomingFriends(`ResultCallback<Friends>` callback)
List Incoming Friends With Time	type: ListIncomingFriendsWithTimet\n		Lobby::ListIncomingFriendsWithTime()	ListIncomingFriendsWithTime(`ResultCallback<FriendsWithTimestamp>` callback)
List Outgoing Friends With Time	type: ListOutgoingFriendsWithTimet\n		Lobby::ListOutgoingFriendsWithTime()	ListOutgoingFriendsWithTime(`ResultCallback<FriendsWithTimestamp>` callback)
Accept incoming friend request	type: acceptFriendsRequest\n id: message123\n friendId: user123	type: acceptFriendsResponse\n id: message123\n code: 0	Lobby::AcceptFriend(FString UserId)	AcceptFriend(string userId, ResultCallback callback)
Friends acceptance notification		type: acceptFriendsNotif\n friendId: user123	SetOnFriendRequestAcceptedNotifDelegate(const FAcceptFriendsNotif& OnAcceptFriendsNotif)	FriendRequestAccepted
Reject incoming friend request	type: rejectFriendsRequest\n id: message123\n friendId: user123	type: rejectFriendsResponse\n id: message123\n code: 0	Lobby::RejectFriend(FString UserId)	RejectFriend(string userId, ResultCallback callback)
List current friends	type: listOfFriendsRequest\n id: message123	type: listOfFriendsResponse\n id: message123\n code: 0\n friendsId: [user123,user456,]	Lobby::LoadFriendsList()	`LoadFriendsList(ResultCallback<Friends>` callback)
Get friendship status	type: getFriendshipStatusRequest\n id: message123\n friendId: user123	type: getFriendshipStatusResponse id: message123 code: 0 friendshipStatus: 3	Lobby::GetFriendshipStatus(FString UserId)	GetFriendshipStatus(string userId, `ResultCallback<FriendshipStatus>` callback)
Unfriend notif		type: unfriendNotif\n friendId: user123	SetOnUnfriendNotifDelegate(const FUnfriendNotif& OnUnfriendNotif)	OnUnfriend
Cancel friend notif		type: cancelFriendsNotif\n userId: user123	SetOnCancelFriendsNotifDelegate(const FCancelFriendsNotif& OnCancelFriendsNotif)	FriendRequestCanceled
Reject friend notif		type: rejectFriendsNotif\n userId: user123	SetOnRejectFriendsNotifDelegate(const FRejectFriendsNotif& OnRejectFriendsNotif)	FriendRequestRejected

Presence

Command	Request Payload	Async Response Payload	Unreal	Unity	OSS
Set user status	type: setUserStatusRequest\n id: message123\n availability: 1\n activity: in party looking for members	type: setUserStatusResponse\n id: message123\n code: 0	Lobby::SendSetPresenceStatus(const EAvailability Availability , const FString& Activity)	SetUserStatus(UserStatus status, string activity, ResultCallback callback)	void FOnlinePresenceAccelByte::SetPresence(const FUniqueNetId& User, const FOnlineUserPresenceStatus& Status, const FOnPresenceTaskCompleteDelegate& Delegate)
Set user status v2	type: setUserStatusRequestv2\n		N/A	N/A
Notify status		type: userStatusNotif\n userID: 123\n availability: 1\n activity: idle	SetUserPresenceNotifDelegate(FFriendStatusNotif OnUserPresenceNotif)	FriendsStatusChanged	OnPresenceReceived
List all friends presence	type: friendsStatusRequest\n id: message123	type: friendsStatusResponse\n id: message123\n code: 0\n friendsId: [uid1,uid2,uid3,]\n availability: [1,2,1,]\n activity: [playing mahjong ultra,null,in deathmatch shooter game,]\n lastSeenAt: [2018-09-30T06:42:57Z,2018-11-30T06:42:57Z,2018-10-21T06:42:57Z,]	Lobby::SendGetOnlineFriendPresenceRequest()	ListFriendsStatus(`ResultCallback<FriendsStatus>` callback)	N/A

Block Player

Command	Request Payload	Async Response Payload	Unreal	Unity
Block player	type: blockPlayerRequest\n id: message123\n userId: user123\n blockedUserId: user456\n namespace: sdktest	type: blockPlayerResponse\n id: message123\n code: 0\n namespace: ns\n blockedUserId: user123	Lobby::BlockPlayer(const FString& UserId)	BlockPlayer(string userId, `ResultCallback<BlockPlayerResponse>` callback)
Get Blocked Player	type: GetBlockedPlayer\n		*used REST API	*used REST API
Block player notif		type: blockPlayerNotif userId: user123\n blockedUserId: user456\n	SetBlockPlayerNotifDelegate(FBlockPlayerNotif OnBlockPlayerNotif)	PlayerBlockedNotif
Unblock player	type: unblockPlayerRequest\n id: message123\n userId: user123\n unblockedUserId: user456\n namespace: ns	type: unblockPlayerResponse\n id: friends-5358\n code: 0\n namespace: ns\n unblockedUserId: user456\n	Lobby::UnblockPlayer(const FString& UserId)	UnblockPlayer(string userId, `ResultCallback<UnblockPlayerResponse>` callback)
Unblock player notif		type: unblockPlayerNotif userId: user123\n unblockedUserId: user456\n	SetUnblockPlayerNotifDelegate(FUnblockPlayerNotif OnUnblockPlayerNotif)	PlayerUnblockedNotif

Notifications

Being sent notification		type: messageNotif\n subject: updateNotification\n from: system\n to: user123\n topic: 1111\n payload: message content 123\n sentAt: 2018-11-25T23:45:05Z	SetMessageNotifDelegate(const FMessageNotif& OnNotificationMessage)	OnNotification	Used only to print log internally
Sent ban notification		type: userBannedNotification\n id: message123\n code: 12002\n userId: user123\n ban: BAN-TYPE\n reason: BAN-REASON\n endDate: 2022-05-11 16:21:36.688 +0000 UTC\n enable: true	SetUserBannedNotificationDelegate(FUserBannedNotification OnUserBannedNotification)	UserBannedNotification	N/A
Sent unban notification		type: userUnbannedNotification\n id: message123\n code: 12002\n userId: user123\n ban: BAN-TYPE\n reason: BAN-REASON\n endDate: 2022-05-11 16:21:36.688 +0000 UTC\n enable: false	SetUserUnbannedNotificationDelegate(FUserUnbannedNotification OnUserUnbannedNotification)	UserUnbannedNotification	N/A

Signaling P2P

Command	Request Payload	Async Response Payload	Unreal	Unity	OSS
Send Signaling	type: signalingP2PNotif\n id: message123\n destinationId: user123\n message: message123	type: signalingP2PNotif\n id: message123\n destinationId: user123\n message: message123	Lobby::SendSignalingMessage(const FString& UserId, const FString& Message)	SendSignalingMessage(string userId, string message)	N/A

Refresh token

Command	Request Payload	Async Response Payload	Unreal	Unity
Refresh Token	type: refreshTokenRequest\n id: message123\n token: token123	type: refreshTokenResponse\n id: message123\n code: 0	Lobby::RefreshToken(const FString& AccessToken)	RefreshToken( string newAccessToken, ResultCallback callback )

Error Notifications

Command	Request Payload	Async Response Payload	Unreal	Unity
Error Notif		type: errorNotif\n code: 429\n message: message123	SetErrorNotifDelegate(FErrorNotif OnErrorNotif)	ErrorNotification

Lobby and WebSockets

Overview

Basic structure

Message types

Request

Response

Notification

Lobby server usage

Friends

Presence

Block Player

Notifications

Signaling P2P

Refresh token

Error Notifications

More Topic

On this page

Overview​

Basic structure​

Message types​

Request​

Response​

Notification​

Lobby server usage​

Friends​

Presence​

Block Player​

Notifications​

Signaling P2P​

Refresh token​

Error Notifications​

More Topic​

On this page

Overview

Basic structure

Message types

Request

Response

Notification

Lobby server usage

Friends

Presence

Block Player

Notifications

Signaling P2P

Refresh token

Error Notifications

More Topic