7. Heartbeats & Disconnects

An active search only stays queued for as long as the client keeps proving it's still around. That's what heartbeats are for — and if the connection drops anyway, there's a short window to reconnect without losing the player's place in the queue.

Heartbeats

While a search is active, send a heartbeat more often than every 3 minutes:

{ "action": "heartbeat" }

No response is sent

A heartbeat doesn't get an acknowledgement back. Don't wait for one — just send it on an interval (e.g. every minute) for as long as the player is searching.

If a heartbeat isn't received in time, the search is dropped from the queue as if the player had disconnected.

In a party, every member sends heartbeats while the party is searching, not only the leader who started it — each member has a search of their own in the queue.

Disconnects

If the connection drops — network loss, app backgrounding, a crash — the server doesn't immediately give up on the player's search. There's a 30-second grace window to reconnect:

Open a new WebSocket connection with a freshly generated ticket (see Generate a Ticket — the old ticket was already consumed by the first connection).
Send begin_search again with the same gameMode.

If this happens within 30 seconds of the drop, the player resumes the same search — their place in the queue isn't lost. After 30 seconds, the search is abandoned and the player would need to start a new search from scratch. Abandoned and cancelled searches never use any of your matched player allowance — only players placed in a made match do.

Disconnecting during a ping check

For Ping-based game modes, a disconnect while waiting on a PING/pong round trip has nothing to resume — no search exists yet at that point. Reconnecting and sending begin_search again just starts the ping check over from scratch, the same as a fresh search.

Party members don't get a reconnect window

A party can't search short-handed, so there's nothing to resume. If a member's connection drops while the party is searching or starting, they are removed from the party, the party's search is cancelled for everyone, and the remaining members receive PARTY_SEARCH_CANCELLED (reason MEMBER_DISCONNECTED). After reconnecting, the player rejoins with the party's join code or a fresh invite, and the leader starts the search again.

Summary

Situation	What to do
Player is actively searching	Send `heartbeat` at least once every 3 minutes.
Connection drops unexpectedly	Get a new ticket, reconnect, and re-send `begin_search` within 30 seconds to resume.
Player cancels intentionally	Send `cancel_search` instead of just closing the connection.
Party member's connection drops	They leave the party and its search is cancelled. Reconnect, rejoin the party, and have the leader search again.

That covers the full integration flow — from account setup through to a resilient, reconnecting matchmaking client.