There are many different applications for Room Codes, however below we are going to dive into a high-level example of a single use case, a casual multiplayer game.

In this scenario, here are the specs we are looking at:

• 8 Players per room.
• The game involves players submitting questions and answers to each other.

1. First things first, a player will want to start a room.

The player, via your server, will hit our /requestroom endpoint. This will allocate a room, and provide the code back to you.

2. How you show the code is up to you, but it will then be up to your players to share the code with their friends who they want to join.

The user that first joins the room will be the "Host" of the room.

This means that their client will be responsible for managing the rooms lifetime, and in the "HostClient" broadcastType, it means they will recieve all client messages.

This could be as simple as showing the code in the user's client, or you could build ways to share it via Discord or other tools.

3. Once the other users have the code, they can start joining the room!

The specifics of how you build this is completely up to you!

Each user simply needs to hit the /joinroom endpoint using the room code you generated earlier.

They can do this from any client, they'll just need the room code, and the ability to generate a JWT to ensure you have authorised them to use the API.

4. We now have users in the room, now it's up to you to manage how the communication looks!

If the room is in the 'Broadcast' broadcast type, all users will receive all messages sent to each other. This can be perfect for a simple Peer-To-Peer experience.

If you want a little more control, you can use 'HostClient' broadcast type. This will route all messages from clients to a host user, and the host user broadcasts all of their messages to the users.

5. Now your users are playing, there is only one thing left: Room Lifecycle management.

By default, a room will last 5 minutes, from it's creation.

This can be extended by intervals of 5 minutes by using the /extendroom endpoint.

If the room expires before the /extendroom endpoint is used, the room is cleaned and closed!

All Room Codes end points use the same base URL, which also contains a version identifier.

The version number will only increase when any change implemented would break backwards compatibility in some way.

For now, there is simply just "v1".

https://room.codes/api/v1/

Authentication within Room Codes exists in two forms:

1. API Key Authentication

The API Key is only used to request a JWT. This makes it safer for you to provide client-side access to the API.

2. JWT (JsonWebToken) Authentication

All other endpoints within Room Codes expect a JWT to be provided.

For standard requests, its expected that the client token (or API key for /getclienttoken) will be provided in the Authorization Header as 'Bearer _YOUR_KEY/TOKEN_HERE_'

The only exception is for joining a room (the /joinroom endpoint). Due to this endpoint upgrading the client to a websocket, the token is expected to be provided as "token" query param in the request.

The goal of this endpoint is to allow you to generate a JWT that you can safely provide a client-side user, that has the following traits:

• Very short expiry. Token's generated from this endpoint expire after ONE (1) minute.
• Scoped usage. A client can only do exactly what you let them do, thanks to Scopes.

To avoid authentication errors, generate tokens just-in-time for each action (e.g., when joining or creating a room), rather than once at app startup.

It's highly recommended that you ensure there are some protections around who and how you generate JWT's, to avoid abuse from malicious users.

Do not generate JWTs directly from the client; always call your backend to request them.

{
    "scope": "request-room"
}

{
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySUQiOiI3OGJmMjc5My..."
}

Your API Key is important, and should be kept private and away from any client-facing code.

Your API Key can be found on your Room Codes Dashboard.

Scopes are used to determine what kind of 'work' can be done with any given JWT.

Only one scope can be provided per token, to limit the chance of token misuse.

There are three scopes available:

1. request-room - This scope is required for the /requestroom endpoint.
2. join-room - This scope is required for the /joinroom endpoint.
3. extend-room - This scope is required for the /extendroom endpoint.

Now we are really diving into Room Codes! It really just comes down to three very powerful endpoints.

1. / requestroom - Provisions a room on our end, and gives you a room code for joining.
2. / joinroom - Uses the room code created by /requestroom to connect all of your users together via WebSocket.
3. / extendroom - Extends the lifetime of the room requested by /requestroom.

When you use this endpoint, we provision a room for your users to join, and provide you with a room code to be used for joining the room.

{
    "codeLength": 4,
    "broadcastType": "Broadcast",
    "echo": true
}

{
    "code": "HZRW",
    "expirationTime": 1755579042503
}

There are two broadcast modes available in Room Codes, and they are declared in the configuration when the room is created (/requestroom endpoint).

1. Broadcast
2. HostClient

This endpoint is used to join an active room.

The first user to join any room using this endpoint becomes the host of the room. The host will recieve updates around the potential expiration of the room, and that user's client will be responsible for using the /extendroom endpoint to keep the room alive, if needed.

Importantly, if the host user disconnects, the room will be closed immediately.

The request is expecting a WebSocket connection.

This request must be initiated as a WebSocket upgrade (wss://). It cannot be called with a standard HTTP client

   const socket = new WebSocket(<JOIN_ROOM_CONNECTION_URL>);
        
    socket.onopen = function (event) {
        //Handles when the connection opens
    }
            
    socket.onmessage = function (event) {
        //Handles when the connection receives a message
    }
        
    socket.onclose = function (event) {
        //Handles when the connection closes
    }
        
    function sendMessage(message) {
        //Used to send a message back to the server.
        socket.send(message);
    }

After connection all messages sent via the WebSocket are either shared with other users, or the host, depending on the room type.

This endpoint is used to extend the lifespan of an active room.

When a room is created, by default it has a five minute lifespan. This lifespan can be extended perpetually by hitting the /extendroom endpoint.

Whenever /extendroom is called, the lifespan is increased by 5 minutes.

This call can be repeated as many times as need to reach the desired lifespan, or called as required for rooms with variable lifespans.

Room Codes is designed so that this endpoint is hit by the "host user's client". This avoids multiple clients having to manage who is extending the room, and also avoids the developer having to implement their own timer system.

{
    "room": "ABCDEF"
}

{
    "expirationTime": 1755579042503
}

Typically any errors that may occur are returned as JSON, with the 'error' attribute containing a message describing the error.

{
    "error": "This is a message that will attempt to describe the error."
}

Errors will be returned with their corresponding HTTP error codes. Some error codes that can be anticipated are listed below.

Always check the error field and the HTTP status code. Do not rely only on one.

Once you have a connection to the room via WebSocket, we switch to a different form of messaging.

Each time a user sends a message to the websocket, it's wrapped with some extra metadata to help identify the context of the message.

The message is then sent to other users depending on the rooms configuration settings.

Messages sent by your users to the WebSocket get wrapped in a response JSON object.

We recommend sending your messages as JSON strings. The server will wrap them and return them in the message field, so you can easily parse them on receipt.

However you can send your data in any form, and it will be returned in the message attribute.

{
    "type": "SYSTEM",
    "message": "{\"roomCode\":\"LOLO\",\"expirationTime\":1755578262614,\"broadcastType\":\"Broadcast\",\"echo\":true}",
    "code": {
        "code": "rc.100",
        "message": "Initial room joining update."
    }
}

Any errors returned to the user via the WebSocket will use the "type" of "SYSTEM", and it will provide an error code from the Message Codes table.

Room Codes WebSocket message codes are prefixed with "rc.", and are broken into four categories:

1. rc.1xx - Informational. Generally don't require action, just informative.
2. rc.2xx - User Generated. A user generated message triggered by a user sending a message to the WebSocket.
3. rc.4xx - API Usage Error. Generally an error caused by invalid usage of the API. Includes exceeding usage limits, or attempting to use an expired room.
4. rc.5xx - Server issue. Usually means there is an issue between the client and our servers, or on our end.

Below we dive more into the specific of each error category.

Some of these endpoints and actions have a "Usage Point" cost associated with them.

Accounts are provided with a daily allowance of tokens, depending on your subscription level.

For exact information on the token usages and subscription levels, check out the Pricing Page.

Your total point balance can be viewed while logged in, on the Dashboard.

If you attempt an action that will exceed your usage point balance, you will receive an error.

If you are on the Premium subscription plan, your daily usage points rollover, and accumulate over time.

As long as you maintain a subscription, the usage points are yours to keep. On cancellation your balance is frozen, for when you choose to resubscribe.

If you were on a Premium subscription, but changed back to free we don't wipe your balance, instead it's frozen.

If you choose to resubscribe, your frozen balance is immediately unfrozen, and accessible to you again.

NOTE: This feature does not apply to the free tier, as the tokens earned from free tier do not rollover.

For any questions or feedback, please reach out via one of the channels provided on the Contact page.

Thank you for using Room Codes!

All of your support, and feedback, are greatly appreciated!

We are always trying to improve Room Codes consistently and substantially, and we can only do that with your feedback.

Happy Coding!

- Josh from Hallway Digital, and Room Codes