# Client-side callbacks
We broadcast client events on the window via `postMessage` and on any method you provide in `cta` field while generating the `roomDetails` object.
{% hint style="info" %}
All the data broadcasted is in the form of stringified JSON.
{% endhint %}
### Events
Match found event
**Trigger**
This event is broadcasted when a player is matched with [an opponent](#user-content-fn-1)[^1], and a countdown starts for the match to start.
**Broadcast payload structure**
```
{
"event": "match_found",
"gameCode": "game-code",
"matchId": "match-id",
"players": [
"sub-1",
"sub-2"
]
}
```
**Payload notes**
* `gameCode` is the unique identifier for that game (you get this on the [All Games API](https://docs.platform.gamezop.com/publishers/gamezop/types-of-integration/all-games-api))
* `matchId` is the identifier generated by your systems via the [Create Match API](https://docs.platform.gamezop.com/publishers/gamezop/advanced/receive-winners-data#create-match-api)
* `players` is an array of the `sub` identifiers you pass while generating the `roomDetails` object. IDs of all players matched together are passed.
No match found event
**Trigger**
This event is broadcasted when a player completes the [wait time](#user-content-fn-2)[^2] for finding [an opponent](#user-content-fn-3)[^3], but the [minimum number of opponents needed to start the match](#user-content-fn-4)[^4] could not be found.
**Broadcast payload structure**
```
{
"event": "match_not_found",
"gameCode": "game-code"
}
```
**Payload notes**
* `gameCode` is the unique identifier for that game (you get this on the [All Games API](https://docs.platform.gamezop.com/publishers/gamezop/types-of-integration/all-games-api))
Match start event
**Trigger**
This event is broadcasted when the user starts playing the match. This happens after opponents are found, and the match countdown has finished.
**Broadcast payload structure**
```
{
"event": "match_start",
"gameCode": "game-code",
"matchId": "match-id",
"players": [
{
"firstName":"user-name",
"photo":"https://www.exammple.com/photos/user-1.png",
"gzpId":"sub-id"
},
{
"firstName":"user-name",
"photo":"https://www.exammple.com/photos/user-1.png",
"gzpId":"sub-id"
}
]
}
```
**Payload notes**
* `gameCode` is the unique identifier for that game (you get this on the [All Games API](https://docs.platform.gamezop.com/publishers/gamezop/types-of-integration/all-games-api))
* `matchId` is the identifier generated by your systems via the [Create Match API](https://docs.platform.gamezop.com/publishers/gamezop/advanced/receive-winners-data#create-match-api)
* `players` consists of an array of objects, each representing one of the players of that match. Within each object, `firstName` represents the `user.name` value from the [`roomDetails` object](https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/..#generate-a-roomdetails-object) that you configure. Similarly, `photo` in the broadcast represents the `photo` URL you pass for that user, and the `gzpId` value is the `sub` value you pass for that user.
Match playing event
**Trigger**
This event is triggered each time there is a score update for any of the players in the match. Let's say Alice and Bob are in a match, and Alice's score goes from 0 to 1, then our systems will dispatch a `match_playing` event on both clients, and not just on Alice's client.
**Broadcast payload structure**
```
{
"event": "match_playing",
"gameCode": "game-code",
"matchId": "match-id",
"players": [
{
"firstName":"user-name",
"photo":"https://www.exammple.com/photos/user-1.png",
"gzpId":"sub-id",
"score": 10,
"rank: 1
},
{
"firstName":"user-name",
"photo":"https://www.exammple.com/photos/user-1.png",
"gzpId":"sub-id",
"score": 10,
"rank: 1
}
]
}
```
**Payload notes**
* All notes remain same as the `match_start` event above. We additionally send 2 more values for each `players` object: `score` and `rank`. These represent the latest score of the corresponding user, and their latest rank in the match.
Match over event
**Trigger**
This is broadcasted when a user is done with all their attempts[^5], but their opponent is still playing. In case of multiplayer games, one player may finish before another. For instance, if Alice has scored 100 and runs out of attempts, whereas Bob is still at score 90, Bob can continue playing as he still has a chance to beat Alice.
The broadcast is only made for the user that has run out of attempts, and is [not made on the other user's device](#user-content-fn-6)[^6].
**Broadcast payload structure**
```
{
"event": "match_over",
"gameCode": "game-code",
"players": [
{
"firstName":"user-name",
"photo":"https://www.exammple.com/photos/user-1.png",
"gzpId":"sub-id",
"score": 10,
"rank: 1
},
{
"firstName":"user-name",
"photo":"https://www.exammple.com/photos/user-1.png",
"gzpId":"sub-id",
"score": 10,
"rank: 1
}
]
}
```
**Payload notes**
* All notes remain same as the `match_playing` event above.
Match result event
**Trigger**
This event is triggered when the match is over for all players and the final results are known.
Note that in some cases, `match_over` and `match_result` may come together. Let's say Alice and Bob are playing. Alice is at score 100, and Bob is at 80. Bob runs out of attempts. Since Alice is already at a higher score, she automatically wins, even though she did not exhaust her attempts. This would trigger `match_over` and `match_result` events for both players.
Also note that `match_result` is broadcasted to all players in the match.
**Broadcast payload structure**
```
{
"event": "match_result",
"gameCode": "game-code",
"players": [
{
"firstName":"user-name",
"photo":"https://www.exammple.com/photos/user-1.png",
"gzpId":"sub-id",
"score": 10,
"rank: 1
},
{
"firstName":"user-name",
"photo":"https://www.exammple.com/photos/user-1.png",
"gzpId":"sub-id",
"score": 10,
"rank: 1
}
]
}
```
**Payload notes**
* All notes remain same as the `match_playing` event above.
Navigate home event
**Trigger**
This event is broadcasted when the user taps on the option to "GO HOME" from within the game UI. You can receive this event in your app and navigate the user to your app's home screen / take any other action.
**Broadcast payload structure**
```
{
"event": "go_home",
"gameCode": "game-code"
}
```
**Payload notes**
* `gameCode` is the unique identifier for that game (you get this on the [All Games API](https://docs.platform.gamezop.com/publishers/gamezop/types-of-integration/all-games-api))
{% hint style="info" %}
These events above are specific to multiplayer experiences. We also broadcast events and game states in case of single-player experiences, details for which can be found [here](https://docs.platform.gamezop.com/publishers/gamezop/advanced/receive-scores).
{% endhint %}
[^1]: Could be more than one opponent, depending on how you configure your [`roomDetails` object.](https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/..#generate-a-roomdetails-object) This event is broadcasted when all opponents needed for the match to start have been found.
[^2]: Configurable via the `maxWait` value in the [`roomDetails` object.](https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/..#generate-a-roomdetails-object)
[^3]: Could be more than one opponent, depending on how you configure your [`roomDetails` object.](https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/..#generate-a-roomdetails-object)
[^4]: Configurable via the `minPlayers` value in the [`roomDetails` object.](https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/..#generate-a-roomdetails-object)
[^5]: Configured by you in the [`roomDetails` object](https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/..#generate-a-roomdetails-object)
[^6]: The broadcast on their device would be made when they run out of attempts themselves.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.platform.gamezop.com/publishers/gamezop/advanced/multiplayer-games/client-side-callbacks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.