Skip to content
This repository has been archived by the owner on Jul 16, 2022. It is now read-only.

Extensions

Jump to bottom
Gilbert Gobbels edited this page Jan 4, 2018 · 10 revisions

GAwesomeBot supports and encourages extensions. Extensions are Javascript code snippets run in response to a keyword, command, or timer and managed per-server via the Admin Console. To add an extension to a server, use the extension builder (described below) to the bot after logging into the Admin Console for a server.

Extension Builder

blank extension builder

Extension Properties

The GAwesomeBot extension builder allows you to easily build and test extensions. The builder contains a form for the extension's properties:

  • A unique, human-readable name for the extension
  • Channels in which the extension will work
  • Type: command, keyword, or timer

Command extensions look and behave like regular bot commands, available with the command prefix set on the server and accepting parameters in the suffix. You must specify a one-word command key that will trigger the extension in a channel. You may also specify usage and help strings (per the image above); these will display if a user runs help <command key>.

Keyword extensions are activated when one of the specified keywords is used in a public message on the server. You must specify a list of comma-separated keywords without duplicates or blank entries.

Timer extensions are run periodically in certain channels. They're useful for automatically running moderation tasks. Specify an interval in milliseconds (60000 milliseconds = 1 minute).

Code Editor

The extension builder contains a large, beautifully dark-themed code editor (courtesy of CodeMirror). It supports Javascript syntax highlighting, and you can save work in progress code for later (although it is advisable to disable extensions in all channels if code is unfinished). We recommend that you use an editor of your choice to write the code and upload the code to the extension builder when you're ready to test it. Helpfully, the builder features Upload and Download buttons. Only use the built-in code editor if you're really in a hurry.

Testing an Extension

When you've filled out the form and you've uploaded your code, hit the save button. You are strongly advised to test the extension (and any/all parameters it uses) in a channel, to ensure there are no bugs. You may then check the logs for any errors.

If the extension does not produce any errors and functions as it should, you do not need to do anything more (although you may wish to modify the channels it is enabled in, any help usage information/keywords etc). Otherwise, continue tweaking your extension until it works as desired.

Javascript API

Extensions have about 10 seconds to run and are responsible for sending messages (if necessary). They are sandboxed and have access to only the following built-in Javascript Objects/Functions, npm modules, and GAwesomeBot Objects/Variables/Methods.

Built-in JavaScript Objects

  • Array
  • Date
  • JSON
  • Math
  • Number
  • Object
  • RegExp

Built-in JavaScript Functions

  • decodeURI
  • decodeURIComponent
  • encodeURI
  • encodeURIComponent
  • isFinite
  • isNaN
  • moment
  • parseFloat
  • parseInt
  • setTimeout

npm Modules

  • feed-read's feed function. In GAwesomeBot, this function is aliased to rss. See rss for details on its call and usage. See here for full npm documentation.
  • moment: A date library for parsing, validating, manipulating, and formatting dates. See here for documentation.
  • util: A Java-esque port into JavaScript. See here for full npm documentation.
  • unirest: A lightweight HTTP request library. See here for full npm documentation.
  • xml-parser: A XML parser library. In GAwesomeBot, this function is aliased to xmlparser. See xmlparser. See here for the full npm documentation.

GAwesomeBot Objects

Guild

"A Guild", you ask?! Discord's modern tech speak for a server. We'll start calling it the guild from now on.

  • name: full name of the guild.
  • id: the Discord ID of the guild.
  • ownerID: Discord ID of the user who owns the guild
  • region: the server region of the guild (e.g. eu-west, us-central, etc).
  • splash: the hash of the guild splash image, or null if no splash image (Discord Partnered servers only).
  • unavailable: whether the guild is unavailable or not (boolean).
  • verificationLevel: the guild's verification level (a number: 0/1/2/3 = [None/Low/Medium/Tableflip]).
  • defaultNotifications: the default notification settings for the guild (0 or 1 = ["All Messages" or "Only @mentions"]).
  • mfaLevel: the admin two-factor authentication level for the guild (0 or 1 = [not required/required]).
  • memberCount: the number of members in the guild
  • defaultChannel: returns the Channel object of the guild's default channel.
  • icon: the hash of the guild's icon (may be undefined).
  • iconURL: the URL of the guild's icon (may be undefined).
  • createdAt: timestamp of the guild's creation.
  • joinedAt: timestamp of when the bot account joined the guild.
  • afkTimeout: the guild's AFK timeout in seconds.
  • afkChannelID: the ID of the guild's AFK voice channel (if set; otherwise null).
  • emojis: returns an array of guild emoji objects.
  • features: returns an array of guild feature objects.
  • channels: Collection of Channels on the guild.
  • members: Collection of Members on the guild.
  • roles: Collection of Roles on the guild.
  • editNickname: function that takes a nickname and edit the bot's nickname in the guild.
  • kickMember: function that kicks a member from the guild. Takes a user ID and and optional callback.
  • banMember: function that bans a member from the guild and deletes x days of messages by that user. Takes a user ID and deleteMessageDays (number of days to delete messages for), and optional callback.
  • unbanMember: function that unbans a member from the guild. Takes a user ID and optional callback.
  • createChannel: function that creates a channel on the guild. Takes a channel name, type (either 0 or 2 [text or voice]), and callback. Returns the Channel object for the newly created channel to the callback function. See an example below.
  • createEmoji: function that creates an emoji in the guild. Takes an options object (see here) and returns an emoji object (see here) to callback. Note: Discord does not allow adding, editing or removing of emojis through bot accounts, so while GAwesomeBot does support this feature, it likely will not work for you. This is an issue on Discord's end; not ours.
  • editEmoji: function that edits an emoji in the guild. Takes emoji ID and options object, edits the emoji and returns an emoji object to callback. As above, not likely to work for you due to Discord's API limitation on bot accounts.
  • deleteEmoji: function that deletes an emoji from the guild. Takes an emoji ID and optional callback. As above, not likely to work for you due to Discord's API limitation on bot accounts.
  • createRole: function that creates a role on the guild. Takes an options object (optional; if not provided an empty roll called 'new role' is created) and a callback. The newly created role is passed to the callback as a Role object. The options object may include (all optional):
    • name: name of the role
    • permissions: role permissions number
    • color: hex color of the role, in number form (e.g 0x3d15b3 or 4040115)
    • hoist: whether to hoist the role in the user list. (boolean)
    • mentionable: whether the role should be mentionable (boolean)
  • deleteRole: function that takes a role ID and deletes the role. Optional callback.
  • delete: function that deletes the guild (bot user must be owner).
  • edit: function that takes options object and callback and edits the guild. Passes the amended guild object to callback.
  • editMember: function that edits a member on the guild. Takes member ID and options object. The same as Member.edit().
  • editRole: function that edits a role on the guild. Takes role ID, options object and returns the amended Role to a callback.
  • getBans: takes a callback (required) and returns an array of Users who are banned from the guild.
  • getEmbed: function that gets a guild's embed object and returns it to a callback (required).
  • getInvites: function that gets all invites in the guild. Returns an array of Invite objects to callback.
  • getPruneCount: function that gets the prune count for the guild. Takes a number of days and callback. Returns the number of members that would be removed in a prune operation to your callback.
  • pruneMembers: function that prunes the guild. Takes number of days and callback. Prunes members who have been inactive for x days and returns the number of members prunes to callback.
  • getVoiceRegions: function that gets an array of voice region objects for the guild, returned to callback.
  • getWebhooks: function that gets all the webhooks in the guild. Returns an array of webhook objects to callback.
  • leave: function that makes the bot leave the guild. Use wisely.

Channel

  • name: the name of the channel.
  • id: Discord ID of the channel.
  • mention: string to mention the channel in the format <#ID>.
  • position: number indicating the position of the channel in the sidebar (ascending from the top, the top channel being 0).
  • topic: the channel topic (may be undefined).
  • type: 0 for text channels, 2 for voice channels.
  • bitrate: The bitrate of the channel (voice channels only).
  • lastMessageID: the ID of the last message.
  • lastPinTimestamp: timestamp from when a message was last pinned in the channel.
  • createdAt: timestamp of channel creation
  • guild: Guild object of the server where the channel exists. Not likely to be needed as guild is already an object variable in its own right (see below).
  • messages: returns a Collection of messages (message objects) in the channel.
  • permissionOverwrites: returns a Collection of permissionOverwrites in the channel. These are specific permissions in that channel for a specific user or role.
  • voiceMembers: returns a Collection of members in the channel. (Voice channels only).
  • createMessage: function that takes a message and sends it in the channel. Supports content, file and callback, the last two being optional. See examples below.
  • deleteMessage: function that takes a _message ID and deletes the message from the channel. Optional callback.
  • deleteMessages: function that takes an array of _message IDs and deletes the messages from the channel (bot accounts only). Optional callback.
  • getMessages: function that takes limit, before, after, around and a callback and gets the last limit of previous messages in a text channel. Returns an object array of message objects to callback. See the documentation here. All parameters are optional but must be specified (i.e. specify null to leave empty). See example below.
  • editMessage: function that takes a message ID, content and callback (optional) and edits a message in the channel if the bot has the appropriate permissions (self messages only). The content may be a string or object (see documentation here). The amended message object is passed to the callback (if specified).
  • getPins: function that returns an array of message objects consisting of every message in the channel that is pinned.
  • pinMessage: function that takes a message ID and optional callback and pins the message in the channel.
  • unpinMessage: function that takes a message ID and optional callback and unpins the message in the channel.
  • purge: function that purges messages from the channel (bot accounts only). Takes limit, filter, before, after, and a callback and deletes the specified messages. Other than limit, all fields are optional, but all options must be specified (use null to leave a parameter blank). If specified, filter should be a function that for each message returns true if it is to be deleted. For an example of a filter, see the awaitMessage snippet. Returns the number of messages deleted to callback. See the documentation here.
  • unsendMessage: why simply remove a message from the channel with deleteMessage when you can use the function? Sure, it does exactly the same thing, and is used in exactly the same way, but it sounds cooler.
  • sendTyping: function that sends typing status in a text channel. Lasts a few seconds.
  • permissionsOf: function that takes a member ID and returns the channel-specific permissions of that user in the channel, in the form of a permissions object. See here.
    • allow: the allowed permissions number
    • deny: the denied permissions number
    • json: a JSON representation of the permissions number
    • has: function that takes a permission and returns true or false if the role has that permission. See an example below.
  • getInvites: function to get all unexpired invites for the channel. Returns an array of Invite objects to a callback.
  • getWebhooks: function to get all webhooks for a channel. Returns an array of webhook objects to a callback.
  • createInvite: function that takes options and callback and creates an invite for the channel, returning an Invite object to the callback. The options parameter is optional and if not null should be an object (see here).
  • createWebhook: function that takes options and callback and creates a webhook for the channel, returning the newly created webhook to the callback. The options parameter should be an object containing name and/or avatar (a base64 data URI). See an example below.
  • editPosition: function that takes a position number and callback (optional) and changes the position of the channel in the sidebar to the number provided.
  • getMessageReaction: function that obtains a list of users who reacted to a message in the channel with a specific emoji. Takes a message ID, reaction (unicode string or emojiName:emojiID if custom emoji), optional limit (max number of users to obtain) and callback. Returns an array of users who reacted to the message with the specified reaction to the callback.
  • addMessageReaction: function that adds a reaction to a message in the channel. Takes a message ID, reaction (unicode string or emojiName:emojiID if custom emoji) and optional callback.
  • removeMessageReaction: function that removes a reaction from a message in the channel. Takes a message ID, reaction (unicode string or emojiName:emojiID if custom emoji), optional user ID (ID of the user to remove the reaction for) and optional callback. If no user ID is specified, defaults to the bot.
  • editPermission: function that creates or edits a channel 'permission overwrite' (a custom permission in the channel for a user or role). Takes:
    • overwriteID (the ID of a member or role)
    • allow (permissions number for allowed permissions)
    • deny (permissions number for denied permissions)
    • type (either member or role)
    • callback If you're not familiar with Discord permissions numbers, see here. Some helpful geniuses have even created a permissions calculator. See a usage example below.
  • deletePermission: function that removes a permission overwrite for a role or user. Takes overwriteID (the ID of a role or user). Optional callback.
  • edit: function that takes options object and callback and edits the channel, returning the amended channel object to callback. See the documentation here. See an example below.
  • delete: function that deletes the channel. Optional callback.

User

  • username: user's global username.
  • id: user's Discord ID.
  • discriminator: four-digit ID differentiating the user from the 9999 possible users with the same name.
  • mention: string to mention the user in the format <@ID>.
  • avatar: the hash of the user's avatar (may be undefined).
  • defaultAvatar: hash for the default avatar of the user if there is no avatar set.
  • avatarURL: the URL of the user's avatar (may be undefined).
  • defaultAvatarURL: the URL of the user's default avatar.
  • bot: boolean for whether user is a bot.
  • createdAt: timestamp of the user's account creation.
  • createMessage: PMs a user. Supports message, file and callback, the last two being optional. See example below.

Member

  • username: member's global username.
  • id: member's Discord ID.
  • nick: member's nickname on the guild (if no nickname is set, will be null).
  • discriminator: four-digit ID differentiating the member from the 9999 possible users with the same name.
  • mention: string to mention the member in the format <@ID>.
  • avatar: the hash of the member's avatar (may be undefined).
  • defaultAvatar: hash for the default avatar of the member if there is no avatar set.
  • avatarURL: the URL of the member's avatar (may be undefined).
  • defaultAvatarURL: the URL of the member's default avatar.
  • bot: boolean for whether member is a bot.
  • status: the member's status. Either "online", "idle", or "offline".
  • game: returns object (type and name) for the active game the member is playing (or null if no active game).
  • createdAt: timestamp of the member's account creation.
  • joinedAt: timestamp of when the member joined the guild.
  • roles: an array of role IDs this member is a part of.
  • user: the member's User object.
  • guild: the Guild object for the member. Not likely to be needed as guild is already an object variable in its own right (see below).
  • permission: the guild-wide permissions of the member in the form of a permissions object. Also see role.permissions below.
  • voiceState: the voice state of the member. Returns a VoiceState object
  • addRole: function that adds the member to a role. Takes a role ID.
  • removeRole: function that removes the member from a role. Takes a role ID.
  • kick: function that kicks the user from the guild. Takes an optional callback.
  • ban: function that bans the member from the guild and deletes x days of messages by that member. Takes deleteMessageDays (number of days to delete messages for), and optional callback.
  • unban: function that unbans the member from the guild. Takes an optional callback.
  • edit: function that edits the member on the guild. Takes options object and an optional callback.

Role

  • name: the name of the role.
  • id: Discord ID of the role.
  • mention: string to mention the role in the format of <@&ID>.
  • position: number indicating the position of the role on the list.
  • hoist: whether users with this role are hoisted in the user list or not (boolean);
  • color: hex color of the role, in base 10.
  • createdAt: timestamp of role creation.
  • managed: whether a guild integration manages this role or not (boolean).
  • mentionable: whether the role is mentionable or not (boolean).
  • guild: Guild object of the server where the role exists. Not likely to be needed as guild is already an object variable in its own right (see below).
  • permissions: an array representing a calculated permissions number.
    • allow: the allowed permissions number
    • deny: the denied permissions number
    • json: a JSON representation of the permissions number
    • has: function that takes a permission and returns true or false if the role has that permission.
  • edit: function that modifies the role and takes options as defined here. See an example below.
  • editPosition: function that edits the role's position (see position above). Takes a position number. Role position numbers are highest on top and lowest at the bottom.
  • delete: function that deletes the role and disassociates all members.

Invite

  • code: the invite code.
  • maxAge: how long the invite lasts (in seconds).
  • revoked: whether the invite has been revoked (boolean).
  • uses: the number of times the invite has been used.
  • createdAt: timestamp of the invite's creation.
  • inviter: the invite creator (user object).
  • maxUses: the maximum number of invite uses. If no max, returns 0.
  • temporary: whether the invite is temporary (boolean).
  • channel: brief information on the channel the invite is for:
    • type: (0 or 2 = [text channel or voice channel])
    • name: the channel name
    • id: the channel ID
  • guild: brief information on the guild the invite is for:
    • splash: splash image (null if not a Discord Partnered guild)
    • icon: hash of the guild's icon
    • name: the name of the guild
    • id: the guild ID
  • delete: function that deletes the invite.

MemberDocument

  • last_active: date of the user's last activity (e.g. 2017-02-10T19:10:39.738Z).
  • cannotAutokick: whether the user can be autokicked, if the bot's autokick feature is enabled (boolean).
  • rank_score: the user's score on the bot's ranking system [link to Configuration page#ranks]. Rank is determined by the rank_score, and this is based on the user's activity on the guild.
  • rank: the name of the user's rank on the guild, determined by the user's ranks score and the ranks configured by the guild's Bot Admins.
  • voice: the number of minutes of voice activity on the guild in the last week
  • messages: the number of messages by the user posted on the guild in the last week
  • afk_message (if set): the user's afk message (if they have set themselves as AFK on the guild; otherwise undefined).
  • profile_fields: an array of profile fields in the form of key : value. Also see bot.setMemberDataKey.
  • strikes: an array of the user's strikes on the guild. Each strike item consists of: * _id: the id of the user who issued the strike * reason: the reason for the strike * timestamp: timestamp of when the strike was issued

UserDocument (Global) To be removed

This is the information held about a user on the Bot globally, distinct from any information held on the individual server where the extension is running.

  • past_names: previous usernames the user may have had (if they have changed their username).
  • points: the number of GAwesomePoints the user has.
  • afk_message: the user's global afk message (if they have set themselves as AFK; otherwise undefined)
  • server_nicks: an array of any server nicks the user may have set. Each item consists of _id and server_id for each server nick (e.g. "_id":"shortnick","server_id":"213945652427556895").
  • reminders: an array of any reminders the user may have set. Each item consists of name and expiry_timestamp.
  • location: the user's profile location, if they have set one.
  • weatherunit: the user's profile weather unit, if they have set one (will be either C or F = [Celsius or Fahrenheit]).
  • last_seen: the timestamp of the user's last activity with the bot, either via PM or on any server in which the bot is present.
  • profile_fields: an array of profile fields in the form of key : value.
  • profile_background_image: the URL of the user's background image on the bot's website. If they have not set one, this returns the default image.
  • isProfilePublic: whether the user has allowed their profile to be public on the bot's web interface (boolean).
  • upvoted_gallery_extensions: public extensions on the bot that the user has upvoted in the extension gallery on the bot's web interface. Returns an array of public extensions IDs.

GAwesomeBot Variables and Methods

extension.store

This is how extensions save data between runs. The extension.store variable returns a JSON object in which you can store number, string, and array values corresponding to keys. Modifying this variable does not actually save changes; use extension.writeStore for that. Returns undefined if empty (i.e. if no data previously written to the extension store with extension.writeStore [below]).

extension.writeStore(key, value, callback)

Use this method to actually save changes to extension.store. It accepts a key and a value, which are written to the bot's config file. Returns the updated extension.store via callback.

extension.deleteStore(key, callback)

Deletes a key from extension.store. Returns the updated extension.store via callback.

Extension Store is to be fully revamped in 4.1. Further information to come

rss

An alias to npm's feed-read's feed function, which takes the following arguments:

  • url: the URL of RSS feed
  • num: the number of articles to return
  • callback: function that takes an error and array of articles. Each article is a hash:
    • title: article's title
    • author: author's name
    • link: string of the url to the article
    • content: HTML content of the article
    • published: Date object of when the article was published

xmlparser

An alias to npm's xml-parser function. The function takes an XML body and parses it to JSON for easier handling in JavaScript.

imgur

Pre-authenticated imgur-node-api module. The most useful method will be upload, which takes the following arguments:

  • image: the URL of the image to be uploaded
  • callback: function that takes an error and result To be removed

gif

Giphy search method that takes the following arguments:

  • query: string of search terms, in English
  • rating: y, g, pg, pg-13, or r
  • callback: function that takes a url To be removed

image

Google Image Search method using the Custom Search API that accepts these arguments:

  • query: string of search terms, in English
  • safe: Google SafeSearch (boolean)
  • num: number of results to fetch, between 1 and 25
  • callback: function that takes a url To be removed

bot

  • user: the bot user object.

  • guilds: the number of guilds (that's Discord talk for 'servers') the bot is on.

  • users: the number of users the bot is serving.

  • connectionUptime: the period of time the bot has been running, in milliseconds. e.g. 88647426. To be renamed to uptime

  • uptime: the period of time the bot has been running, in seconds. e.g. 88647.426 would mean an uptime of 88647 seconds and 426 milliseconds. Returns the same number as connectionUptime but divided by 1000. To be removed

  • isMuted: function that takes a channel and member and checks whether a user is muted in the channel (returns a boolean).

  • muteMember: function that takes a channel, member and callback, and mutes the user.

  • unmuteMember: function that unmutes a user. Usage is the same as for muteMember.

  • getMember: function to find a user on the guild by username, ID etc. Takes a string and if found, returns a member object. To be renamed to findMember

  • getMemberName: takes a user id and ignorenick (boolean) and returns the member's username. If the member has a nickname on the guild, this will be returned instead of their username. If ignorenick is specified and is true, returns the member's username. To be renamed to displayName and moved to member

  • getMemberAdminLevel: takes a user id and returns the Admin Level for the user on the guild (returns 0/1/2/3/4). To be modified: Level 4 removed

  • getMemberData: takes a usrid and callback, returning the user's MemberDocument to the callback. To be renamed to document moved to member

  • addMemberStrike: function to strike a user from within an extension. Takes a user id, reason, and callback. To be renamed to addStrike and moved to member

  • setMemberDataKey: Creates or updates a field in the user's profile_ fields array under the user's MemberDocument. Takes a user id, key, value, and callback. To be removed

  • deleteMemberDataKey: Deletes a field in the user's profile_ fields array under the user's MemberDocument. Takes a user id, key, and callback. To be removed

  • getUserData: Takes a usrid and callback, returning a user's UserDocument to the callback. To be removed

  • handleViolation: trigger a user violation on a server, as if a user has just been caught by a filter rule. Strikes a user, PMs them to tell them what they did wrong, messages the guild's Bot Admins (level 2 and above) to inform them of the violation, and creates a new item in the ModLog. Takes channel id, member id, user Message, admin message, strike message, action (block/ mute/kick/strike/ban/none), and an optional role id. See the example below.

  • messageBotAdmins: Takes a given message and PMs it to Bot Admins on the guild (level 2 and above).

  • awaitMessage: Listens for 60 seconds, awaiting a particular user's messages, passing those messages in the channel through an optional filter and to your callback. Accepts the following:

    • channel id: the ID of the channel to listen in
    • user id: the ID of the user whose messages to listen to
    • filter: an optional function. If provided, awaitMessage will listen to all messages from the user in the given channel and pass them to the filter function. If your filter function returns true, the callback function will be triggered and awaitMessage will stop listening.
      If no filter is provided, awaitMessage will listen for a single message from the user in the given channel, and then trigger your callback function.
    • callback: receives the specified user's message(s) from the channel, whether filtered or not.

message

Not included for timer extensions

  • content: full content of the message, including tag syntax.
  • cleanContent: content of message with tags replaced by usernames.
  • mentions: array of Members mentioned in the message.
  • author: User who sent the message.
  • member: Member object of the user who sent the message.
  • channel: Channel object of the channel where the message was posted. Not likely to be needed as channel is already an object variable in its own right (see below).
  • guild: Guild object of the server where the message was posted. Not likely to be needed as guild is already an object variable in its own right (see below).
  • editedTimestamp: the timestamp of the last time the message was edited (if not edited will be null).
  • embeds: embed object if the message contained any embedded content (otherwise null).
  • id: the message's ID.
  • mentionEveryone: whether the message mentions everyone/here (boolean).
  • pinned: whether the message is pinned (boolean).
  • roleMentions: an array of any roles mentioned in the message (consisting of only role IDs, ordered by role ID in ascending order).
  • reactions: an array of reaction objects for any user's reactions to the message (empty if no reactions).
  • timestamp: timestamp of message creation (the date and time the message was posted).
  • tts: whether the message is a text-to-speech message (boolean).
  • attachments: array of the message's attachments where each element is an object with the following properties:
    • url: URL of the attachment from Discord's CDN
    • size: number indicating the file size of the attachment in bytes
    • filename: the name of the attached file
  • pin: function that pins the message if the bot has the appropriate permissions.
  • unpin: function that unpins the message if the bot has the appropriate permissions.
  • delete: function that deletes the message if the bot has the appropriate permissions.
  • edit: function that edits the message if the bot has the appropriate permissions (self messages only).
  • getReaction: function that obtains a list of users who reacted with a specific reaction. Takes a reaction (unicode string or emojiName:emojiID if custom emoji), optional limit (max number of users to obtain) and callback. Returns an array of users who reacted with the specific reaction to the callback.
  • addReaction: function that adds a reaction to the message. Takes a reaction (unicode string or emojiName:emojiID if custom emoji) and optional callback.
  • removeReaction: function that removes a reaction from the message. Takes a reaction (unicode string or emojiName:emojiID if custom emoji), optional user ID (ID of the user to remove the reaction for) and optional callback. If no user ID is specified, defaults to the bot.

commandPrefix

Only for command extensions. The command prefix on the guild.

commandSuffix

Only for command extensions. The content of message after the command (may be undefined).

commandKey

Only for command extensions. The key used to trigger the command.

guild

The Guild in which the extension is running.

channel

The Channel in which the extension is running.

keywordMatch

Only included for keyword extensions

Contains selectedKeyword and keywordIndex; the former the index of the keyword in the keywords array, the latter the index of the keyword match in the message content. e.g. if an extension's list of keywords is apple,banana,orange and a user posts the message I like bananas: "selectedKeyword":1,"keywordIndex":7.

logMsg

Function that takes a level (info, warn, or error) and a message and writes it to the guild's GAwesomeBot log. Defaults to info if level is unspecified.

setTimeout, JSON, Math, isNaN, _isFinite_, Date, RegExp, Array, Number, encodeURI, _encodeURIComponent_, decodeURI, _decodeURIComponent_, _parseFloat_, _moment_, parseInt, util

Example Snippets

Example: bot.awaitMessage 

channel.createMessage("Do you want me to post your avatar?");
bot.awaitMessage(channel.id, message.member.id,
                 filter => {
    myfilter = filter.content.toLowerCase().trim();
    // return true to trigger the callback function and stop listening to messages
    // otherwise keep listening to the user's messages (for up to 60 seconds)
    if(myfilter == "y" || myfilter == "n") return true;
},
                 callback => {
    if(callback.content == "y") {
        channel.createMessage("Here is your avatar: " + message.author.avatarURL);
    }
});

OR if we only want to listen to the user's next message, we can leave out the filter:

channel.createMessage("Do you want me to post your avatar?");
bot.awaitMessage(channel.id, message.member.id,
                 callback => {
    if(callback.content == "y") {
        channel.createMessage("Here is your avatar: " + message.author.avatarURL);
    }
});

Example: bot.handleViolation 

if (typeof message.mentions != "undefined" && message.mentions.length > 0) {
    var suffix = commandSuffix.split("|");
    if(suffix[2] === undefined || (suffix[2] != 'block' && suffix[2] != 'mute' && suffix[2] != 'kick' && suffix[2] != 'ban')) {
        suffix[2] = 'none';
    }
    var adminmsg = bot.getMemberName(message.mentions[0].id) + " " + suffix[1] + " and this was flagged by " + message.author.username;
    var usermsg = "You" + suffix[1];
    bot.handleViolation(channel.id, message.mentions[0].id, usermsg, adminmsg, suffix[1], suffix[2]);
}

Example usage: <command key> @kevin|insulted GAwesomeBot|mute

bot.handleViolation also has an optional role_id parameter at the end. If provided, this will also add the user to a given role.

Example: channel.getMessages 

channel.getMessages(3, null, null, null, messages => {
    messages.forEach(msg => {
        msg.pin();
    });
});

The above snippet would take the last three messages in the channel and pin them.

Example: channel.createWebhook 

channel.createWebhook({ "name":"Hilbert's New Webhook" },
                      newwebhook => {
    /*
     * newwebhook.name = name of the new webhook (Hilbert's New Webhook)
     * newwebhook.channel_id = the ID of the channel it was created in
     * newwebhook.guild_id = the server id
     * newwebhook.avatar = the avatar of the webhook (if none, returns null)
     * newwebhook.user = the object of the bot
     * newwebhook.id = the important bit
     * newwebhook.token = the other important bit
    */
    var webhookurl = "https://ptb.discordapp.com/api/webhooks/" + newwebhook.id + "/" + newwebhook.token;
});

Example: channel.edit 

channel.edit({ "topic":"The channel topic is now this line" });

Example: channel.permissionsOf.has 

if(!channel.permissionsOf(message.author.id).has("createInstantInvite")){
    channel.createMessage("I will not create an invite for you because you do not have permission to create invites in this channel.");
}

Example: channel.editPermission 

channel.editPermission(message.author.id, 32768, null, 'member');

The above snippet creates a permission overwrite for the user to attach files.

channel.editPermission(message.author.id, null, 32768, 'member');

The above snippet creates a permission overwrite disallowing the user from attaching files.

Example: guild.createChannel 

guild.createChannel('oranges', 0, newchan => {
    newchan.edit({ "topic":"This channel is for discussing our shared love of oranges." });
});

The above creates a channel called oranges and sets the topic of that channel.

Example: channel.createMessage 

channel.createMessage("Hello folks in #" + channel.name);
channel.createMessage("This is a simple message");

We can also send embedded messages. See the structure of the embed object for more detailed guidance.

channel.createMessage({
    embed: {
        color: 10551296,
        title: "Title of the message",
        description: "Message content"
    }
});

Send an embedded message in the channel, with an author:

channel.createMessage({
    embed: {
        author: {
            name: bot.getMemberName(bot.user.id),
            icon_url: bot.user.avatarURL,
            url: "https://mybotwebsite.com"
        },
        color: 10551296,
        title: "Message title",
        description: "Message content"
    }
});

Embed an image:

channel.createMessage({
    embed: {
        image: {
            url: "http://i.imgur.com/U8WeLcO.jpg"
        },
    }
});

Send an image as an attachment:

unirest.request({ url:"http://i.imgur.com/U8WeLcO.jpg", encoding: null },
function (error, response, body) {
    if(response.statusCode == 200){
        channel.createMessage(null, {
            file: body,
            name: "image.jpg"
        });
    }
});

Example: user.createMessage 

message.author.createMessage("This is a simple message");

The above example PMs the user who runs the extension. Remember the message property contains author (an alias of user). As long as we have a user object we can run .createMessage() to PM that user.

If the user we want to PM is the author of the message then this is fine. But in other cases we'll often have a have a member object instead. For example, message.mentions returns an array of members who were mentioned in the message. A member object contains more information and can be more useful than user, but it doesn't provide .createMessage.

So what if we want our extension to PM the first member who is mentioned in the message? message.mentions[0] gives us that user's member object, so message.mentions[0].createMessage won't work.

Fortunately, we can get a member's user object with member.user. So for an extension that PMs the first user mentioned in the message:

message.mentions[0].user.createMessage("Hello there!");

Example: role.edit 

if(message.roleMentions !== undefined && message.roleMentions > 0){
    const hoisted = (guild.roles.get(message.roleMentions[0]).hoist) ? false : true;
    guild.roles.get(message.roleMentions[0]).edit({ hoist : hoisted });
}

The above takes a role (i.e. <command key> @role) and hoists/unhoists it. Unlike message.mentions, message.roleMentions does not return an array of objects, but a simple array of the IDs of any roles that are mentioned. Accordingly, we have to obtain the Role object from its ID; for this we can use guild.roles.get(<ID>) to get the object, and can then access Role.edit. We can use .get(ID) on any Collection (i.e. channels, members, or roles).

const roleName = "Special";
const myRole = guild.roles.find(rolefind => { return (rolefind.name == roleName ? true : false) });
if(!myRole) {
  channel.createMessage("The role " + roleName + " could not be found.");
} else {
  const hoisted = (myRole.hoist) ? false : true;
  myRole.edit({ hoist : hoisted });
}

The above uses Collection.find to search the roles array for a role with the name Special and obtain its Role object, then hoists/unhoists it.

The Role is found by applying a function (rolefind) to each role in the array, until the function evaluates to true (when the name of the role matches the predefined roleName) and then returns the object of this role. This will only return the first matching item, so if there were multiple roles of the same name, this code would be ineffective (although you could perhaps use Collection.filter). In any event, it is always safer to use the ID of a role/member/channel than its name.

Example: user.addRole 

var roleforeveryone = 'ROLE ID HERE';
guild.members.map(usr => {
if(usr.roles.indexOf(roleforeveryone) == -1) {
    usr.addRole(roleforeveryone);
}
});

The above uses Collection.map to find all members on the guild and, if they are not already a member of the role (defined by a given role ID), adds them to that role.

Clone this wiki locally