Client¶
extends EventEmitter
This page contains documentation on the Discord.Client class. This should be used when you want to start creating things with the API.
Parameters¶
Client takes an options object, and supports the following options:.
autoReconnect¶
Have discord.js autoreconnect when connection is lost.
compress¶
Have Discord send a compressed READY packet.
forceFetchUsers¶
Make the library get all the users in all guilds, and delay the ready event until all users are received. This will slow down ready times and increase initial network traffic.
guildCreateTimeout¶
How long in milliseconds to wait for more guilds during the initial ready stream. Default is 1000ms. Increase this number if you are getting some serverCreated events right after ready.
largeThreshold¶
Set a custom large_threshold (the max number of offline members Discord sends in the initial GUILD_CREATE). The maximum is 250.
maxCachedMessages¶
The maximum number of messages to cache per channel. Decreasing this leads to more missing messageUpdated/messageDeleted events, increasing this leads to more RAM usage, especially over time.
rateLimitAsError¶
Have the lib throw a rejection Promise/callback when being ratelimited, instead of auto-retrying.
disableEveryone¶
Have the lib insert a zero width space between here and everyone mentions disabling them.
shardCount¶
The total number of shards.
shardId¶
A zero-based integer representing the value of the current shard.
Attributes¶
channels¶
A Cache of ServerChannel objects that the client has cached.
privateChannels¶
A Cache of PMChannel objects that the client has cached. These are all the Private/Direct Chats the client is in.
voiceConnections¶
A Cache of VoiceConnection objects that the client is in.
voiceConnection¶
Returns a VoiceConnection object, is an alias to voiceConnections[0].
readyTime¶
A Number unix timestamp dating to when the Client emitted ready.
uptime¶
A Number in milliseconds representing how long the Client has been ready for.
userAgent¶
An object containing url, version and full. Setting this property allows the discord developers to keep track of active bots, it defaults to the discord.js git repo and the current version of the package. url should be the repository/homepage of the creator. version should be the version of your bot. full is read only and will be automatically generated upon setting.
Functions¶
Note
Any functions used here that take callbacks as an optional parameter can also be used as Promises. Promises take the exact same parameters for each use case, except errors are moved to catch statements instead of then. For example, you can do:
bot.login(email, password).then(success).catch(err);
function success(token){
// handle success
}
function err(error){
// handle error
}
or use callbacks:
bot.login(email, password, function(error, token){
// handle error and success
});
login(email, password, callback)¶
Logs the client in so it can begin initialising. Use this after registering your events to ensure they are called!
email - The e-mail used to sign in, String.
password - The password used to sign in, String.
- callback - function that takes the following parameters:
- error - An error if any occurred
- token - The token received after logging in, String.
loginWithToken(token, email, password, callback)¶
Logs the client in, using just a token. The specified email and password are optional - they’re only needed when using updateDetails which requires them for authentication.
token - A valid Discord authentication token used to log in, String
email - (Optional) The e-mail used for later authentication, String.
password - (Optional) The password used for later authentication, String.
- callback - function that takes the following parameters:
- error - An error if any occurred
- token - A String containing the specified token. This is only used for compatibility with login, this token will always be identical to the specified one.
logout(callback)¶
Logs the client out and closes the WebSocket connections.
- callback - function that takes the following parameter:
- error - An error if any occurred
destroy(callback)¶
Similar to logout but should be used if you’re not going to create the Client again later in your program.
- callback - function that takes the following parameter:
- error - An error if any occurred
sendMessage(channel, content, options, callback)¶
Sends a message to the specified channel.
channel - a Channel Resolvable
content - (Optional if file is passed in options) a String Resolvable - the message you want to send
- options - (Optional) object containing:
tts - (Optional) Boolean, should message be text-to-speech
- file - (Optional) object, containing:
- file - a File Resolvable
- name - (Optional) String, filename to upload file as
- disableEveryone - (Optional) Boolean, disable here and everyone mentions
- callback - function that takes the following parameters:
- error - error object if any occurred
- message - the sent Message
sendTTSMessage(channel, content, callback)¶
An alias for sendMessage(channel, content, {tts: true}, callback)
sendFile(channel, attachment, name, content, callback)¶
Sends a file to the specified channel.
channel - a Channel Resolvable
attachment - A File Resolvable
name - (Optional) String, filename to upload file as
content - (Optional) String, text message to send with the attachment
- callback - function taking the following:
- error - error if any occurred
- message - the sent Message
reply(message, content, options, callback)¶
Shortcut to sendMessage but prepends a mention to the sender of the original message to the start of your message.
message - The Message to reply to
content - a String Resolvable - the message you want to send
- options - object containing:
- tts - Boolean, should message be text-to-speech
- callback - function that takes the following parameters:
- error - error object if any occurred
- message - the sent Message
replyTTS(message, content, callback)¶
An alias for reply(message, content, {tts: true}, callback)
awaitResponse(message, prompt, options, callback)¶
Wait for a response from the same user in the same channel as an existing message.
message - The original Message
prompt - a String Resolvable - a message you want to send to prompt the user
- options - object containing:
- tts - Boolean, should message be text-to-speech
- callback - function that takes the following parameters:
- error - error object if any occurred
- message - the sent Message
updateMessage(message, content, options, callback)¶
Updates the content of a previously sent message
message - The Message to update
content - a String Resolvable - the content you want to update the message with
- options - object containing:
- tts - Boolean, should message be text-to-speech
- callback - function that takes the following parameters:
- error - error object if any occurred
- message - the sent Message
deleteMessage(message, options, callback)¶
Attempts to delete a message
message - The Message Resolvable to delete
- options - object containing the following:
- wait - Milliseconds as a number to wait before deleting the message
- callback - function that takes the following parameters:
- error - error object if any occurred
deleteMessages(messages, callback)¶
Attempts to bulk delete messages from the same channel
message - Array of Message Resolvable to delete
- callback - function that takes the following parameters:
- error - error object if any occurred
getChannelLogs(channel, limit, options, callback)¶
Gets a list of previously sent messages in a channel.
channel - The Channel to get messages from
limit - The maximum amount of messages to retrieve - defaults to 50. A Number
- options - An object containing either of the following:
- before - A Message Resolvable - gets messages before this message.
- after - A Message Resolvable - gets messages after this message.
- callback - function taking the following:
- error - error if any occurred
- messages - array of Message objects sent in channel
getBans(server, callback)¶
Gets a list of banned users in a server.
server - Server Resolvable - The server to get banned users of
- callback - function taking the following:
- error - error if any occurred
- users - array of banned users in the server
joinServer(invite, callback)¶
Joins a server from the given invite. This will not work for OAuth bot accounts, you must use OAuth invite URLs instead.
invite - an Invite Resolvable
- callback - function taking the following:
- error - error if any occurred
- server - the joined Server
createServer(name, region, callback)¶
Creates a server
name - String, name of the server
region - String, region of the server, currently us-west, us-east, us-south, us-central, singapore, london, sydney, frankfurt or amsterdam
- callback - function taking the following:
- error - error if any occurred
- server - the created Server
updateServer(server, options, callback)¶
Updates the information, such as name or region, of a server the client is in
server - a Server Resolvable
- options - object containing (all optional):
- name - String, name of the server
- region - String, region of the server, currently us-west, us-east, us-south, us-central, singapore, london, sydney, frankfurt or amsterdam
- ownerID - a User Resolvable, user to transfer the server to (must be owner)
- icon - a Base64 Resolvable
- splash - a Base64 Resolvable (VIP only)
- verificationLevel - Number, a verification level (0, 1, 2, 3)
- afkChannelID - a Channel Resolvable, the AFK voice channel
- afkTimeout - Number, AFK timeout in seconds
- callback - function taking the following:
- error - error if any occurred
deleteServer(server, callback)¶
Deletes a server that the client is in
server - a Server Resolvable
- callback - function taking the following:
- error - error if any occurred
leaveServer(server, callback)¶
Leaves a server that the client is in
server - a Server Resolvable
- callback - function taking the following:
- error - error if any occurred
createChannel(server, name, type, callback)¶
Creates a channel in a server
server - a Server Resolvable
name - String, name of the channel. Spaces not allowed.
type - defaults to text, but can also be voice
- callback - function taking the following:
- error - error if any occurred
- channel - the created ServerChannel
deleteChannel(channel, callback)¶
Deletes a channel in a server.
channel - a Channel Resolvable to delete
- callback - function taking the following:
- error - error if any occurred.
banMember(user, server, length, callback)¶
Bans a user from a server.
user - A User Resolvable to ban
server - A Server Resolvable to ban the user from
length - Number, how many days to go back and delete messages from that user
- callback - function taking the following:
- error - error if any occurred.
unbanMember(user, server, callback)¶
Unbans a user from a server.
user - A User Resolvable to unban
server - A Server Resolvable to unban the user from
- callback - function taking the following:
- error - error if any occurred.
kickMember(user, server, callback)¶
Removes a user from a server
user - A User Resolvable to kick
server - A Server Resolvable to kick the user from
- callback - function taking the following:
- error - error if any occurred.
moveMember(user, channel, callback)¶
Moves a user from one voice channel into another.
user - A User Resolvable that should be moved
channel - The Channel Resolvable to move the user to
- callback - function taking the following:
- error - error if any occurred.
createInvite(channel, options, callback)¶
Creates an invite for the specified channel (or server)
channel - A Channel Resolvable
- options - object containing:
- maxAge - Number for maximum time in seconds for invite’s validity
- maxUses - Number, maximum uses of invite
- temporary - Boolean, whether the invite should be temporary
- xkcd - Boolean, whether the invite should be human-readable-friendly.
- callback - function taking the following:
- error - error if any occurred
- invite - the created Invite
getInvite(invite, callback)¶
Gets more info on a specific invite
invite - An Invite Resolvable
- callback - function taking the following:
- error - error if any occurred
- invite - an Invite object
getInvites(source, callback)¶
Gets all the invites in a channel/server
source - A Channel Resolvable or Server Resolvable
- callback - function taking the following:
- error - error if any occurred
- invite - Array of Invite objects
deleteInvite(invite, callback)¶
Deletes an invite
invite - An Invite Resolvable
- callback - a function taking the following:
- error - error if any occurred
setStatus(status, game, callback)¶
Sets the Discord Status of the Client
status - String, either
online, here, active, available
oridle, away
game - String, Name of game being played, or Object with the properties name url type, or null to clear
- callback - function taking the following:
- error - error if any occurred
setStatusOnline()¶
Aliases: setStatusHere, setStatusActive, setStatusAvailable
Sets the status of the Client to Online
setPlayingGame(game, callback)¶
Sets the Discord Status of the Client
game - String, Name of game being played, or null to clear
- callback - function taking the following:
- error - error if any occurred
setStreaming(name, url, type, callback)¶
Sets the Discord Status of the Client
name - String, Name of game being played
url - String, URL that it will link to
type - Number, 1 indicates streaming
- callback - function taking the following:
- error - error if any occurred
setChannelTopic(channel, topic, callback)¶
Sets the topic of a channel
channel - A Channel Resolvable
topic - A String
- callback - function taking the following:
- error - error if any occurred
setChannelName(channel, name, callback)¶
Sets the name of a channel
channel - A Channel Resolvable
name - A String
- callback - function taking the following:
- error - error if any occurred
setChannelNameAndTopic(channel, name, topic, callback)¶
Sets the name and topic of a channel
channel - A Channel Resolvable
name - A String
topic - A String
- callback - function taking the following:
- error - error if any occurred
setChannelUserLimit(channel, limit, callback)¶
Sets the user limit of a voice channel
channel - A Channel Resolvable
limit - A Number, user limit (0 - 99)
- callback - function taking the following:
- error - error if any occurred
setChannelBitrate(channel, bitrate, callback)¶
Sets the bitrate of a voice channel
channel - A Channel Resolvable
bitrate - A Number, bitrate (in kb/s) (8 - 96)
- callback - function taking the following:
- error - error if any occurred
updateChannel(channel, data, callback)¶
Updates the settings of a channel
channel - A Channel Resolvable
- details - object containing any of the following:
- name - String, the new name of channel
- topic - String, the new topic of the channel (TextChannel only)
- position - Number, the new position of the channel
- userLimit - Number, the new user limit of the channel (VoiceChannel only)
- bitrate - Number, the new bitrate (in kb/s) of the channel (VoiceChannel only)
- callback - function taking the following:
- error - error if any occurred
startTyping(channel, callback)¶
Marks the client as typing in a channel.
channel - A Channel Resolvable
- callback - function taking the following:
- error - error if any occurred
stopTyping(channel, callback)¶
Marks the client as not typing in a channel (takes a few seconds to go active).
channel - A Channel Resolvable
- callback - function taking the following:
- error - error if any occurred
updateDetails(details, callback)¶
Updates the details of the client
- details - object containing any of the following:
- avatar - Base64 Resolvable, new avatar of the client
- email - String, new email of the client
- newPassword - String, new password of the client
- username - String, new username of the client
- callback - function taking the following:
- error - error if any occurred
setAvatar(avatar, callback)¶
Sets the avatar of the client
avatar - Base64 Resolvable, new avatar of the client
- callback - function taking the following:
- error - error if any occurred
setUsername(name, callback)¶
Sets the username of the client
username - String, new username of the Client
- callback - function taking the following:
- error - error if any occurred
joinVoiceChannel(channel, callback)¶
Joins a Voice Channel to begin transmitting audio. If you have an OAuth bot account, you can connect to multiple voice channels at once, but only one per guild.
channel - A VoiceChannel Resolvable
- callback - function that takes the following:
- error - error if any occurred
- connection - VoiceConnection, the created Voice Connection.
leaveVoiceChannel(channel, callback)¶
Leaves the specified Voice Channel if connected
channel - A VoiceChannel Resolvable
- callback - function that takes the following:
- error - error if any occurred
createRole(server, data, callback)¶
Creates a new role in a server.
server - a Server Resolvable
data - object containing the structure below
- callback - function that takes the following:
- error - error if any occurred
- role - the created Role
// structure of data parameter (all attrs optional):
{
color : 0xFF0000,
hoist : false,
name : "A New Role!",
permissions : [
// see the constants documentation for full permissions
"attachFiles", "sendMessages"
],
mentionable: false
}
updateRole(role, data, callback)¶
Updates a role in a server.
role - a Role
data - an object taking the structure shown below
- callback - a function taking the following:
- error - error if any occurred
- role - the updated Role
// structure of data parameter (all attrs optional):
{
color : 0xFF0000,
hoist : false,
name : "A New Role!",
permissions : [
// see the constants documentation for full permissions
"attachFiles", "sendMessages"
],
mentionable: false
}
deleteRole(role, callback)¶
Deletes a role from a server
role - The Role to delete
- callback - function that takes the following:
- error - error if any occurred
addMemberToRole(member, role, callback)¶
Aliases : addUserToRole
Adds a member of a server to a role in the server
member - A User Resolvable
role - A Role Resolvable or an array of Role Resolvable
- callback - function that takes the following:
- error - error if any occurred
memberHasRole(member, role)¶
Aliases : userHasRole
Returns if a user has a role
- member - A User Resolvable
- role - A Role Resolvable or an array of Role Resolvable
removeMemberFromRole(member, role, callback)¶
Aliases : removeUserFromRole
Removes a member of a server from a role in the server
member - A User Resolvable
role - A Role Resolvable or an array of Role Resolvable
- callback - function that takes the following:
- error - error if any occurred
overwritePermissions(channel, roleOrUser, options, callback)¶
Overwrites the permissions of a role or a user in a channel
channel - a Channel Resolvable
options - an object containing a structure as shown below
- callback - function that takes the following:
- error - error if any occurred
{
"sendMessages" : false,
"attachFiles" : true
}
muteMember(user, server, callback)¶
Server-mutes a member.
user - A User Resolvable to mute
server - A Server Resolvable to mute the user in
- callback - function taking the following:
- error - error if any occurred.
unmuteMember(user, server, callback)¶
Server-unmutes a member.
user - A User Resolvable to unmute
server - A Server Resolvable to unmute the user in
- callback - function taking the following:
- error - error if any occurred.
deafenMember(user, server, callback)¶
Server-deafens a member.
user - A User Resolvable to deafen
server - A Server Resolvable to deafen the user in
- callback - function taking the following:
- error - error if any occurred.
undeafenMember(user, server, callback)¶
Server-undeafens a member.
user - A User Resolvable to undeafen
server - A Server Resolvable to undeafen the user in
- callback - function taking the following:
- error - error if any occurred.
setNickname(server, nickname, user, callback)¶
Set the nickname of a user on a server.
server - A Server Resolvable to set the nickname of the user in
nickname - string of the nickname
user - The User Resolvable to perform the nickname change on. If no user is specified, this will change the bot user’s nickname
- callback - function taking the following:
- error - error if any occurred.
Events¶
Discord.Client is an EventEmitter, so you can use .on() and .off() to add and remove events.
ready¶
Emitted when the client is ready to use
debug¶
Emitted when the client debugs or wants to log something internally
warn¶
Emitted when the client has encountered a small error that can be avoided.
messageDeleted¶
Emitted when a message has been deleted and the Client finds out, supplies a Message object IF available, and a Channel object.
messageUpdated¶
Emitted when a message has been updated and the client finds out. Supplies two Message objects, the first being the message before the update, the second being the new, updated message.
disconnected¶
Emitted when the client is disconnected from the Discord server.
error¶
Emitted when the client runs into a big problem, supplies an error object.
raw¶
Emitted when a message over WebSocket is received, it supplies one object containing the raw data from the WebSocket.
serverUpdated¶
Emitted when a server is updated (e.g. name change). Supplies two Server objects, the first being the server before the update, the second being the new, updated server.
channelCreated¶
Emitted when a channel is created, supplies a Channel object (includes PM chats as well as server channels).
channelUpdated¶
Emitted when a channel is updated (e.g. name/topic change). Supplies two Channel objects, the first being the channel before the update, the second being the new, updated channel.
serverRoleUpdated¶
Emitted when a role is updated in a server, supplies two Role objects. The first is the old role, the second is the updated role.
serverMemberRemoved¶
Emitted when a member is removed from a server. Supplies a Server object and a User object.
serverMemberUpdated¶
Emitted when a member in a server is updated. Supplies a Server object and 2 User objects, the first being the new, updated user, the second being the old one. The old user object could be null if the bot didn’t previously have the member cached.
presence¶
Emitted when a user goes online/offline/idle, starts/stops playing a game, or changes their username/avatar/similar. Supplies 2 User objects, the first being the old user, the second being the new, updated user.
userTypingStarted¶
Emitted when a user starts typing in a channel. Supplies two parameters, a User object and a Channel object.
userTypingStopped¶
Emitted when a user stop typing in a channel. Supplies two parameters, a User object and a Channel object.
userBanned¶
Emitted when a user is banned from a server. Supplies two parameters, a User object and a Server object.
userUnbanned¶
Emitted when a user is unbanned from a server. Supplies two parameters, a User object and a Server object.
voiceJoin¶
Emitted when a user joins a voice channel, supplies a VoiceChannel and a User
voiceSwitch¶
Emitted when a user switches voice channels, supplies the old VoiceChannel, the new VoiceChannel, and a User
voiceLeave¶
Emitted when a user leaves a voice channel, supplies a VoiceChannel and a User
voiceStateUpdate¶
Emitted when a user mutes/deafens, supplies a VoiceChannel, User, an object containing the old mute/selfMute/deaf/selfDeaf properties, and an object containing the new mute/selfMute/deaf/selfDeaf properties