Extensions - OtaK/AwesomeBot GitHub Wiki

Starting with version 3.2, AwesomeBot supports extensions! They are Javascript code snippets run in response to a keyword or command, 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.

The AwesomeBot extension builder was introduced in v3.4, allowing you to easily build and test extensions. The left side 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 key without spaces and, optionally, usage and help strings.

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 seconds.

On the right side of the extension builder is a large, beautifully dark-themed code editor (courtesy of CodeMirror). It supports autocompletion and Javascript syntax highlighting, but you can't save work in progress code for later. 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. Only use the built-in code editor if you're really in a hurry.

When you've filled out the form on the left of the builder and you've uploaded your code, hit the teal run button in the lower-right to test your extension in a sandbox, live on the server. You'll be prompted for a channel in which to test the extension and (unless you're making a timer extension) a test message. This generates a test case that will be treated like a message on the server to test your extension on. Make sure you include your command key or one of your keywords in the test message.

Once you click run again, the output button in the lower-left will either turn green or red. As you might expect, green means the extension was executed successfully, and red means there was a fatal error. Either way, you should click on the output button to view the extension test log. If everything looks good, go ahead and click the save button that appears next to run. If not, continue tweaking your extension until it works as desired.

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 AwesomeBot Objects/Variables/Methods.

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

• decodeURI
• encodeURI
• isNaN
• parseInt
• setTimeout

• feed-read's feed function. In AwesomeBot, this function is aliased to rss. See rss for details on its call and usage. See here for full npm 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 AwesomeBot, this function is aliased to xmlparser. See xmlparser. See here for the full npm documentation.

• name: name of the user in the format specified in the server configuration,
• username: user's global username
• nick: user's nickname on the server (may be undefined)
• discriminator: four-digit ID differentiating the user from the 9999 possible users with the same name
• id: user's Discord ID
• isBot: boolean for whether user is a bot
• mention: string to mention the user in the format <@ID>
• avatar: the URL of the user's avatar (may be undefined)
• status: user's current status (online, idle, or offline)
• game: game the user is currently playing on Discord
• roles: the full list of Roles the user has on the server, stored as an object in which the keys are role IDs
• profileData: the user's global AwesomeBot data
  • points: user's AwesomePoints as an integer
  • afk: reason the user is AFK (may be undefined)
  • past names: array of the user's past usernames
  • svrnicks: list of the user's personal server nicknames, stored as an object in which the keys are server nickname strings
  • any values the user may have set in their profile, stored as an object
• statsData: the data for the user on the server
  • messages: number of messages sent by the user on this server in the past week
  • voice: number of minutes the user has held an active voice connection on the server, divided by 5
  • seen: timestamp of when the user was last seen on Discord in an online state
  • active: timestamp of when the user was last active on the server
  • rank: the user's current rank on the server
  • strikes: array of the user's strikes on the server where each element is an array with the following elements
    • 0: Discord ID of the admin that added the strike
    • 1: reason for the strike
    • 2: timestamp of when the strike was added
  • any values the user may have set in their server profile, stored as an object
• setProfileKey(key, value): function that takes a key and optional value to set a field in the user's profileData. If no value is provided, the key will be deleted.
• setSvrProfileKey(key,value): function that takes a key and optional value to set a field in the user's statsData. If no value is provided, the key will be deleted.
• setNickname(nick): function that takes a nick and requires AwesomeBot to have the "Manage Nicknames" permission
• addStrike(reason): function that takes a reason and adds a strike to the user for admins to see
• kick(): function that kicks the user from the server if the bot has the "Kick Members" permission
• block(): function that adds the user to the blocklist for this server
• promote(): function that adds the user to the admins list for this server

• name: full name of this server
• id: the Discord ID of the server
• icon: the URL of the server's icon (may be undefined)
• channels: array of Channels on the server, sorted by position in sidebar
• owner: User who owns the server
• members: the full list of server Users, stored as an object in which the keys are user IDs
• roles:
  • list: the full list of Roles on the server, stored as an object in which the keys are role IDs
  • create: function that takes options as defined here and creates a new role on the server
  • getByName: function that takes a name and returns a matching Role (may be undefined)
• configs:
  • admins: list of bot admins on the server, stored as an object in which the keys are user IDs
  • blocked: list of blocked members on the server, stored as an object in which the keys are user IDs
  • defaultcount: the number of items to fetch for any command, specified in the server configuration
  • maxcount: the maximum number of items to fetch for any command, specified in the server configuration
  • tags: the full list of tags on the server, stored in an object in which the keys are tag names
  • cmdprefix: the command prefix specified in the server configuration (+, @AwesomeBot , etc.)
  • ranks: array of ranks specified in the server configuration where each element is an object with the following properties:
    • name: name of the rank
    • max: maximum activity score for members to have the rank
    • role: ID of role assigned to members with rank (may be undefined)
  • listing: These can be set in Public Data section of the config panel.
    • enabled: a boolean value. Determines if the server shows up on the public server list
    • description: The description that people see if the server shows up on the public server list
    • invite: The Discord invite URL to your server
• userSearch: function that takes a str and searches for server Members
• createChannel: function that takes a name and creates a text channel on the server

• 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
• topic: the channel topic (may be undefined)
• getMessages: function that takes a num and callback(err,messages). Fetches the latest num messages from the channel and calls the callback function on them.
• sendMessage: function that takes a message and sends it in the channel
• sendFile: function that takes a url, an optional name, and optional message and attaches the file provided by the url to the channel.
• deleteMessages: function that takes a usrid, a num of messages to delete, and callback function
• overwritePermissions: function that takes a type (user or role), an id (of the user or role), options as defined here, and a callback (that takes an error which may be undefined)
• muteUser: function that takes a usrid and a callback function (that takes an error which may be undefined)
• createSelectMenu: function that takes a usrid, callback function (that takes the num selected by the user), and an inclusive max number that can be selected; after sending a message with some numerical options, the select menu allows the user to choose one by sending only the number of their selection
• setName: function that takes a name and changes the channel name
• setTopic: function that takes a topic and changes the channel topic
• delete: function that deletes the channel

• name: the name of the role
• id: Discord ID of the role
• mention: string to mention the role in the format of <@&ID>
• permissions: a hash with Discord permission names (camelCase, no spaces) as the key and boolean as value
• position: number indicating the position of the role on the list
• color: hex color of the role, including the #
• add: function that takes a usrid and adds a member to the role
• remove: function that takes a usrid and removes a member from the role
• update: function that modifies the role and takes options as defined here
• delete: function that deletes the role and disassociates all members

This is how extensions save data between runs. The store variable is 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 writeStore for that.

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

Deletes a key from store. Returns the updated store.

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

• url: the URL of RSS feed
• 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

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

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

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

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

• query: string of search terms, in English
• num: number of results to fetch, between 1 and 25
• callback: function that takes a url

• user: the bot user
• sendUser: function that takes a usrid and message, and sends to the user via PM if they are on this server

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 Users mentioned in the message
• author: User who sent the message
• 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
• suffix (only for command extensions): content of message after the command (may be undefined)
• delete: function that deletes the message if the bot has the appropriate permissions

The Server in which the extension is running.

The Channel in which the extension is running.

Only included for keyword extensions

The index (in the message content) of the match in the key array.

Function that takes a Date object and returns a nicely formatted string: [YYYY-MM-DD HH:MM:SS UTC]

A method that takes n seconds and returns a nicely formatted relative time string: YY years, DD days, HH hours, MM minutes, SS seconds

Function that takes a level (INFO, WARN, or ERROR) and a message and writes it to AwesomeBot's log.

Coming soon!