Grumble Download

Developers

Build for Grumble.

Bots, slash commands, webhooks and apps. Grumble speaks the same API as Discord, so the libraries you already know work here too.

Sign in and make a bot Read the docs

Already have a Discord bot?

Point it at Grumble.

Your bot's code can stay as it is. Change where it sends requests and where it connects, and it logs in, joins its servers and registers its slash commands. Here's what changes.

discord.jsone line
const { Client, GatewayIntentBits } = require("discord.js");

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
  rest: { api: "https://grumble.gg/api" },});

client.on("messageCreate", (m) => {
  if (m.content === "!ping") m.reply("pong 🐾");
});

client.login(process.env.GRUMBLE_TOKEN);

discord.js asks Grumble where its gateway is, so the API address is all it needs.

discord.pytwo lines
import discord, yarl

discord.http.Route.BASE = "https://grumble.gg/api/v10"discord.gateway.DiscordWebSocket.DEFAULT_GATEWAY = yarl.URL("wss://grumble.gg/gateway/")
intents = discord.Intents.default()
intents.message_content = True
client = discord.Client(intents=intents)

@client.event
async def on_message(message):
    if message.content == "!ping":
        await message.reply("pong 🐾")

client.run(os.environ["GRUMBLE_TOKEN"])

Set both. discord.py doesn't ask the server where its gateway is, so if you leave the second line out, your bot tries to log in to Discord with its Grumble token.

Tested with discord.js, discord.py, serenity, JDA and Discord.Net, directly and in encrypted servers. See how each one did, and what to change in each. Other libraries work the same way. Change the API address, and the gateway address if the library has its own.

Encrypted servers need the bridge. Grumble's servers are end-to-end encrypted and our servers never hold the keys, so through the API alone a bot gets their messages, names and command options still encrypted. The Grumble bridge fixes that. It's a small program that runs next to your bot, holds its keys on your machine, and serves your bot this same API with everything decrypted. Your bot points at the bridge instead. Run it with npx grumble-bridge.

Make a bot

Three steps, about two minutes.

  1. 1

    Create an application

    Open the Developer Portal. In the Grumble app it's under Settings, and on the web it's at developers.grumble.gg, where you sign in with your Grumble account. Click New application and agree to the Developer Terms.

  2. 2

    Add a bot and copy its token

    On the Bot tab, click Add a bot. Copy the token straight away, because it's only shown once. It's how your code logs in, so keep it secret.

  3. 3

    Put it in a server

    On Add to a server, pick its permissions and one of your servers, or share its link so anyone can add it (if it's public).

What you can build

The whole toolbox.

Bots

A user your code logs in as. Get gateway events as they happen (messages, reactions, members, voice states) and act on them through the REST API.

Slash commands

Global or per-server commands with typed options. People type / and pick yours, and your bot answers right away or defers and follows up.

Buttons and forms

Put buttons and menus on your bot's messages and open pop-up forms. Clicks and answers arrive as interactions your bot replies to.

Webhooks

Post alerts, feeds and build results into a channel from anywhere, with just a URL. In a forum channel, each post starts a new thread.

Add-to-server links

OAuth2 links with the bot and applications.commands scopes and exactly the permissions your bot needs.

Slack and GitHub webhooks

Add /slack or /github to a webhook's URL, and anything that posts to a Slack webhook, or a GitHub repository's events, posts here.

Interactions over HTTP

Give your app an address and its commands and button presses arrive there, signed, with no gateway connection to keep open. Answer in the response.

Laid-out messages

Boxes with a coloured edge, sections with a picture or button beside them, galleries and separators, with the IS_COMPONENTS_V2 flag.

Familiar everything

Requests, responses, events, permissions and rate-limit headers follow Discord's API v10, so its documentation applies here too.

The essentials

API
https://grumble.gg/api/v10 (versions 6 to 10 are all accepted)
Gateway
wss://grumble.gg/gateway, also returned by GET /gateway/bot
Auth
Authorization: Bot <token>

Where Grumble differs from Discord

  • Encrypted servers. Messages, files, names and the options people type into commands are end-to-end encrypted. A bot reads and sends them through the Grumble bridge (npx grumble-bridge).
  • Voice. Bots join calls through the Grumble bridge, which speaks Discord's voice to them (so libraries like @discordjs/voice work) and Grumble's end-to-end encrypted calls to everyone else. Without the bridge, a bot can't be heard in a call.
  • Users carry less. There's no email, phone number or locale on anyone, bots included, because Grumble doesn't collect them.
  • Privileged intents (message content, members, presences) may need the server operator's approval.
  • No paid features. There are no premium tiers, entitlements or SKUs.
  • Some places are closed. Requests and gateway connections from the UK, Brazil, Turkey, Mississippi and Tennessee get 451, so don't host a bot there (why).
  • Safety. A message search for child sexual abuse material is refused with code 290008, and an upload of a known illegal file with 290002.

Make one of these

Bots people want.

Servers ask for these, and nobody's made them for Grumble yet. If you make one, or bring yours over, tell us and we'll point people to it. Grumble's own bots already do voice-time leaderboards, levels, tickets and reaction roles, and they're yours to copy.

Giveaways

A button to enter, a timer, and a fair draw announced at the end. Rerolls for winners who don't answer.

Starboard

Messages that get enough of one reaction copied to a channel of the server's best moments.

Birthdays

People add their own birthday (just the day and month), and get a wish and a role on the day.

Modmail

Someone messages the bot, and the server's team answers in a private thread, as one team, with notes and a log.

Live alerts

A post when a streamer goes live, a video goes up or a feed has something new. Webhooks make the posting easy.

Games

Counting, trivia, word chains and question of the day: small games a server plays together, with scores.

Building something?

Ask, share what you've made, and tell us what you'd build if Grumble had it, in Grumble Developers.

Join Grumble Developers