switchchat
Advanced tools
SwitchCraft Chatbox v2 module for Node.js written in TypeScript
npm i switchchat
In-depth documentation can be found at docs.sc3.io:
This example will show you how to connect to the SwitchCraft Chatbox API with a basic Hello World bot.
/chatbox license in-game. You can click the token to copy it to
your clipboard.npm init, and install SwitchChat by running npm i switchchat.
package.json and set "type": "module".index.js with the following code:// Import SwitchChat
import {Client} from "switchchat";
// Create the Chatbox client
const sc = new Client("YOUR-CHATBOX-TOKEN", {
// Optional - set the default name and markdown formatting mode for all `.say()` and `.tell()` calls
defaultName: "Hello World Bot",
defaultFormattingMode: "markdown",
});
// Add event listener for when a backslash command is received
sc.on("command", async (cmd) => {
// Only respond if the command is `\helloworld`
if (cmd.command === "helloworld") {
// Send message back to the user: "Hello World!"
await sc.tell(cmd.user.name, "Hello World!");
}
});
// Event listener for when the client is connected to SwitchCraft and ready to
// receive messages and events
sc.on("ready", () => {
console.log("Connected!");
});
// Connect to SwitchCraft
sc.connect();
node index.js. When it says "Connected!", run
\helloworld in-game, and the Chatbox should respond to you!You are able to listen after the following events, which directly map to the events sent by the Chatbox websocket API:
| Friendly name | Name | Trigger |
|---|---|---|
| In-game chat | chat_ingame | A player sent a message in-game |
| Discord chat | chat_discord | A player sent a message from Discord |
| Chatbox message | chat_chatbox | A chatbox sent a public message |
| Chatbox command | command | A player sent a chatbox command in-game |
| Join | join | A player joined the server |
| Leave | leave | A player left the server |
| Death | death | A player died |
| World change | world_change | A player changed worlds |
| AFK | afk | A player went AFK |
| AFK return | afk_return | A player returned from being AFK |
| Restart scheduled | server_restart_scheduled | The server will restart soon |
| Restart cancelled | server_restart_cancelled | The scheduled server restart was cancelled |
User that went AFK(Websocket API docs – API reference)
The event received when a player posts a message in public chat.
string of the contents of the chat messagestring of the raw contents of the chat messageRenderedTextObject of the rendered text of the chat messageUser that sent the message(Websocket API docs – API reference)
The event received when a player posts a message in Discord.
string of the contents of the chat message, without formatting codesstring of the raw contents of the chat message, with its original formatting codesRenderedTextObject of the rendered text of the chat messagestring of the Discord snowflake ID of the messageDiscordUser that sent the messageboolean if the message has been edited(Websocket API docs – API reference)
The event received when another chatbox sends a message.
string of the contents of the message, without formatting codesstring of the raw contents of the message, with its original formatting codesRenderedTextObject of the rendered text of the messageUser of the owner of the chatboxstring name of the chatbox, without formatting codesstring name of the chatbox, with its original formatting codes(Websocket API docs – API reference)
The event received when a player runs a chatbox command (public backslash commands: \command, private owner-only
caret/pipe commands: ^command) in-game. The command capability is required to receive command events.
User that ran the chatbox commandstring arguments after the command.boolean if the command is an owner-only command (^command)(Websocket API docs – API reference)
The event received when a player joins the game.
User that joined the server(Websocket API docs – API reference)
The event received when a player leaves the game.
User that left the server(Websocket API docs – API reference)
The event received when a player dies in-game.
string of the death message contents, without formatting codesstring of the death message contents, with its original formatting codesRenderedTextObject of the death messageUser that diedUser | null that killed the user. Only set if they were killed by another player(Websocket API docs – API reference)
The event received when a player changes worlds.
User that changed worldsstring of the world the player moved fromstring of the world the player is now in(Websocket API docs – API reference)
The event received when a player goes AFK in-game.
User that goes AFK(Websocket API docs – API reference)
The event received when a player returns from being AFK in-game.
(Websocket API docs – API reference)
The event received when a server restart has been scheduled. At the time of restartAt, the server will restart and the
SwitchChat client will be disconnected.
If a server restart was scheduled before the websocket connected, then the server_restart_scheduled event will be
sent after the hello/ready events. In this case, restartSeconds will not be the time until the restart, but
instead the time that was initially specified for the restart. time will still be the initial time the restart was
scheduled, and restartAt will be the time the restart will happen.
string that tells you what type of restart it is ("automatic" or "manual")number that tells you how many seconds until the restartDate that tells you when the restart will happen(Websocket API docs – API reference)
The event received when a previously scheduled server restart has now been cancelled.
string that tells you what type of restart it was ("automatic" or "manual")The Chatbox server has a ratelimit of 500ms per license, with up to 5 messages queued at once.
When the methods client.say and client.tell are called, the data is enqueued internally before being sent to the server.
This internal queue makes it safe to go well over the limits, because it processes each message every 500ms to avoid hitting the rate limit of the server.
You are also able to listen after these packets that are sent by SwitchCraft to the client.
| Friendly name | Name | Trigger |
|---|---|---|
| Hello packet | ready | When SwitchChat has successfully connected to SwitchCraft |
| Player list packet | players | When you connect, and when a player joins/leaves |
| Error packet | error | When there is an error |
| Closing packet | closing | When the server is closing the connection |
(Websocket API docs – API reference)
boolean that says if you are authenticated with the guest keystring that represents who owns the chatbox licenseUser that represents who owns the chatbox license, or null if this is a guest connectionstrings that can tell you what capabilities you have(Websocket API docs – API reference)
Users that are currently online on the server.(Websocket API docs – API reference)
string that tells you what type of error that occurred (possible errors).string that is a human-readable version of error.(Websocket API docs – API reference)
string reason for closing the connection (possible values).string that is a human-readable version of closeReasonYou can run these methods on your Client instance.
(Websocket API docs – API reference)
await client.say(text, name, mode)Sends a message to the in-game public chat. Returns a Promise that resolves to a
Success object, which will tell you if the message
was sent (reason is "message_sent").
| Argument | Type | Description |
|---|---|---|
text | string | The message to send. |
name | string (optional) | The name of the chatbox to show. If no name is specified, it will default to the username of the license owner, or client.defaultName. |
mode | FormattingMode (optional) | The formatting mode to use ("markdown" or "format"). Defaults to client.defaultFormattingMode or "markdown". |
(Websocket API docs – API reference)
await client.tell(user, text, name, mode)Sends a private message to an in-game player. Returns a Promise that resolves to a
Success object, which will tell you if the message
was sent (reason is "message_sent").
| Argument | Type | Description |
|---|---|---|
user | string, User | The username, UUID or the User object of the user to send the message to. |
text | string | The message to send. |
name | string (optional) | The name of the chatbox to show. If no name is specified, it will default to the username of the license owner, or client.defaultName. |
mode | FormattingMode (optional) | The formatting mode to use ("markdown" or "format"). Defaults to client.defaultFormattingMode or "markdown". |
client.connect()Connects to SwitchCraft.
client.close()Disconnects the connection to SwitchCraft.
client.reconnect()Reconnects to SwitchCraft.
(Websocket API docs – API reference)
The user object represents an in-game player.
name."default", "moderator" or "admin"./pronouns. This may be
null if the player has not set any preferred pronouns. Where reasonably possible, you should attempt to use the
user's preferred pronouns, or avoid using pronouns entirely. If you are unable to do this, you should use the player's
name instead.null if this information is not available. It will be a Minecraft namespaced
registry key, for example:
minecraft:overworld - The overworldminecraft:the_nether - The Netherminecraft:the_end - The End0 if the player is not a
supporter or has opted out of showing their supporter tag, 1 for a Tier 1 supporter, 2 for a Tier 2 supporter, and
3 for a Tier 3 supporter.(Websocket API docs – API reference)
The Discord user object represents a user on Discord.
(Websocket API docs – API reference)
Minecraft's serialised raw JSON text format. See the SwitchCraft documentation for more information on how this is used.
The mode to use for outgoing chatbox messages (.say(), .tell()).
&e for yellow). Supports colours, but not URLs.FAQs
Framework for the SwitchCraft Chatbox v2
We found that switchchat demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.