Global Functions

The following functions are always available within the code of your javascript event.

Table of Contents
debuglog()
find_user()
find_username()
find_channel()
find_channelname()
create_message()
create_embed()
save()
load()
delete()
get()
post()
exit()
add_reaction()
delete_reaction()

debuglog

debuglog(text)

Outputs any parameters to the bot's debug console. Generally, you won't want to use this unless being asked to troubleshoot a problem with the bot's developer.

find_user

find_user(snowflake_id)

When given a snowflake id as a string, representing a user on the current guild, this will return an object if that user can be found, containing the following fields:

field	content
bot	True if the author is a bot.
discriminator	The user's discriminator value
username	The user's username
nickname	The user's nickname on the current guild, or an empty string if they have no nickname
avatar	A hash representing the location of the user's avatar
id	The user's snowflake unique id
mfa_enabled	True if the user is using multi-factor authentication
mention	A string that can be used to build a mention for the user
full_name	A combination of the user's username, a hash symbol (#) and the discriminator

find_username

find_username(full_username)

When given a full username as a string, representing a user on the current guild, this will return an object if that user can be found, containing the following fields. A full username is considered to be both the username and descriptor portion, separated by a hash symbol, e.g. "Brain#0001".

field	content
bot	True if the author is a bot.
discriminator	The user's discriminator value
username	The user's username
nickname	The user's nickname on the current guild, or an empty string if they have no nickname
avatar	A hash representing the location of the user's avatar
id	The user's snowflake unique id
mfa_enabled	True if the user is using multi-factor authentication
mention	A string that can be used to build a mention for the user
full_name	A combination of the user's username, a hash symbol (#) and the discriminator

find_channel

find_channel(snowflake_id)

When given the snowflake id as a string of a channel on the current guild, returns the details of that channel as an object, with the following fields in the returned value:

field	content
dm	True if the channel is a direct message channel. In all instances at present, this will be false
id	The snowflake id of the channel
parent_id	The snowflake id of the parent category
guild_id	The guild id of the guild this channel exists on
name	The name of the channel
type	The type of the channel, 0 for text channel.
nfsw	True if this channel is marked as NSFW

find_channelname

find_channelname(channel_name)

When given the name of a channel as a string of a channel on the current guild, returns the details of that channel as an object, with the following fields in the returned value:

field	content
dm	True if the channel is a direct message channel. In all instances at present, this will be false
id	The snowflake id of the channel
parent_id	The snowflake id of the parent category
guild_id	The guild id of the guild this channel exists on
name	The name of the channel
type	The type of the channel, 0 for text channel.
nfsw	True if this channel is marked as NSFW

create_message

create_message(snowflake_id, message_text)

Creates and sends a message to the channel given in snowflake_id. The snowflake id must be a string, all values given by other functions in the API are already string values, so no conversion should be neccessary.

There is a limit of 5 outbound messages at present, per inbound event.

create_embed

create_embed(snowflake_id, embed_object)

Creates and sends an embed message to the given in snowflake_id. The snowflake id must be a string, all values given by other functions in the API are already string values, so no conversion should be neccessary.

There is a limit of 5 outbound messages at present, per inbound event.

The embed object is a complex object which is well documented on the discord API documentation page.

save

save(key, value)

When given both a key and a value as strings, the bot will save the value to a key/value store, which can later be retrieved using load() with that same key. Each guild has its own backing store, which is global to all channels upon that guild, so this provides a mechanism to pass persistent data between events and across channels.

There is a limit of 1024 maximum persistent keys that can be stored in the key/value store per guild, and a maximum size per value of 64 kilobytes.

load

load(key)

When given a key as a string, attempts to load a value from the key/value store of the guild. If the key does not exist, an undefined value is returned.

There is a limit of 1024 maximum persistent keys that can be stored in the key/value store per guild, and a maximum size per value of 64 kilobytes.

delete

delete(key)

When given a key name as a string, attempts to delete that key name from the key/value store of the guild. If the key does not exist, this function has no effect.

get

get(url, callback_function_name_string)

Retrieve a webpage via a HTTP GET request. The callback_function_name_string must be the name of a function defined in your script, and not an inline function, lambda, or similar. This is because in between you calling the get() function and the callback function, the entire state of the interpreter has been reset, so there is no position to call back to except by name. Here is an example of how to use this function:

    get("https://www.google.com", "mycallback");
    
    function mycallback(data) {
        debuglog("received", data);
    }

Within the callback, the objects guild, channel, and author are not defined, however CHANNEL_ID is and you can use find_channel on this to fetch channel information, or just message a channel directly as above. If you wish to save any other state, you should use the load() and save() functions.

The callback will be passed the raw text returned from the remote web service as its single parameter.

Note that web requests will be made via an anonymised secure network to protect your discord and the bot's operation against attacks, so some services may block your request. If this is the case and these services are important for your script, you should proxy these requests via a system within your own control on your own server.

post

post(url, postdata, callback_function_name_string)

Retrieve a webpage via a HTTP POST request, including some post data in the form you choose. The callback_function_name_string must be the name of a function defined in your script, and not an inline function, lambda, or similar. This is because in between you calling the get() function and the callback function, the entire state of the interpreter has been reset, so there is no position to call back to except by name. Here is an example of how to use this function:

    get("https://api.myservice.com/v1/endpoint",
        JSON.stringify({"guess_what":"teapot","guess_where":"over there"}),
        "mycallback"
    );
    
    function mycallback(data) {
        create_message(CHANNEL_ID, "here's what i got back: ", data);
    }

Within the callback, the objects guild, channel, and author are not defined, however CHANNEL_ID is and you can use find_channel on this to fetch channel information, or just message a channel directly as above. If you wish to save any other state, you should use the load() and save() functions.

The callback will be passed the raw text returned from the remote web service as its single parameter.

Note that web requests will be made via an anonymised secure network to protect your discord and the bot's operation against attacks, so some services may block your request. If this is the case and these services are important for your script, you should proxy these requests via a system within your own control on your own server.

exit

exit(status)

Immediately ends the current script and yields back to the rest of the bot. This can be used in place of return at the top level of the script, as within the script at the top level you are not within a function and otherwise cannot end execution voluntarily.

add_reaction

add_reaction(channel_id, message_id, reaction_string)

Add a reaction to a message. The reaction string should be in the form :emojiname:snowflake-id, e.g. :sporks_2019:646281600182648842.

delete_reaction

delete_reaction(channel_id, message_id, reaction_string)

Delete a reaction from a message. The reaction string should be in the form :emojiname:snowflake-id, e.g. :sporks_2019:646281600182648842.

Note that this can only currently remove reactions the bot itself set on messages due to the permissions of the bot not allowing management of other user's reactions as standard.