Game server notifications
Overview
AccelByte Gaming Services (AGS) Play's game server notification system quickly delivers relevant information to the game server. It uses the WebSocket messaging protocol from DS Hub to send multiplayer notifications from the backend to the server.
This article contains a list of game server notifications the system provides.
DS Hub notifications
The following sections pertain to DS Hub notifications.
Prerequisites
To connect to DS Hub, you need:
- A game server deployed through AccelByte Multiplayer Servers (AMS)
- DS Hub credentials (automatically provided during server deployment)
- Server ID (obtained during game server claiming)
Connection Flow
- Initialize the DS Hub client using the SDK
- Configure connection settings with provided credentials
- Establish WebSocket connection
- Handle connection events (connected/disconnected)
- Set up notification listeners
For detailed implementation steps, see Configure DS Hub with the SDK.
DSHUB_CONNECTED
When your server successfully establishes a WebSocket connection to DS Hub, the first notification you will receive is DSHUB_CONNECTED. This message confirms that:
- The connection is active and authenticated
- The WebSocket session is ready to receive notifications
- A unique connection ID has been assigned
{
"MessageID": "",
"Code": 200,
"topic": "DSHUB_CONNECTED",
"payload": {
"connectionId": "f8598b33afaf4490adfae2e1049eda90"
}
}
Basic structure
Multiplayer notifications system for game servers uses direct JSON format.
Matchmaking notifications
The following sections pertain to matchmaking notifications.
BACKFILL_PROPOSAL
AGS Matchmaking will send the BACKFILL_PROPOSAL notification to the game server via DS Hub when there is a match proposal that needs to be manually accepted or rejected partially by the server.
{
"namespace": "sanitytest",
"topic": "BACKFILL_PROPOSAL",
"payload": {
"AddedTickets": [
{
"CreatedAt": "2024-10-10T02:01:30.445Z",
"ExcludedSessions": null,
"IsActive": true,
"IsPivot": false,
"IsSinglePlay": false,
"Latencies": {
"us-east-1": 10
},
"MatchPool": "testtestMatchPool-OPEN-AutoBackFill-01J9T2HD6WG1A1HS15XSMF6057",
"MatchedAt": "0001-01-01T00:00:00Z",
"Namespace": "sanitytest",
"PartySessionID": "",
"Players": [
{
"Attributes": null,
"PartyID": "",
"PlatformID": "",
"PlayerID": "db47c7bdf5f74bea832526cf89862d74"
}
],
"ProposedProposal": {
"BackfillID": "",
"ProposalID": "",
"Status": ""
},
"TicketAttributes": null,
"TicketID": "7b10a13345d74b2c99d67acd11851780",
"TicketInformation": {
"CrossPlatforms": null,
"CrossPlayEnabled": false
}
}
],
"Attribute": {
"member_attributes": {}
},
"BackfillTicketID": "0b1d36362c0b43afa3c132cba07e6d7d",
"CreatedAt": "2024-10-10T02:01:31.793444607Z",
"MatchPool": "testtestMatchPool-OPEN-AutoBackFill-01J9T2HD6WG1A1HS15XSMF6057",
"MatchSessionID": "d1ebfd60e42b4c42b366c703612dbbef",
"ProposalID": "f46e1474c4c34f6fb8123cfd2e407bfc",
"ProposedTeams": [
{
"Parties": [
{
"userIDs": [
"1a671fdb53564f6780ef88f0114caed2"
]
},
{
"userIDs": [
"ab72d9886df5470f938aba71c9f7d2a8"
]
},
{
"userIDs": [
"7202e94cad0b4a11ab484e108f66f353"
]
},
{
"userIDs": [
"db47c7bdf5f74bea832526cf89862d74"
]
}
],
"UserIDs": [
"1a671fdb53564f6780ef88f0114caed2",
"ab72d9886df5470f938aba71c9f7d2a8",
"7202e94cad0b4a11ab484e108f66f353",
"db47c7bdf5f74bea832526cf89862d74"
]
}
]
},
"traceContext": {
"b3": "9982475df57acc8f052c1398f374c4d2-4c3157f5c0b3e27f-1",
"traceparent": "00-9982475df57acc8f052c1398f374c4d2-4c3157f5c0b3e27f-01"
},
"timestamp": "2024-10-10T02:01:31.800675505Z"
}
BACKFILL_TICKET_EXPIRE
AGS Matchmaking will send the BACKFILL_TICKET_EXPIRE notification to the game server via DS Hub when the backfill ticket that is being assigned to the active session has expired.
{
"namespace": "sanitytest",
"topic": "BACKFILL_TICKET_EXPIRE",
"payload": {
"TicketID": "0b1d36362c0b43afa3c132cba07e6d7d"
},
"traceContext": {
"b3": "217b643d494d6238572f14823154d1f9-83e43b6fc577cb32-1",
"traceparent": "00-217b643d494d6238572f14823154d1f9-83e43b6fc577cb32-01"
},
"timestamp": "2024-10-10T02:01:32.657730245Z"
}
Session notifications
The following sections pertain to session notifications.
serverClaimed
AGS Session will send the serverClaimed notification to the server when it is being assigned to a session. This notification is only for the AccelByte Multiplayer Servers (AMS) add-on dedicated servers.
{
"namespace": "sanitytest",
"topic": "serverClaimed",
"payload": {
"game_mode": "testtestMatchPool-OPEN-AutoBackFill-01J9T2HD6WG1A1HS15XSMF6057",
"namespace": "sanitytest",
"session_id": "d1ebfd60e42b4c42b366c703612dbbef"
},
"traceContext": {
"b3": "5ee9219f4ad83fcaf11f0816ad309318-61dbc0a1f1bb8df2-1",
"traceparent": "00-5ee9219f4ad83fcaf11f0816ad309318-61dbc0a1f1bb8df2-01"
},
"timestamp": "2024-10-10T02:01:21.243100897Z"
}
SESSION_MEMBER_CHANGED
AGS Session will send the SESSION_MEMBER_CHANGED notification to the server when there is an update to the game session member status.
{
"namespace": "sanitytest",
"topic": "SESSION_MEMBER_CHANGED",
"payload": {
"Attributes": {
"member_attributes": {}
},
"BackfillTicketID": "0b1d36362c0b43afa3c132cba07e6d7d",
"Code": "WJVVTR",
"Configuration": {
"AutoJoin": true,
"InactiveTimeout": 300,
"InviteTimeout": 300,
"Joinability": "OPEN",
"MaxPlayers": 4,
"MinPlayers": 1,
"Name": "testtestSessionTemplateAMSOpen-01J9T2HD6WG1A1HS15Y14J55HK",
"RequestedRegions": [
"us-east-1"
],
"Type": "DS",
"enableSecret": false
},
"ConfigurationName": "testtestSessionTemplateAMSOpen-01J9T2HD6WG1A1HS15Y14J55HK",
"CreatedAt": "2024-10-10T02:01:21Z",
"CreatedBy": "client-5edadc7e0ba147eab1022d57a1656638",
"DSInformation": {
"RequestedAt": "2024-10-10T02:01:21.024Z",
"Server": {
"ams_protocol": [
{
"name": "default",
"protocol": "UDP"
}
],
"custom_attribute": "ttx1.s",
"deployment": "sanity_fleet",
"game_version": "",
"image_version": "img_01903977-bfb0-7b4e-9fdb-184a22b57bc2",
"ip": "192.192.192.192",
"is_override_game_version": false,
"last_update": "2024-10-10T02:01:21Z",
"namespace": "sanitytest",
"pod_name": "ds_01927425-ff7e-72da-a858-c0ed60ac42ad",
"port": 22222,
"ports": {
"default": 22222
},
"protocol": "UDP",
"provider": "AMS",
"region": "us-east-1",
"session_id": "d1ebfd60e42b4c42b366c703612dbbef",
"source": "AMS",
"status": "READY"
},
"Status": "AVAILABLE",
"StatusV2": "AVAILABLE"
},
"GameMode": "testtestMatchPool-OPEN-AutoBackFill-01J9T2HD6WG1A1HS15XSMF6057",
"ID": "d1ebfd60e42b4c42b366c703612dbbef",
"IsFull": true,
"LeaderID": "1a671fdb53564f6780ef88f0114caed2",
"MatchPool": "testtestMatchPool-OPEN-AutoBackFill-01J9T2HD6WG1A1HS15XSMF6057",
"Members": [
{
"ID": "1a671fdb53564f6780ef88f0114caed2",
"Status": "JOINED",
"StatusV2": "JOINED",
"UpdatedAt": "2024-10-10T02:01:21Z"
},
{
"ID": "ab72d9886df5470f938aba71c9f7d2a8",
"Status": "JOINED",
"StatusV2": "JOINED",
"UpdatedAt": "2024-10-10T02:01:21Z"
},
{
"ID": "7202e94cad0b4a11ab484e108f66f353",
"Status": "JOINED",
"StatusV2": "JOINED",
"UpdatedAt": "2024-10-10T02:01:21Z"
},
{
"ID": "db47c7bdf5f74bea832526cf89862d74",
"Status": "INVITED",
"StatusV2": "INVITED",
"UpdatedAt": "2024-10-10T02:01:32.343Z"
}
],
"Namespace": "sanitytest",
"Teams": [
{
"parties": [
{
"partyID": "",
"userIDs": [
"1a671fdb53564f6780ef88f0114caed2"
]
},
{
"partyID": "",
"userIDs": [
"ab72d9886df5470f938aba71c9f7d2a8"
]
},
{
"partyID": "",
"userIDs": [
"7202e94cad0b4a11ab484e108f66f353"
]
},
{
"partyID": "",
"userIDs": [
"db47c7bdf5f74bea832526cf89862d74"
]
}
],
"userIDs": [
"1a671fdb53564f6780ef88f0114caed2",
"ab72d9886df5470f938aba71c9f7d2a8",
"7202e94cad0b4a11ab484e108f66f353",
"db47c7bdf5f74bea832526cf89862d74"
]
}
],
"UpdatedAt": "2024-10-10T02:01:32.345Z",
"Version": 3
},
"traceContext": {
"b3": "217b643d494d6238572f14823154d1f9-c1aec25b8c1564f0-1",
"traceparent": "00-217b643d494d6238572f14823154d1f9-c1aec25b8c1564f0-01"
},
"timestamp": "2024-10-10T02:01:32.379068307Z"
}
SESSION_ENDED_NOTIF
AGS Session will send the SESSION_ENDED_NOTIF notification to the server when the game session has ended.
{
"namespace": "sanitytest",
"topic": "SESSION_ENDED_NOTIF",
"payload": {
"is_active": false,
"session_id": "b007745748d844d0afbf1a0cfb93a121"
},
"traceContext": {
"b3": "bbbc419a4909637f4b743cda290e1f78-60ee030a7819530d-1",
"traceparent": "00-bbbc419a4909637f4b743cda290e1f78-60ee030a7819530d-01"
},
"timestamp": "2024-10-10T01:20:45.872179433Z"
}
SESSION_SERVER_SECRET
AGS Session will send the SESSION_SERVER_SECRET notification to the server when the secret is being enabled on the game session template.
{
"namespace": "sanitytest",
"topic": "SESSION_SERVER_SECRET",
"payload": {
"secret": "3gB0swvrKZV4K4kvdfV4Dnkv3fnOXppr"
},
"traceContext": {
"b3": "01793f8e1dab64d7ee3d29714364150c-d2fb4855c1a0de87-1",
"traceparent": "00-01793f8e1dab64d7ee3d29714364150c-d2fb4855c1a0de87-01"
},
"timestamp": "2024-10-10T04:21:39.839853986Z"
}
DS Hub notifications
The following sections pertain to DS Hub notifications.
DSHUB_CONNECTED
When your server successfully establishes a WebSocket connection to DS Hub, the first notification you will receive is DSHUB_CONNECTED. This message confirms that the connection is active and ready to receive further notifications.
DS Hub will send the DSHUB_CONNECTED notification when the server has successfully connected with the DS Hub WebSocket.
{
"MessageID": "",
"Code": 200,
"topic": "DSHUB_CONNECTED",
"payload": {
"connectionId": "f8598b33afaf4490adfae2e1049eda90"
}
}
Custom notifications
An admin or service can send a custom notification to the server using this endpoint with the format below:
{
"payload": "string",
"timestamp": "2024-10-14T03:42:54.387Z", // the current timestamp in RFC3339 format
"topic": "string"
}