Sending & Receiving Messages

Once connected to a room, you can send and receive messages in real-time.

Sending Messages

Send messages to the room. Messages are encoded with MsgPack and can hold any JSON-serializable data.

client.ts

//
// sending message with string type
//
room.send("move", { direction: "left"});
 
//
// sending message with number type
//
room.send(0, { direction: "left"});

Client.cs

//
// sending message with string type
//
await room.Send("move", new { direction = "left" });
 
//
// sending message with number type
//
await room.Send(0, new { direction = "left" });

client.lua

--
-- sending message with string type
--
room:send("move", { direction = "left" })
 
--
-- sending message with number type
--
room:send(0, { direction = "left" })

client.hx

//
// sending message with string type
//
room.send("move", { direction: "left" });
 
//
// sending message with number type
//
room.send(0, { direction: "left" });

client.gd

# sending message with string type
room.send_message("move", {"direction": "left"})
 
# sending message with number type
room.send_message(0, {"direction": "left"})

client.dart

//
// sending message with string type
//
room.send('move', {'direction': 'left'});
 
//
// sending message with number type
//
room.sendInt(0, {'direction': 'left'});

Backend: See Room → Message Handling for detailed documentation on receiving messages from the client.

Send Raw Bytes

For custom encoding, send a Uint8Array of raw bytes.

client.js

//
// sending message with number type
//
room.sendBytes(0, new Uint8Array([ 172, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]));
 
//
// sending message with string type
//
room.sendBytes("some-bytes", new Uint8Array([ 172, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]));

⚠️

The payload must be a Uint8Array. A plain number[] array silently sends an empty message, since the SDK reads .byteLength from the payload.

Receiving Messages

Listen for messages sent from the server.

client.ts

room.onMessage("powerup", (message) => {
  console.log("message received from server");
  console.log(message);
});

Client.cs

class PowerUpMessage {
  string kind;
}
 
room.OnMessage<PowerUpMessage>("powerup", (message) => {
  Debug.Log ("message received from server");
  Debug.Log(message);
});

client.lua

room:on_message("powerup", function(message)
  print("message received from server")
  print(message)
end)

client.hx

room.onMessage("powerup", function(message) {
  trace("message received from server");
  trace(Std.string(message));
});

client.gd

room.message_received.connect(_on_message_received)
 
func _on_message_received(type: Variant, message: Variant):
    print("message received from server")
    print(message)

client.dart

room.onMessage('powerup').listen((message) {
  print('message received from server');
  print(message);
});

Backend: To send a message from the server to a client, use client.send() or room.broadcast().

Request/Response

Send a message and await the server’s reply. The server answers by returning a value from its matching message handler.

client.ts

//
// Promise form: room.request(type, payload)
//
const profile = await room.request("get-profile", { userId: 42 });
 
//
// Override the default timeout (10s) per request
//
const result = await room.request("slow-task", { id }, { timeout: 30_000 });
 
//
// Callback form: pass a 3rd argument to room.send()
//
room.send("get-profile", { userId: 42 }, (profile, error) => {
    if (error) { return console.error(error); }
    console.log(profile);
});

The promise rejects (or the callback receives an error) when the handler throws or no handler is registered for that type. Rejection also happens when the connection closes first, or when no reply arrives within the timeout. The default timeout is Room.defaultRequestTimeout (10000 ms), overridable per request via the timeout option.

The server may also deliberately reject a request via ctx.reject(reason): a business-logic “no”, distinct from an error. The rejection arrives as an Error with name: "rejected", and the server’s raw reason on its .reason property:

client.ts

try {
    await room.request("join-team", { team: "red" });
} catch (e: any) {
    if (e.name === "rejected") {
        console.log(e.reason); // => { code: "TEAM_FULL", team: "red" }
    }
}

Pass mode: "unreliable" in the options to send the request over the unreliable channel, when the transport has one. A genuine packet drop is then surfaced by the timeout.

Request/response is currently available in the JavaScript/TypeScript SDK.

Client SDK Connection Lifecycle