WebSockets API offers access to idem matchmaking reducing latency compared to the REST API.
Authentication for this API is works via a authorization query string parameter in the connection url.
The token retrieval process is described in the servers section.
The response contains an IdToken in the AuthenticationResult.
This token needs to be provided in the authorization query string parameter of the websocket connection url.
The API uses JSON messages for communication. Each message contains an action field and a payload field. The action field specifies the type of message, while the payload field contains the data necessary to perform the action. You can specify an optional messageId field to track messages. The server will echo the messageId in the response message. The messageId can be used to correlate requests and responses.
Each message will trigger a response message from the server. The response message will contain the same messageId as the request message. The response message will contain an action field that specifies the type of response and a payload field that contains the response data.
Example request message:
{
"action": "addPlayer",
"messageId": "nfasooa73zga9p3ja",
"payload":
{
"gameId": "1v1",
"partyName": "player_1_1276543",
...
}
}
Remark: Please design your websocket client to be compatible with additional fields in the response messages.
In case of an error, the server will send an error message. The error message contains an error code and a message field. The error code is an integer that specifies the type of error. The message field contains a human-readable error message.
To avoid connection timeouts, the server sends a keep alive message every minute. The keep alive message has an empty payload.
We recommend to use a push approach for receiving match suggestions. Push allows a websocket to receive match suggestions without having to request them. Instead, they will be pushed through the websocket once a match has been found. To register a websocket for push messages, there are two options:
At connection time, you can provide the following query string parameters to the connection url:
wss://ws.int.idem.gg/?receiveMatches=true&gameMode=1v1,2v2,3v3&authorization=eyJraWQi(...)Las-AAW9w
Alternatively, you can use the subscribe action to register for match suggestions after the connection
has been established. To unsubscribe, use the unsubscribe action.
{
"action": "subscribe",
"payload":
{
"gameIds": ["1v1", "2v2", "3v3"],
}
}
System for integration testing of new features.
Authentication for this API is works via a authorization query string parameter in the connection url.
To retrieve a token, send a POST request to - Host: https://cognito-idp.eu-central-1.amazonaws.com/ - Headers:
X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuthContent-Type: application/x-amz-json-1.1{"AuthParameters":{"USERNAME": "<your username>","PASSWORD":"<your-password>"}, "AuthFlow":"USER_PASSWORD_AUTH","ClientId":"1do8hesp16ocufpjd33ahibrmo"}The response contains an IdToken in the AuthenticationResult. This token needs to be provided in the authorization query string parameter of the websocket connection url.
Example:
wss://ws.int.idem.gg/?authorization=eyJraWQi(...)Las-AAW9w
Accepts one of the following messages:
Add a player to the matchmaking system
Depending on your game configuration, additional payload fields might be required.
{
"action": "addPlayer",
"messageId": "nfasooa73zga9p3ja",
"payload": {
"gameId": "1v1",
"partyName": "party1",
"players": [
{
"playerId": "player1",
"servers": [
"server1"
]
}
]
}
}
{
"action": "addPlayer",
"messageId": "nfasooa73zga9p3jb",
"payload": {
"gameId": "1v1",
"players": [
{
"playerId": "player1",
"servers": [
"server1"
],
"reference": "int_plyr_1"
}
]
}
}
Remove a previously added player from the queue
Please note you can only remove players waiting for a match. Players that have already been matched can be removed from the queue by setting the match suggestion to "failed" only.
{
"action": "removePlayer",
"messageId": "nfasooa73zga9p3jc",
"payload": {
"gameId": "1v1",
"playerId": "player1"
}
}
Retrieve a list of players being processed
Please note this action only retrieves players that are in a waiting or matched state, not players who are in a running match.
{
"action": "getPlayers",
"messageId": "nfasooa73zga9p3jd",
"payload": {
"gameId": "1v1"
}
}
Obtain pending match suggestions
In the recommended setup, match suggestions are automatically pushed via the websocket. However, this message can be useful in two cases: a) If a websocket connection is terminated in an unplanned fashion, match suggestions that could not be delivered during the outage can be requested using this message. b) In case you want to implement a poll architecture, you can use this message to request pending matches.'
{
"action": "getMatches",
"messageId": "nfasooa73zga9p3je",
"payload": {
"gameId": "1v1"
}
}
Confirm the successful delivery of a match suggestion
In the recommended setup, match suggestions are automatically pushed via the websocket. To ensure that the match suggestion has been received, the client can confirm the delivery. In case the delivery is not confirmed, the match suggestion will be re-sent after a certain backoff time. In the default configuration, match delivery is retried for up to two minutes.
{
"action": "matchSuggestionDelivery",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61"
}
}
Confirm the successful creation of a match
Depending on your game configuration, additional payload fields might be required.
{
"action": "updateMatchConfirmed",
"messageId": "nfasooa73zga9p3jf",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61"
}
}
Report failed match creation for a suggested match
{
"action": "updateMatchFailed",
"messageId": "nfasooa73zga9p3jg",
"payload": {
"gameId": "1v1",
"matchId": "f18cf73d-d9d3-4e3c-9a36-b05124928301",
"requeue": [
"player1",
"player2",
"player3"
],
"remove": [
"player4"
]
}
}
Report the completion of a match
Depending on your game configuration, additional payload fields might be required.
{
"action": "updateMatchCompleted",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"server": "server1",
"gameLength": 1200,
"teams": [
{
"rank": 0,
"players": [
{
"playerId": "player1",
"score": 100
}
]
},
{
"rank": 1,
"players": [
{
"playerId": "player2",
"score": 80
}
]
}
]
}
}
Request backfilling for a running match
Depending on your game configuration, additional payload fields might be required.
{
"action": "requestBackfilling",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"droppedPlayerOd": "player1"
},
"matchScores": [
{
"score": 165,
"players": [
{
"playerId": "player1",
"score": 55
},
{
"playerId": "player2",
"score": 110
}
]
},
{
"score": 195,
"players": [
{
"playerId": "player3",
"score": 100
},
{
"playerId": "player4",
"score": 95
}
]
}
]
}
Cancel a pending backfilling request
{
"action": "cancelBackfillingRequest",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"backfillingRequestId": "c35a725f-0abf-4f66-96b4-9b8e32223bdd"
}
}
Get the stats of a player
{
"action": "getPlayerStats",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"playerId": "player1"
}
}
Subscribe to match suggestions
{
"action": "subscribe",
"messageId": "nfasooa73zga9p3ji",
"payload": {
"gameIds": [
"1v1"
]
}
}
Subscribe to match suggestions
{
"action": "unsubscribe",
"messageId": "nfasooa73zga9p3jj",
"payload": {
"gameIds": [
"1v1"
]
}
}
Accepts one of the following messages:
Acknowledgement of adding a player to the matchmaking system
{
"action": "addPlayerResponse",
"messageId": "nfasooa73zga9p3jb",
"payload": {
"gameId": "1v1",
"playerIds": [
"player1"
]
}
}
Acknowledges the removal of a player from the matchmaking system
{
"action": "removePlayerResponse",
"messageId": "nfasooa73zga9p3jc",
"payload": {
"gameId": "1v1",
"playerId": "player1",
"reference": "int_plyr_1"
}
}
List of players being processed
{
"action": "getPlayersResponse",
"messageId": "nfasooa73zga9p3jd",
"payload": {
"gameId": "1v1",
"players": [
{
"playerId": "player1",
"state": "waiting"
},
{
"playerId": "player2",
"state": "matched"
}
]
}
}
{
"action": "getMatchesResponse",
"messageId": "nfasooa73zga9p3je",
"payload": {
"gameId": "1v1",
"matches": []
}
}
{
"action": "getMatchesResponse",
"messageId": "nfasooa73zga9p3je",
"payload": {
"gameId": "1v1",
"matches": [
{
"uuid": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"teams": [
{
"players": [
{
"playerId": "player1",
"reference": "int_plyr_1"
},
{
"playerId": "player2",
"reference": "int_plyr_2"
}
]
},
{
"players": [
{
"playerId": "player3",
"reference": "int_plyr_3"
},
{
"playerId": "player4",
"reference": "int_plyr_4"
}
]
}
]
}
]
}
}
Acknowledges the delivery report for a match suggestion
{
"action": "matchSuggestionDeliveryResponse",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61"
}
}
Acknowledges the report of a confirmed match
{
"action": "updateMatchConfirmedResponse",
"messageId": "nfasooa73zga9p3jf",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61"
}
}
Acknowledges the report of a failed match
{
"action": "updateMatchFailedResponse",
"messageId": "nfasooa73zga9p3jg",
"payload": {
"gameId": "1v1",
"matchId": "f18cf73d-d9d3-4e3c-9a36-b05124928301"
}
}
Acknowledges the report of a completed match and returns updated player stats
{
"action": "updateMatchCompletedResponse",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"players": [
{
"playerId": "player1",
"totalWins": 1,
"totalLosses": 0,
"totalMatchesPlayed": 1,
"season": "S1",
"seasonWins": 1,
"seasonLosses": 0,
"seasonMatchesPlayed": 1,
"rating": 1000,
"rankingPoints": 100,
"ratingDeltaLastGame": 10,
"rankingDeltaLastGame": 1,
"wins": 1,
"losses": 0,
"matchesPlayed": 1,
"winRatio": 1
},
{
"playerId": "player2",
"totalWins": 1,
"totalLosses": 0,
"totalMatchesPlayed": 1,
"season": "S1",
"seasonWins": 1,
"seasonLosses": 0,
"seasonMatchesPlayed": 1,
"rating": 1000,
"rankingPoints": 100,
"ratingDeltaLastGame": 10,
"rankingDeltaLastGame": 1,
"wins": 1,
"losses": 0,
"matchesPlayed": 1,
"winRatio": 1
}
]
}
}
Acknowledges the request for backfilling
{
"action": "requestBackfillingResponse",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"backfillingRequestId": "c35a725f-0abf-4f66-96b4-9b8e32223bdd"
}
}
Replacement player suggestion for a backfilling request
{
"action": "backfillingMatchSuggestion",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"backfillingRequestId": "c35a725f-0abf-4f66-96b4-9b8e32223bdd",
"player": {
"playerId": "player7",
"reference": "tkt_176258"
}
}
}
Acknowledges the cancellation of a backfilling request
{
"action": "cancelBackfillingRequestResponse",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"gameId": "1v1",
"matchId": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"backfillingRequestId": "c35a725f-0abf-4f66-96b4-9b8e32223bdd"
}
}
{
"action": "getPlayerStatsResponse",
"messageId": "nfasooa73zga9p3jh",
"payload": {
"playerId": "player_1",
"totalMatchesPlayed": 1,
"totalWins": 0,
"totalLosses": 1,
"seasons": [
{
"season": "S1",
"seasonMatchesPlayed": 1,
"seasonWins": 0,
"seasonLosses": 1,
"stats": [
{
"mode": "1v1",
"matchesPlayed": 1,
"wins": 0,
"losses": 1,
"rating": 1436.034,
"ratingUncertainty": 332.312,
"rankingPoints": 0,
"winRatio": 0
}
]
}
]
}
}
A message sent by the server for each suggested match
This message is only sent if a websocket is registered to receive match suggestions. This can be configured at connection time using the corresponding url parameter.
{
"action": "matchSuggestion",
"payload": {
"gameId": "1v1",
"match": {
"uuid": "3972ac34-0cb3-4cbf-88c0-7c8162d0ba61",
"server": "server1",
"teams": [
{
"players": [
{
"playerId": "player1",
"reference": "int_plyr_1",
"rating": 1500,
"ranking": 651
},
{
"playerId": "player2",
"reference": "int_plyr_2",
"rating": 1500,
"ranking": 680
}
]
},
{
"players": [
{
"playerId": "player3",
"reference": "int_plyr_3",
"rating": 1500,
"ranking": 684
},
{
"playerId": "player4",
"reference": "int_plyr_4",
"rating": 1500,
"ranking": 690
}
]
}
]
}
}
}
Acknowledges match suggestion subscription
{
"action": "subscribeResponse",
"messageId": "nfasooa73zga9p3ji",
"payload": {
"gameIds": [
"1v1"
],
"priority": 10,
"rateLimit": 100
}
}
Acknowledges match suggestion unsubscription
{
"action": "unsubscribeResponse",
"messageId": "nfasooa73zga9p3jj",
"payload": {
"gameIds": [
"1v1"
]
}
}
A message periodically sent by the server to avoid connection timeouts
{
"action": "keepAlive",
"payload": {}
}
Error message sent by the server
This message is sent by the server in case of an error. The payload contains the error message.
{
"action": "addPlayer",
"messageId": "nfasooa73zga9p3ja",
"error": {
"code": 403,
"message": "The requested operation is forbidden."
}
}
Add a player to the matchmaking system
Depending on your game configuration, additional payload fields might be required.
Acknowledgement of adding a player to the matchmaking system
Remove a previously added player from the queue
Please note you can only remove players waiting for a match. Players that have already been matched can be removed from the queue by setting the match suggestion to "failed" only.
Acknowledges the removal of a player from the matchmaking system
Retrieve a list of players being processed
Please note this action only retrieves players that are in a waiting or matched state, not players who are in a running match.
List of players being processed
Obtain pending match suggestions
In the recommended setup, match suggestions are automatically pushed via the websocket. However, this message can be useful in two cases: a) If a websocket connection is terminated in an unplanned fashion, match suggestions that could not be delivered during the outage can be requested using this message. b) In case you want to implement a poll architecture, you can use this message to request pending matches.'
A message sent by the server for each suggested match
This message is only sent if a websocket is registered to receive match suggestions. This can be configured at connection time using the corresponding url parameter.
Confirm the successful delivery of a match suggestion
In the recommended setup, match suggestions are automatically pushed via the websocket. To ensure that the match suggestion has been received, the client can confirm the delivery. In case the delivery is not confirmed, the match suggestion will be re-sent after a certain backoff time. In the default configuration, match delivery is retried for up to two minutes.
Acknowledges the delivery report for a match suggestion
Confirm the successful creation of a match
Depending on your game configuration, additional payload fields might be required.
Acknowledges the report of a confirmed match
Report failed match creation for a suggested match
Acknowledges the report of a failed match
Report the completion of a match
Depending on your game configuration, additional payload fields might be required.
Acknowledges the report of a completed match and returns updated player stats
Request backfilling for a running match
Depending on your game configuration, additional payload fields might be required.
Acknowledges the request for backfilling
Replacement player suggestion for a backfilling request
Cancel a pending backfilling request
Acknowledges the cancellation of a backfilling request
Get the stats of a player
Subscribe to match suggestions
Acknowledges match suggestion subscription
Subscribe to match suggestions
Acknowledges match suggestion unsubscription
A message periodically sent by the server to avoid connection timeouts
Error message sent by the server
This message is sent by the server in case of an error. The payload contains the error message.