Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-09 16:13:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: (backport) Bring the main doc pages up to date, and add more examples (#2094)

Browse Source
This commit is contained in:
Isabella
2018-04-26 01:13:44 -05:00
parent feb0991c46
commit d7e7803178
11 changed files with 390 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
docs/examples/attachments.md Normal file
View File

@@ -0,0 +1,163 @@
# Sending Attachments
In here you'll see a few examples showing how you can send an attachment using discord.js.
## Sending an attachment using a URL
There are a few ways you can do this, but we'll show you the easiest.
The following examples use [Attachment](/#/docs/main/stable/class/Attachment).
```js
// Extract the required classes from the discord.js module
const { Client, Attachment } = require('discord.js');
// Create an instance of a Discord client
const client = new Client();
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
client.on('message', message => {
// If the message is '!rip'
if (message.content === '!rip') {
// Create the attachment using Attachment
const attachment = new Attachment('https://i.imgur.com/w3duR07.png');
// Send the attachment in the message channel
message.channel.send(attachment);
}
});
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');
```
And here is the result:
![Image showing the result](/static/attachment-example1.png)
But what if you want to send an attachment with a message content? Fear not, for it is easy to do that too! We'll recommend reading [the TextChannel's "send" function documentation](/#/docs/main/stable/class/TextChannel?scrollTo=send) to see what other options are available.
```js
// Extract the required classes from the discord.js module
const { Client, Attachment } = require('discord.js');
// Create an instance of a Discord client
const client = new Client();
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
client.on('message', message => {
// If the message is '!rip'
if (message.content === '!rip') {
// Create the attachment using Attachment
const attachment = new Attachment('https://i.imgur.com/w3duR07.png');
// Send the attachment in the message channel with a content
message.channel.send(`${message.author},`, attachment);
}
});
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');
```
And here's the result of this one:
![Image showing the result](/static/attachment-example2.png)
## Sending a local file or buffer
Sending a local file isn't hard either! We'll be using [Attachment](/#/docs/main/stable/class/Attachment) for these examples too.
```js
// Extract the required classes from the discord.js module
const { Client, Attachment } = require('discord.js');
// Create an instance of a Discord client
const client = new Client();
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
client.on('message', message => {
// If the message is '!rip'
if (message.content === '!rip') {
// Create the attachment using Attachment
const attachment = new Attachment('./rip.png');
// Send the attachment in the message channel with a content
message.channel.send(`${message.author},`, attachment);
}
});
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');
```
The results are the same as the URL examples:
![Image showing result](/static/attachment-example1.png)
But what if you have a buffer from an image? Or a text document? Well, it's the same as sending a local file or a URL!
In the following example, we'll be getting the buffer from a `memes.txt` file, and send it in the message channel.
You can use any buffer you want, and send it. Just make sure to overwrite the filename if it isn't an image!
```js
// Extract the required classes from the discord.js module
const { Client, Attachment } = require('discord.js');
// Import the native fs module
const fs = require('fs');
// Create an instance of a Discord client
const client = new Client();
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
client.on('message', message => {
// If the message is '!memes'
if (message.content === '!memes') {
// Get the buffer from the 'memes.txt', assuming that the file exists
const buffer = fs.readFileSync('./memes.txt');
/**
* Create the attachment using Attachment,
* overwritting the default file name to 'memes.txt'
* Read more about it over at
* http://discord.js.org/#/docs/main/stable/class/Attachment
*/
const attachment = new Attachment(buffer, 'memes.txt');
// Send the attachment in the message channel with a content
message.channel.send(`${message.author}, here are your memes!`, attachment);
}
});
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');
```
And of course, the results are:
![Attachment File example 3](/static/attachment-example3.png)

19
docs/examples/avatars.js
View File

@@ -1,6 +1,6 @@
/*
Send a user a link to their avatar
*/
/**
* Send a user a link to their avatar
*/
// Import the discord.js module
const Discord = require('discord.js');
@@ -8,11 +8,10 @@ const Discord = require('discord.js');
// Create an instance of a Discord client
const client = new Discord.Client();
// The token of your bot - https://discordapp.com/developers/applications/me
const token = 'your bot token here';
// The ready event is vital, it means that your bot will only start reacting to information
// from Discord _after_ ready is emitted
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
@@ -26,5 +25,5 @@ client.on('message', message => {
}
});
// Log our bot in
client.login(token);
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');

38
docs/examples/embed.js Normal file
View File

@@ -0,0 +1,38 @@
/**
* An example of how you can send embeds
*/
// Extract the required classes from the discord.js module
const { Client, RichEmbed } = require('discord.js');
// Create an instance of a Discord client
const client = new Client();
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
client.on('message', message => {
// If the message is "how to embed"
if (message.content === 'how to embed') {
// We can create embeds using the MessageEmbed constructor
// Read more about all that you can do with the constructor
// over at https://discord.js.org/#/docs/main/stable/class/RichEmbed
const embed = new RichEmbed()
// Set the title of the field
.setTitle('A slick little embed')
// Set the color of the embed
.setColor(0xFF0000)
// Set the main content of the embed
.setDescription('Hello, this is a slick embed!');
// Send the embed to the same channel as the message
message.channel.send(embed);
}
});
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');

19
docs/examples/greeting.js
View File

@@ -1,6 +1,6 @@
/*
A bot that welcomes new guild members when they join
*/
/**
* A bot that welcomes new guild members when they join
*/
// Import the discord.js module
const Discord = require('discord.js');
@@ -8,11 +8,10 @@ const Discord = require('discord.js');
// Create an instance of a Discord client
const client = new Discord.Client();
// The token of your bot - https://discordapp.com/developers/applications/me
const token = 'your bot token here';
// The ready event is vital, it means that your bot will only start reacting to information
// from Discord _after_ ready is emitted
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
@@ -27,5 +26,5 @@ client.on('guildMemberAdd', member => {
channel.send(`Welcome to the server, ${member}`);
});
// Log our bot in
client.login(token);
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');

145
docs/examples/moderation.md Normal file
View File

@@ -0,0 +1,145 @@
# Moderation
In here, you'll see some basic examples for kicking and banning a member.
## Kicking a member
Let's say you have a member that you'd like to kick. Here is an example of how you *can* do it.
```js
// Import the discord.js module
const Discord = require('discord.js');
// Create an instance of a Discord client
const client = new Discord.Client();
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
client.on('message', message => {
// Ignore messages that aren't from a guild
if (!message.guild) return;
// If the message content starts with "!kick"
if (message.content.startsWith('!kick')) {
// Assuming we mention someone in the message, this will return the user
// Read more about mentions over at https://discord.js.org/#/docs/main/stable/class/MessageMentions
const user = message.mentions.users.first();
// If we have a user mentioned
if (user) {
// Now we get the member from the user
const member = message.guild.member(user);
// If the member is in the guild
if (member) {
/**
* Kick the member
* Make sure you run this on a member, not a user!
* There are big differences between a user and a member
*/
member.kick('Optional reason that will display in the audit logs').then(() => {
// We let the message author know we were able to kick the person
message.reply(`Successfully kicked ${user.tag}`);
}).catch(err => {
// An error happened
// This is generally due to the bot not being able to kick the member,
// either due to missing permissions or role hierarchy
message.reply('I was unable to kick the member');
// Log the error
console.error(err);
});
} else {
// The mentioned user isn't in this guild
message.reply('That user isn\'t in this guild!');
}
// Otherwise, if no user was mentioned
} else {
message.reply('You didn\'t mention the user to kick!');
}
}
});
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');
```
And the result is:
![Image showing the result](/static/kick-example.png)
## Banning a member
Banning works the same way as kicking, but it has slightly more options that can be changed.
```js
// Import the discord.js module
const Discord = require('discord.js');
// Create an instance of a Discord client
const client = new Discord.Client();
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
client.on('message', message => {
// Ignore messages that aren't from a guild
if (!message.guild) return;
// if the message content starts with "!ban"
if (message.content.startsWith('!ban')) {
// Assuming we mention someone in the message, this will return the user
// Read more about mentions over at https://discord.js.org/#/docs/main/stable/class/MessageMentions
const user = message.mentions.users.first();
// If we have a user mentioned
if (user) {
// Now we get the member from the user
const member = message.guild.member(user);
// If the member is in the guild
if (member) {
/**
* Ban the member
* Make sure you run this on a member, not a user!
* There are big differences between a user and a member
* Read more about what ban options there are over at
* https://discord.js.org/#/docs/main/stable/class/GuildMember?scrollTo=ban
*/
member.ban({
reason: 'They were bad!',
}).then(() => {
// We let the message author know we were able to ban the person
message.reply(`Successfully banned ${user.tag}`);
}).catch(err => {
// An error happened
// This is generally due to the bot not being able to ban the member,
// either due to missing permissions or role hierarchy
message.reply('I was unable to ban the member');
// Log the error
console.error(err);
});
} else {
// The mentioned user isn't in this guild
message.reply('That user isn\'t in this guild!');
}
} else {
// Otherwise, if no user was mentioned
message.reply('You didn\'t mention the user to ban!');
}
}
});
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');
```
And the result is:
![Image showing the result](/static/ban-example.png)

19
docs/examples/ping.js
View File

@@ -1,6 +1,6 @@
/*
A ping pong bot, whenever you send "ping", it replies "pong".
*/
/**
* A ping pong bot, whenever you send "ping", it replies "pong".
*/
// Import the discord.js module
const Discord = require('discord.js');
@@ -8,11 +8,10 @@ const Discord = require('discord.js');
// Create an instance of a Discord client
const client = new Discord.Client();
// The token of your bot - https://discordapp.com/developers/applications/me
const token = 'your bot token here';
// The ready event is vital, it means that your bot will only start reacting to information
// from Discord _after_ ready is emitted
/**
* The ready event is vital, it means that only _after_ this will your bot start reacting to information
* received from Discord
*/
client.on('ready', () => {
console.log('I am ready!');
});
@@ -26,5 +25,5 @@ client.on('message', message => {
}
});
// Log our bot in
client.login(token);
// Log our bot in using the token from https://discordapp.com/developers/applications/me
client.login('your token here');

6
docs/examples/webhook.js
View File

@@ -1,6 +1,6 @@
/*
Send a message using a webhook
*/
/**
* Send a message using a webhook
*/
// Import the discord.js module
const Discord = require('discord.js');

4
docs/general/faq.md
View File

@@ -12,10 +12,10 @@ Update to Node.js 6.0.0 or newer.
node-opus is greatly preferred, due to it having significantly better performance.
## How do I install FFMPEG?
- **npm:** `npm install --save ffmpeg-binaries`
- **npm:** `npm install ffmpeg-binaries`
- **Ubuntu 16.04:** `sudo apt install ffmpeg`
- **Ubuntu 14.04:** `sudo apt-get install libav-tools`
- **Windows:** See the [FFMPEG section of AoDude's guide](https://github.com/bdistin/OhGodMusicBot/blob/master/README.md#download-ffmpeg).
- **Windows:** `npm install ffmpeg-binaries` or see the [FFMPEG section of AoDude's guide](https://github.com/bdistin/OhGodMusicBot/blob/master/README.md#download-ffmpeg).
## How do I set up node-opus?
- **Ubuntu:** Simply run `npm install node-opus`, and it's done. Congrats!

1
docs/general/welcome.md
View File

@@ -10,6 +10,7 @@
<a href="https://www.npmjs.com/package/discord.js"><img src="https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600" alt="NPM downloads" /></a>
<a href="https://travis-ci.org/discordjs/discord.js"><img src="https://travis-ci.org/discordjs/discord.js.svg" alt="Build status" /></a>
<a href="https://david-dm.org/discordjs/discord.js"><img src="https://img.shields.io/david/discordjs/discord.js.svg?maxAge=3600" alt="Dependencies" /></a>
<a href="https://www.patreon.com/discordjs"><img src="https://img.shields.io/badge/donate-patreon-F96854.svg" alt="Patreon" /></a>
</p>
<p>
<a href="https://nodei.co/npm/discord.js/"><img src="https://nodei.co/npm/discord.js.png?downloads=true&stars=true" alt="NPM info" /></a>

6
docs/index.yml
View File

@@ -18,7 +18,13 @@
path: ping.js
- name: Avatars
path: avatars.js
- name: Attachments
path: attachments.md
- name: Server greeting
path: greeting.js
- name: Message Embed
path: embed.js
- name: Moderation
path: moderation.md
- name: Webhook
path: webhook.js

6
docs/topics/voice.md
View File

@@ -4,12 +4,16 @@ Voice in discord.js can be used for many things, such as music bots, recording o
In discord.js, you can use voice by connecting to a `VoiceChannel` to obtain a `VoiceConnection`, where you can start streaming and receiving audio.
To get started, make sure you have:
* ffmpeg - `npm install ffmpeg-binaries`
* FFmpeg - `npm install ffmpeg-binaries`
* an opus encoder, choose one from below:
* `npm install opusscript`
* `npm install node-opus`
* a good network connection
The preferred opus engine is node-opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose node-opus.
Using opusscript is only recommended for development environments where node-opus is tough to get working.
For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers.
## Joining a voice channel
The example below reacts to a message and joins the sender's voice channel, catching any errors. This is important
as it allows us to obtain a `VoiceConnection` that we can start to stream audio with.