Idem Matchmaking Websocket API 1.3.2

WebSockets API offers access to idem matchmaking reducing latency compared to the REST API.

Central concepts

Authentication via Token

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.

Message exchange

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.

Error handling

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.

Keep alive messages

To avoid connection timeouts, the server sends a keep alive message every minute. The keep alive message has an empty payload.

Push vs. pull architecture

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:

Connection time

At connection time, you can provide the following query string parameters to the connection url:

  • receiveMatches: true
  • gameMode: target game mode id, multiple modes can be separated by commas
  wss://ws.int.idem.gg/?receiveMatches=true&gameMode=1v1,2v2,3v3&authorization=eyJraWQi(...)Las-AAW9w

At runtime

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"],
  }
}
  • #websockets

Servers

  • wss://ws.int.idem.gg/wssint

    System for integration testing of new features.

    Authentication via Token

    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.InitiateAuth
    • Content-Type: application/x-amz-json-1.1
    • Request body: {"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
    

Operations

  • SEND /

    Send messages to the API

    Operation IDsend

    Available only on servers:

    Accepts one of the following messages:

    • #0addPlayerAction

      Add a player to the matchmaking system

      Message IDaddPlayerAction

      Depending on your game configuration, additional payload fields might be required.

      object
      object

      Examples

    • #1removePlayerAction

      Remove a previously added player from the queue

      Message IDremovePlayerAction

      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.

      object
      object

      Examples

    • #2getPlayersAction

      Retrieve a list of players being processed

      Message IDgetPlayersAction

      Please note this action only retrieves players that are in a waiting or matched state, not players who are in a running match.

      object
      object

      Examples

    • #3getMatchesAction

      Obtain pending match suggestions

      Message IDgetMatchesAction

      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.'

      object
      object

      Examples

    • #4matchSuggestionDeliveryAction

      Confirm the successful delivery of a match suggestion

      Message IDmatchSuggestionDeliveryAction

      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.

      object
      object

      Examples

    • #5confirmMatchAction

      Confirm the successful creation of a match

      Message IDconfirmMatchAction

      Depending on your game configuration, additional payload fields might be required.

      object
      object

      Examples

    • #6failMatchAction

      Report failed match creation for a suggested match

      Message IDfailMatchAction
      object
      object

      Examples

    • #7completeMatchAction

      Report the completion of a match

      Message IDcompleteMatchAction

      Depending on your game configuration, additional payload fields might be required.

      object
      object

      Examples

    • #8requestBackfillingAction

      Request backfilling for a running match

      Message IDrequestBackfillingAction

      Depending on your game configuration, additional payload fields might be required.

      object
      object

      Examples

    • #9cancelBackfillingRequestAction

      Cancel a pending backfilling request

      Message IDcancelBackfillingRequestAction
      object
      object

      Examples

    • #10getPlayerStatsAction

      Get the stats of a player

      Message IDgetPlayerStatsAction
      object
      object

      Examples

    • #11subscribeAction

      Subscribe to match suggestions

      Message IDsubscribeAction
      object
      object

      Examples

    • #12unsubscribeAction

      Subscribe to match suggestions

      Message IDunsubscribeAction
      object
      object

      Examples

  • RECEIVE /

    Receive messages from the API

    Operation IDreceive

    Available only on servers:

    Accepts one of the following messages:

    • #0addPlayerResponse

      Acknowledgement of adding a player to the matchmaking system

      Message IDaddPlayerResponse
      object

      Examples

    • #1removePlayerResponse

      Acknowledges the removal of a player from the matchmaking system

      Message IDremovePlayerResponse
      object

      Examples

    • #2getPlayersResponse

      List of players being processed

      Message IDgetPlayersResponse
      object

      Examples

    • #3getMatchesResponse

      Returns pending matches

      Message IDgetMatchesResponse
      object

      Examples

    • #4matchSuggestionDeliveryResponse

      Acknowledges the delivery report for a match suggestion

      Message IDmatchSuggestionDeliveryResponse
      object

      Examples

    • #5confirmMatchResponse

      Acknowledges the report of a confirmed match

      Message IDconfirmMatchResponse
      object

      Examples

    • #6failMatchResponse

      Acknowledges the report of a failed match

      Message IDfailMatchResponse
      object

      Examples

    • #7completeMatchResponse

      Acknowledges the report of a completed match and returns updated player stats

      Message IDcompleteMatchResponse
      object

      Examples

    • #8requestBackfillingResponse

      Acknowledges the request for backfilling

      Message IDrequestBackfillingResponse
      object

      Examples

    • #9backfillingMatchSuggestion

      Replacement player suggestion for a backfilling request

      Message IDbackfillingMatchSuggestion
      object

      Examples

    • #10cancelBackfillingRequestResponse

      Acknowledges the cancellation of a backfilling request

      Message IDcancelBackfillingRequestResponse
      object

      Examples

    • #11getPlayerStatsResponse

      Reports player stats

      Message IDgetPlayerStatsResponse
      object

      Examples

    • #12matchSuggestionMessage

      A message sent by the server for each suggested match

      Message IDmatchSuggestionMessage

      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.

      object

      Examples

    • #13subscribeResponse

      Acknowledges match suggestion subscription

      Message IDsubscribeResponse
      object

      Examples

    • #14unsubscribeResponse

      Acknowledges match suggestion unsubscription

      Message IDunsubscribeResponse
      object

      Examples

    • #15keepAliveMessage

      A message periodically sent by the server to avoid connection timeouts

      Message IDkeepAliveMessage
      object

      Examples

    • #16errorMessage

      Error message sent by the server

      Message IDerrorMessage

      This message is sent by the server in case of an error. The payload contains the error message.

      object

      Examples

Messages

  • #1addPlayerAction

    Add a player to the matchmaking system

    Message IDaddPlayerAction

    Depending on your game configuration, additional payload fields might be required.

    object
    object
  • #2addPlayerResponse

    Acknowledgement of adding a player to the matchmaking system

    Message IDaddPlayerResponse
    object
  • #3removePlayerAction

    Remove a previously added player from the queue

    Message IDremovePlayerAction

    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.

    object
    object
  • #4removePlayerResponse

    Acknowledges the removal of a player from the matchmaking system

    Message IDremovePlayerResponse
    object
  • #5getPlayersAction

    Retrieve a list of players being processed

    Message IDgetPlayersAction

    Please note this action only retrieves players that are in a waiting or matched state, not players who are in a running match.

    object
    object
  • #6getPlayersResponse

    List of players being processed

    Message IDgetPlayersResponse
    object
  • #7getMatchesAction

    Obtain pending match suggestions

    Message IDgetMatchesAction

    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.'

    object
    object
  • #8getMatchesResponse

    Returns pending matches

    Message IDgetMatchesResponse
    object
  • #9matchSuggestionMessage

    A message sent by the server for each suggested match

    Message IDmatchSuggestionMessage

    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.

    object
  • #10matchSuggestionDeliveryAction

    Confirm the successful delivery of a match suggestion

    Message IDmatchSuggestionDeliveryAction

    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.

    object
    object
  • #11matchSuggestionDeliveryResponse

    Acknowledges the delivery report for a match suggestion

    Message IDmatchSuggestionDeliveryResponse
    object
  • #12confirmMatchAction

    Confirm the successful creation of a match

    Message IDconfirmMatchAction

    Depending on your game configuration, additional payload fields might be required.

    object
    object
  • #13confirmMatchResponse

    Acknowledges the report of a confirmed match

    Message IDconfirmMatchResponse
    object
  • #14failMatchAction

    Report failed match creation for a suggested match

    Message IDfailMatchAction
    object
    object
  • #15failMatchResponse

    Acknowledges the report of a failed match

    Message IDfailMatchResponse
    object
  • #16completeMatchAction

    Report the completion of a match

    Message IDcompleteMatchAction

    Depending on your game configuration, additional payload fields might be required.

    object
    object
  • #17completeMatchResponse

    Acknowledges the report of a completed match and returns updated player stats

    Message IDcompleteMatchResponse
    object
  • #18requestBackfillingAction

    Request backfilling for a running match

    Message IDrequestBackfillingAction

    Depending on your game configuration, additional payload fields might be required.

    object
    object
  • #19requestBackfillingResponse

    Acknowledges the request for backfilling

    Message IDrequestBackfillingResponse
    object
  • #20backfillingMatchSuggestion

    Replacement player suggestion for a backfilling request

    Message IDbackfillingMatchSuggestion
    object
  • #21cancelBackfillingRequestAction

    Cancel a pending backfilling request

    Message IDcancelBackfillingRequestAction
    object
    object
  • #22cancelBackfillingRequestResponse

    Acknowledges the cancellation of a backfilling request

    Message IDcancelBackfillingRequestResponse
    object
  • #23getPlayerStatsAction

    Get the stats of a player

    Message IDgetPlayerStatsAction
    object
    object
  • #24getPlayerStatsResponse

    Reports player stats

    Message IDgetPlayerStatsResponse
    object
  • #25subscribeAction

    Subscribe to match suggestions

    Message IDsubscribeAction
    object
    object
  • #26subscribeResponse

    Acknowledges match suggestion subscription

    Message IDsubscribeResponse
    object
  • #27unsubscribeAction

    Subscribe to match suggestions

    Message IDunsubscribeAction
    object
    object
  • #28unsubscribeResponse

    Acknowledges match suggestion unsubscription

    Message IDunsubscribeResponse
    object
  • #29keepAliveMessage

    A message periodically sent by the server to avoid connection timeouts

    Message IDkeepAliveMessage
    object
  • #30errorMessage

    Error message sent by the server

    Message IDerrorMessage

    This message is sent by the server in case of an error. The payload contains the error message.

    object

Schemas

  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object
  • object