Getting Started
1. Create a room
First, your app needs to create a new room. These rooms are ephemeral and will remain open for 24 hours.
To create a room, make a POST request to https://app.hackbox.ca/rooms.
// Headers
{
"Content-Type": "application/json"
}
// Body
{
"hostId": "11111111-2222-3333-4444-555555555555", // A UUID that identifies your host connection. Generate this yourself. (uuid, required)
"twitchRequired": false // Whether to require players to login with Twitch before joining your room. (boolean, optional, default: false)
}
// Returns
{
"ok": true,
"roomCode": "HKBX"
}
2. Connect via websocket
Now that your room is created, anyone can connect to it via websocket, but you can connect to it as the host by providing the hostId you used when creating the room. Connect with your preferred websocket client.
wss://app.hackbox.ca/socket.io?roomCode=HKBX&userId=11111111-2222-3333-4444-555555555555
3. Listen for events
Now it's time to set up event listeners on your host to handle the messages sent by the server.
state.host
state.host fires every time the state of the room changes. This includes when a new player joins, and when any player's online status changes.
{
"members": {
"11111111-1111-1111-1111-111111111111": {
"id": "11111111-1111-1111-1111-111111111111",
"name": "Dev",
"online": true,
"twitchData": {
"id": 56475817,
"username": "heydevdev",
"photo": "https://static-cdn.jtvnw.net/jtv_user_pictures/cc0dddae-bbdd-4b1a-a6f7-9a718b4da633-profile_image-300x300.png"
}
},
"22222222-2222-2222-2222-222222222222": {
"id": "22222222-2222-2222-2222-222222222222",
"name": "Ash",
"online": true,
},
"33333333-3333-3333-3333-333333333333": {
"id": "33333333-3333-3333-3333-333333333333",
"name": "Ben",
"online": false,
}
}
}
msg
msg is fired when a user sends you a message. This is generally done in response to a button press.
{
"event": "msg",
"payload": {
"from": "11111111-1111-1111-1111-111111111111",
"event": "PickSix",
"message": {
"event": "PickSix",
"value": ["B", "D", "A", "F", "E", "C"]
},
"timestamp": 1769260462112
}
}
change
The change event is identical in shape to the msg event, however it represents a work in progress. The user hasn't explicitly submitted their answer; they are simply modifying a field. This can be useful if you want to accept a user's current selection when a timer expires.
{
"event": "change",
"payload": {
"from": "11111111-1111-1111-1111-111111111111",
"event": "PickSix",
"message": {
"event": "PickSix",
"value": ["B", "D", "A"] // Player has only selected three of six answers.
},
"timestamp": 1769260462101
}
}
4. Send UI payloads
With the event listeners set up, you should be receiving the state.host payload whenever a new user joins your room on hackbox. But, their screen will only display a welcome message for now. It's up to your host to send payloads to customize their game screens.
Here's a quick example payload that will display a single buzzer button on the player's screen.
{
"to": ["11111111-1111-1111-1111-111111111111"], // Array of IDs of all users that should receive this message.
"data": {
{
"ui": {
"main": {
"components": [
{
"type": "Button",
"props": {
"event": "MyFirstEvent",
"label": "Buzz in",
"value": "buzz"
}
}
]
}
}
}
}
}
If you've sent this event successfully, your players should see a "Buzz in" button on their screen. If your event listeners are set up correctly, when a player taps that button you will receive your first msg event with the following message:
{
"event": "MyFirstEvent",
"value": "buzz"
}
Next Steps
Congratulations! You're well on your way to creating your first Hackbox game! Next up, take a quick read through our game design best practices, or hit the playground and build some UI!