Skip to content
Programmatically interact with in realtime.
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

bingosync-api npm Build Status

Programmatically interact with in realtime.


Bingosync is a great tool for speedrunners looking to play just about any kind of bingo they can imagine. And, since it is backed by a realtime websocket, it's a great source of data for other applications to consume. However, its API isn't the easiest, and creating a reliable websocket connection that can recover from unforeseen issues is challenging. So, we created this package to present a simplified and robust API for interacting with Bingosync deployments.


npm install --save @gamesdonequick/bingosync-api


import { Bingosync } from "@gamesdonequick/bingosync-api";
const bingosync = new Bingosync();

// Set up the event listener which will receive the board state updates.
bingosync.on("board-changed", boardState => {
	// boardState is an object with one key, called `cells`.
	// `cells` are objects structured like this:
	// interface BoardCell {
	// 	slot: string;
	// 	colors: CellColor[];
	// 	name: string;
	// }
	// So, to log every property of every cell, you could do the following:
	boardState.cells.forEach(cell => {
		console.log(cell.slot); // Examples: "slot1", "slot2", ..., "slot25", etc.
		console.log(cell.colors); // Examples: [] when a cell is blank, ["blue"], ["blue", "green"], etc.
		console.log(; // Whatever the displayed name of that cell is.

// Set up an error handler to be informed of runtime issues.
// If you don't attach this handler, errors will be silently discarded.
bingosync.on("error", error => {
	console.error("something went wrong:", error);

// Connect to the room.
		roomCode: "c72KEvf1CsRZSjze1kg6HQ",
		passphrase: "your_cool_password",
		playerName: "Node.js",
	.then(() => {
		console.log("successfully connected to bingosync");
	.catch(error => {
		console.error("oh no something went wrong:", error);

// If you want to kill the connection:

Connecting to alternate deployments of Bingosync

Bingosync is open source, and you can run your own deployment of it! Here's how you'd use this library to connect to that:

		siteUrl: "",
		socketUrl: "ws://",
		roomCode: "c72KEvf1CsRZSjze1kg6HQ",
		passphrase: "your_cool_password",
		playerName: "Node.js",
	.then(() => {
			"successfully connected to our cool private deployment of bingosync on",
	.catch(error => {
		console.error("oh no something went wrong again:", error);


Currently only supports joining as a spectator, and is therefore read-only. It is not possible to make changes to the board with this package yet, but this could be added if enough people need it.

You can’t perform that action at this time.