4. Parties

Parties let friends queue together, and are optional: skip this step if your game only does solo queues. Players form a party over the WebSocket after connecting and before searching; the party leader then sends begin_search once (see Start a Search) and the whole party is queued.

Parties are off by default. Turn them on per game mode in the Config page (see Game Modes).

Forming a party

{ "action": "create_party" }

The creator becomes the party leader and receives a PARTY_UPDATE that includes a joinCode. Share the code with friends through your own channels (your friends list, chat, a lobby UI). They join with:

{ "action": "join_party", "payload": { "code": "K7M2QX" } }

You can also invite a specific player by their userId instead of sharing a code (see Inviting a player).

Every member receives a PARTY_UPDATE whenever the party changes. It always carries the full state, so render from it directly:

{
  "action": "PARTY_UPDATE",
  "data": {
    "party": {
      "partyId": "…",
      "joinCode": "K7M2QX",
      "leaderUserId": "alice",
      "members": [{ "userId": "alice" }, { "userId": "bob" }],
      "status": "LOBBY"
    }
  }
}

Other party actions:

Action	Who	Effect
`leave_party`	any member	You get `PARTY_LEFT`. If you were the leader, the longest-standing member takes over.
`kick_member` `{ userId }`	leader	The player gets `PARTY_LEFT` with reason `KICKED`.
`promote_leader` `{ userId }`	leader	Hands leadership to another member.
`invite_to_party` `{ userId }`	leader	Invites a player; they receive `PARTY_INVITE`.

Inviting a player

The leader can invite a player directly, as long as the party isn't searching or starting:

{ "action": "invite_to_party", "payload": { "userId": "bob" } }

The invited player receives a PARTY_INVITE, which stays valid for two minutes:

{ "action": "PARTY_INVITE", "data": { "partyId": "…", "fromUserId": "alice" } }

They reply with accept_invite (or decline_invite, which is optional) using the partyId:

{ "action": "accept_invite", "payload": { "partyId": "…" } }

Accepting joins the party exactly as if they'd used its code. Only players in your own tenant can be invited, and only if they're connected and not already in a party. If the invite can't be delivered you get PARTY_INVITEE_UNAVAILABLE, which deliberately doesn't say whether the player is offline or just busy.

Party basics

A player can only be in one party at a time, and creating or joining a party cancels any search they had running on their own. All members must hold tickets for the same region.

Searching as a party

Send begin_search as usual. When the connection is in a party, only the leader may do this, and it queues every member at once. Each member needs whatever attribute the game mode matches on (for example mmr in their ticket's attrs). A party is matched as a single unit: on its members' average MMR, or, for ping-based game modes, on its slowest member's ping.

Every member (not just the leader) receives SEARCH_STARTED, with the partyId, once the party is queued. While the party is searching its status is SEARCHING and its membership is locked: nobody can join. Every member should keep sending heartbeats while searching.

cancel_search from the leader stops the search for the whole party. If a member leaves, is kicked, or disconnects mid-search, the search is cancelled for everyone and the remaining members receive PARTY_SEARCH_CANCELLED. A member who disconnects is removed from the party and rejoins with the join code after reconnecting.

When a match is made, each player receives MATCH_FOUND as normal and the party returns to LOBBY, ready to queue again. The match webhook includes a PartyId on each participant so you can see who queued together.

Ping-based game modes

Ping needs a reading from every member, so starting a search takes a short extra step. The party's status becomes STARTING (with the gameMode), and each member receives a PING to answer with a pong, exactly as in Start a Search. Membership is locked meanwhile. Once every member has answered, the search is queued and everyone receives SEARCH_STARTED.

As with a solo ping check there's no timeout message: if a member doesn't answer within 10 seconds the check simply expires and the party is back in the lobby, so have the leader's client send begin_search again.

Keeping a party on one team

Each game mode has a Keep parties together setting.

On: a party is always placed on a single team, so a party can be no larger than the biggest team. Matches are only formed when every team can be filled exactly, which means some combinations can never play on their own. In a 3v3, three parties of two can't fill two teams of three; instead the queue waits for a match like two parties of two plus two solo players, with a solo padding out each team.
Off: parties are guaranteed to land in the same match, but their members may be split across teams (including against each other).

Waiting for the right sizes

With Keep parties together on, a pool made up only of awkwardly sized parties will wait until enough players of the right sizes arrive. Searches are not relaxed over time.

Errors

Party errors never close the connection:

ALREADY_IN_PARTY, NOT_IN_PARTY, PARTY_NOT_FOUND, PARTY_MEMBER_NOT_FOUND, PARTY_FULL, PARTY_SEARCHING, NOT_PARTY_LEADER, PARTIES_NOT_ENABLED, PARTY_TOO_LARGE, PARTY_MEMBER_ATTRIBUTE_MISSING, PARTY_CHANGED (retry), PARTY_INVITEE_UNAVAILABLE, PARTY_INVITE_NOT_FOUND.

With the party formed, the leader starts a search as usual.