Parties

To have multiple players join a match together, your game must already have a means for players to communicate with each other - e.g. via an in-game chat system or rich presence. Clients must advertise their connection ID (the id value in ClientStatusResponse) to each other so the party ‘leader’ can see the connection IDs of all the players they want to be in the party - it is these connection IDs that define which players will be put into the match together.

The party ‘leader’, should then issue a QueueJoinRequest, providing the connection IDs of the users they want to queue up with as the partyMembers array. For example, if the leader has the ID connection-1, and wants to queue up with their friends connection-2 and connection-3, the request would look like this:

{
  "msg_type": "QueueJoinRequest",
  "msg": {
    "id": "<queue-id>",
    "attributes": [
      {
        "entry_type": "StringMapEntry",
        "entry": {
          "key": "map",
          "value": "shoreditch"
        }
      }
    ],
    "partyMembers": ["connection-1", "connection-2", "connection-3"]
  }
}

In return, the ClientStatusResponse should show a state of Queued, and include a partyToken value:

{
  "msg_type": "ClientStatusResponse",
  "msg": {
    "status": "Queued",
    "latencyMS": 123,
    "partyToken": "<party-token>",
    "queue": {
      "id": "<queue-id>",
      "ticket": "<ticket-id>",
      "queueTime": 1234,
      "connection": "",
      "token": "",
      "playerCount": 5
    }
  }
}

The party leader should send the partyToken value to the other members of the party, who in turn should each issue their own QueueJoinRequest, but this time only containing the partyToken value:

{
  "msg_type": "QueueJoinRequest",
  "msg": {
    "partyToken": "<party-token>"
  }
}

Once all the party members have joined the queue using the same party token, they will be matched into the same game together, and all receive connection details for the same match at the same time. (The Matchmaker will not return a match for any party member until all players provided in the leader's QueueJoinRequest have joined the queue using the same Party Token.)