Extensions

Starting with version 3.2, AwesomeBot supports extensions! They are code snippets run in response to a keyword or command, managed per-server via the admin console. To add an extension to a server, send a JSON file (described below) to the bot after logging into the admin console for a server.

Extension Resources

Extensions are sandboxed and given access to a limited number of methods and variables. Let's go through each one...

store

This is how extensions save data between runs. The store variable is an array in which you can keep pretty much anything, and it's automatically saved to the bot config file.

bot

• username: AwesomeBot's global username
• nick: the bot's nickname on this server
• id: AwesomeBot's Discord user ID
• avatar: the URL of the bot's avatar (may be undefined)
• sendMessage: function that takes a message and sends it in this channel
• sendUser: function that takes a usrid and message, and sends to the user via PM if they are on this server

unirest

A lightweight HTTP request library, with full documentation available here.

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

gif

Giphy search method:

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

image

Google Image Search method using the Custom Search API:

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

The server and channel ID are used to determine the safe search level and for logging purposes.

rss

The feed-read module's main method:

• svrid: svr.id
• url: the URL of RSS feed
• count: number of artices to fetch
• callback: function that takes an error and array of articles

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 user IDs mentioned in the message
• author:
  • username: message sender's global username
  • nick: the sender's nickname on this server
  • id: sender's Discord user ID
  • mention: the string used to tag the sender
  • avatar the URL of the sender's avatar (may be undefined)
• delete: function that deletes the message if the bot has the appropriate permissions

svr

• name: full name of this server
• id: the Discord ID of the server
• icon: the URL of the server's icon (may be undefined)
• admins: array of user IDs listed as AwesomeBot admins for the server
• members: the full list of server members, stored as an object in which the keys are user IDs; example user entry:
  • username: user's global username
  • nick the user's nickname on this server
  • id: user's Discord ID
  • mention: the string used to tag the user
  • avatar: the URL of the user's avatar (may be undefined)
  • profileData: any values the user may have set in their profile, stored as an object
  • statsData:
    • messages: number of messages sent by the user on this server in the past week
    • lastseen: UNIX timestamp of when the user was last seen on Discord in an online state
  • setNickname: function that takes a nick and requires AwesomeBot to have the "Manage Nicknames" permission
  • 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
• roles:
  • list: discrete roles on the server, stored as an object in which the keys are role IDs; example role entry:
    • name: the name of the role
    • position: number indicating the position of the role on the list
    • color: hex color of the role, including the #
    • members: array of user IDs with this role
    • 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
  • create: function that creates a new role and takes options as defined here

ch

• name: the name of this channel
• id: Discord ID of the channel
• overwritePermissions: function that takes a type (user or role), an id (of the user or role), and options as defined here

selected

Only included for keyword extensions

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

suffix

Only included for command extensions

The text in the message after the bot tag and command. For example, the suffix in @AwesomeBot image cats would be cats.

prettyDate

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

secondsToString

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

setTimeout, JSON, Math, isNaN, Date, Array, Number, RegExp

You are responsible for validating applicable input and ensuring that the extension sends a message.

Keyword Extensions

Keyword extensions are run in response to one or more keywords in a message. Your JSON file must contain:

• name: name of extension
• type: "keyword"
• key: array of keywords
• case: boolean for case sensitivity
• channels: array of accepted channel names without the # (optional)
• process: code to execute, as a string; use this website to minify your code

Here's a fun example of a keyword extension that works in #shitposts and #circlejerk:

{
    "name": "Praise DuARTe",
    "type": "keyword",
    "case": false,
    "channels": ["shitposts", "circlejerk"],
    "key": ["praise duarte"],
    "process": "image('matias duarte', Math.floor(Math.random() * (19 - 0 + 1)) + 0, svr.id, ch.id, function(img) {imgur.upload(img, function(error, res) {if(error) {bot.sendMessage(img);} else {bot.sendMessage(res.data.link);}});});"
}

If you don't know who DuARTe is, head over to /r/acj

Command Extensions

This extension type emulates regular bot commands. It can parse parameters from the full message content and supports data for the help section. The JSON file should include:

• **name: name of extension
• type: "command"
• key: one-word command
• usage: parameters as a string, e.g. "<param1> <param2>" (optional)
• extended: detailed help as a string (optional)
• channels: array of accepted channel names without the # (optional)
• process: code to execute, as a string; use this website to minify your code

The following example links to ripme for a given user or the message author:

{
    "name": "Rip",
    "type": "command",
    "key": "rip",
    "usage": "<username>",
    "extended": "This command displays a funny website ;)",
    "process": "message.suffix=message.suffix.trim();var user=message.author.username;if(message.suffix){var usrid;0==message.suffix.indexOf('<@!')&&message.suffix.indexOf('>')>11?usrid=message.suffix.substring(3,message.suffix.indexOf('>')):0==message.suffix.indexOf('<@')&&message.suffix.indexOf('>')>10&&(usrid=message.suffix.substring(2,message.suffix.indexOf('>'))),usrid&&svr.members[usrid]&&(user=svr.members[usrid].username)}bot.sendMessage('http://ripme.xyz/'+encodeURI(user));"
}

Timer Extensions

Useful for posting status updates, timer extensions are run periodically by the bot. They do not respond to messages and cannot parse input. Here's what the JSON file must have:

• name: name of extension
• type: "timer"
• interval: timer interval in seconds
• channels: array of applicable channel names without the #
• process: code to execute, as a string; use this website to minify your code