Getting Started

This guide outlines the shortest path towards integrating support for the IMS Matchmaker into your game client. If your game uses Unreal Engine 4, a plugin is available - please contact us for more information.

Open a WebSocket connection to the matchmaking server.
Specify the desired encoding using the Sec-WebSocket-Protocol HTTP header; either json for JSON or fbs for Flatbuffer. (For readability, this guide will assume JSON - see the subprotocol guide for more information.)
You must also specify an imp-project HTTP header value (or project_id query parameter), which will have been provided to you.
If client authentication is being used (e.g. PlayFab or JWT), you must also specify an Authorization HTTP header, for example:
```
GET /v1/lobby HTTP/1.1
Host: prd.matchmaker.os.i8e.io
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: json
Sec-WebSocket-Version: 13
Imp-Project: shooter
Authorization: Bearer secret-token:playfab/ABC123DEF456
```
See the Authentication guide for more details on client authentication methods and configuration.
Once a WebSocket connection has been established, the client will receive a ClientStatusResponse message and will be able to send requests to the Matchmaker.

Check client status.

Send an empty ClientStatusRequest message to the server:

{
  "msg_type": "ClientStatusRequest",
  "msg": {}
}

The server will respond with a ClientStatusResponse message describing the current state as Idle:

{
  "msg_type": "ClientStatusResponse",
  "msg": {
    "id": "<connection-id>"
    "status": "Idle",
    "latencyMS": 123
  }
}

List available queues.

Send an empty QueueListRequest message to the server:

{
  "msg_type": "QueueListRequest",
  "msg": {}
}

The server will respond with a QueueListResponse listing the available queues:

{
  "msg_type": "QueueListResponse",
  "msg": {
    "queues": [
      {
        "id": "<queue-id>",
        "name": "<queue-name>",
        "attributes": {}
      }
    ]
  }
}

Join a queue.
Send a QueueJoinRequest message to the server, using the <queue-id> from the previous response to select the queue you want the client to join.
```
{
  "msg_type": "QueueJoinRequest",
  "msg": {
    "id": "<queue-id>",
    "attributes": [
      {
        "entry_type": "StringMapEntry",
        "entry": {
          "key": "map",
          "value": "shoreditch"
        }
      }
    ],
    "clientLatency": []
  }
}
```
See the QueueJoinRequest section for more details on specifying queue requirements.
If successful, the server will respond with a new ClientStatusResponse message describing the new state as Queued. Additional information about the queue the client has joined is provided, including the number of players who are also in the same queue (playerCount) which can be relayed back to the player to give them an indication on whether they are likely to be formed into a match soon.
```
{
  "msg_type": "ClientStatusResponse",
  "msg": {
    "status": "Queued",
    "latencyMS": 123,
    "queue": {
      "id": "<queue-id>",
      "ticket": "<ticket-id>",
      "queueDurationMillis": 1234,
      "connection": "",
      "token": "",
      "playerCount": 5
    }
  }
}
```
Note the ticket field - this will contain an ID for the player's matchmaking ticket, which represents their position within the matchmaking queue. A ticket is valid from the moment the player joins a queue, until they are matched or disconnect from the Matchmaker. (It is also included in the returned Assignment Token when a match is found.)
Wait for a match to be formed.
While a player is waiting for a match to be formed, you can periodically send ClientStatusRequests to get an updated playerCount as part of the returned ClientStatusResponse message.
```
{
  "msg_type": "ClientStatusRequest",
  "msg": {}
}
```
Note, the matchmaker only recalculates the playerCount every 10 seconds for a specific queue, therefore you should send no more than one ClientStatusRequest every 10 seconds from an individual game client.
```
{
  "msg_type": "ClientStatusResponse",
  "msg": {
    "status": "Queued",
    "latencyMS": 123,
    "queue": {
      "id": "<queue-id>",
      "ticket": "<ticket-id>",
      "queueDurationMillis": 11234,
      "connection": "",
      "token": "",
      "playerCount": 8
    }
  }
}
```
Match is formed. After some time, assuming sufficient players join the same matchmaking pool, a match will be formed and the client will receive a ServerAssignmentResponse message containing the connection information:
```
{
  "msg_type": "ServerAssignmentResponse",
  "msg": {
    "queue": "<queue-id>",
    "assignment": "203.4.113.4:29000",
    "token": "<jwt-token>"
  }
}
```
The assignment value describes the game server the game client has been assigned to.
The token value is a signed JWT containing additional information about the game. The client should provide this to the game server when they connect. See Server Getting Started Guide for more information on the what the token contains and how it should be used.
Join the game!
At this point, the game client can disconnect from the matchmaking server and join the game server at the provided address.