Skip to main content

Getting started with Discordeno

info

Discordeno is not intended for beginners, however you can still utilize it.

Installation​

You can install the npm package @discordeno/bot and this package will take care of setting up the REST & Gateway for your bot.

npm install @discordeno/bot # Using npm
yarn add @discordeno/bot    # Using yarn
pnpm add @discordeno/bot    # Using pnpm
bun add @discordeno/bot     # Using bun (as a package manager)

If you are using Deno you will need to still use the npm package, so you will need to use the npm: prefix in your imports.

Minimal bot that logins into Discord​

You can use @discordeno/bot as follows:

import { createBot, Intents } from '@discordeno/bot'

const bot = createBot({
  token: 'YOUR BOT TOKEN',
  intents: Intents.Guilds | Intents.GuildMessages, // Or other intents that you might needs.
  events: {
    ready: data => {
      bot.logger.info(`The shard ${data.shardId} is ready!`)
    },
  },
})

// You can add events after the createBot call if you prefer

bot.events.messageCreate = message => {
  // Do stuff with the message object ...
}

await bot.start()

This code will create a bot object with a specified token and Gateway Intents, in this case the ones for getting Guilds and Guilds messages.

You can check some other minimal examples with Node.JS, Deno or Bun if you want to know more on how to create and invite a Discord application or how to setup the use of environment variables instead of putting your token in your code.

Environment Variables

It is highly encouraged to use an environment variable instead of using a string in your code. You can check out different ways to do it in this guide

That way it makes it much harder to leak sensitive information and it easier to share with other people. Sensitive information are, but not limited to, your bot token

Excessive Intents

Adding intents that you don't use in the intent value on your bot configuration will result in performance degradation. Only use the intents that you need for your bot, especially when dealing with privileged intents. You can read more about intents and privileged intents on Discord documentation.

Send a message in a channel from Discordeno​

As well as managing your connection to the Discord gateway, Discordeno also manage HTTP/REST requests and rate limits (such as Invalid Request Limit aka Cloudflare ban) for you.

In Discordeno, you can call methods in the bot.helpers object to perform some actions on Discord. These methods will return objects that are different from the one returned by Discord, a notable example are the IDs. For IDs, Discord return a string with a number inside to avoid rounding errors in most languages, including JavaScript. However, in JavaScript, this issue can be avoided using BigInt. Therefore, before returning objects, Discordeno will transform most (if not every) IDs from a string to a BigInt. As for methods with parameters that accept an ID, most methods in the bot.helpers object will accept both a BigInt and a normal string.

For example, to send a message to a channel, you can call the bot.helpers.sendMessage method with the 2 required parameters:

  • The ID of the channel that you want to sent the message to
  • The options of your message
// Change the id below with one of the channels of one of the server your bot is in
const message = await bot.helpers.sendMessage(123123123123123123n, {
  content: 'Hello world. This is test message from Discordeno.',
})
Naming of functions in Discordeno

Most of the functions in Discordeno are explicit in what they do and named similar to what Discord calls the endpoint in the documentation.

Discordeno's methods always perform one action only. A method will never call multiple Discord endpoints.

Understanding Desired Properties in Discordeno​

tip

For more details checkout the desired properties docs

If we ran the code above (for example, by putting the code inside the ready event), the bot will send a message in the channel you specified (as long as it has the permissions to do so) with the content "Hello world. This is test message from Discordeno.". However, if we log to the console the message object that Discordeno return, we won't see many, if any, values on it. This is also the case for other events such as MessageCreate. But why is that? Well, this is because of a Discordeno feature called Desired properties.

Desired properties is a feature that reduce the memory usage of your application by removing properties that you don't use. For example, you might not be interested in knowing the topic of a channel, but Discord will always return it, therefore consuming more memory. This is why Discordeno requires you to explicitly set the properties that you want to keep and use.

The main way to configure desired properties is using the desiredProperties object in createBot:

const bot = createBot({
  // ... your exiting code
  desiredProperties: {
    message: {
      id: true,
      content: true,
      channelId: true,
    },
  },
})

With the above, we will be able to get the message ID, the channel ID and the message content* of messages, this means that if we now log the message object from before we will find these 3 values.

*: As long as the required privileged intent is enabled.

Additional information on Discordeno​

Here are some nice to know things about Discordeno that you might be interested, though some may be for more advanced use-cases.

Gateway methods​

If you want to edit some state such as your bot status, you will need to use the methods in bot.gateway. These methods will not return transformed objects so if you want to get transformed objects you will need to call the transformers yourself (the transformers are in bot.transformers).

OAuth2​

Some methods in bot.helpers will accept a Bearer token, or a Client ID and Client Secret. These OAuth2 methods will require you to setup the OAuth2 authorization flow. One example is the bot.helpers.getCurrentUser(bearerToken) method. This is a method that can not be called with a usual Bot token and require a OAuth2 token.

Discordeno includes some utilities (such as createOAuth2Link to create a OAuth2 authorization link) and methods to exchange your token as well as refresh your exiting token.

You can read more about OAuth2 in Discord on the documentation.

Use individual features from Discordeno separably​

While we do provide a @discordeno/bot package on npm with all features included, you might just need some of them. For this reason, Discordeno is split across multiple packages, which are the following:

  • @discordeno/bot: Groups all other packages as well as adding transformers and other functionalities on top.
  • @discordeno/rest: Only provide methods to send requests to Discord REST API as well as handling rate limits. This will provide the same object as bot.rest when you create a RestManager.
  • @discordeno/gateway: Only provide methods to establish and manage gateway connections to Discord. This will provide the same object as bot.gateway when you create a GatewayManager
  • @discordeno/utils: Only provide some utilities that are independent from other Discordeno features.
  • @discordeno/types: Only provide the Discord & Discordeno types used in all other packages.

It might make more sense to simply use @discordeno/bot, as the separate packages are mostly for advanced use cases.

Raw REST methods​

While we recommend using bot.helpers, you might find yourself in a situation where avoiding the transformers and desired properties can be beneficial. For this reason, you can use the methods in bot.rest. These methods will return the raw response from Discord but with the keys being camelCase instead of snake_case.