Adds a reaction to a message.

This supports sending either a custom emoji object, or a unicode literal. While sending raw unicode is technically possible, you’ll usually run into url encoding issues due to hidden characters if you try to send something like “❤️️”; use \u2764 instead.

Examples

Cogs.def heart do
  Client.add_reaction(message, "️\u2764")
end

Adds a role to a member of a guild.

Requires the :manage_roles permission.

Examples

Client.add_role(guild_id, user_id, role_id)

Bans a member from a guild.

This prevents a user from rejoining for as long as the ban persists, as opposed to kick_member/2 which will just make them leave the server.

A days paramater can be set to delete x days of messages; limited to 7.

Examples

Client.ban_member(guild_id, user_id, 1)

Modifies the nickname of the current user.

Examples

Client.change_nickname(guild_id, "best bot")

Opens a new private channel with a user.

Examples

Cogs.def dm_me do
 Client.create_DM(message.author.id)
end

Creates a new channel in a guild.

Requires the MANAGE_CHANNELS permission.

Options

• voice Setting this creates a new voice channel.
• bitrate Sets the bitrate (bits) for a voice channel.
• user_limit Sets the max amount of users for a voice channel.
• permission_overwrites An overwrite for permissions in that channel

Examples

Client.create_channel(guild_id)

Creates a new invite for a channel.

Requires the CREATE_INSTANT_INVITE permission.

Options

• max_age

  The duration (seconds) of the invite. 0 for never.

• max_uses

  The max number of uses. 0 for unlimited.

• temporary

  Whether this invite grants temporary membership.

• unique

  When set, a similar invite won’t try to be used. Useful for creating unique one time use invites.

Examples

Cogs.def invite do
  {:ok, invite} = Client.create_invite(message.channel_id, max_age: 0)
  Cogs.say("Here you go:\nhttps://discord.gg/#{invite.code}")
end

Creates a new role in the guild.

Requires the :manage_roles permission.

Options

• name The name of the new role. Defaults to “new role”
• permissions The set of permissions for that role. Defaults to the @everyone permissions in that guild.
• color The color of the role. Defaults to 0x000000
• hoist When set to true, the role will be displayed seperately in the sidebar.
• mentionable When set to true, allows the role to be mentioned.

Examples

Client.create_role(guild_id, name: "the best role", color: 0x4bd1be)

Deletes a channel from a guild.

Here’s an example of how to deal with the possible return types using pattern matching:

def my_delete(id) do
 {:ok, channel} = Client.delete_channel(id)
  case channel do
    %DMChannel{} -> "this is a private channel!"
    %Channel{} -> "this is a normal channel!"
  end
end

Removes an integration from a guild.

Requires the :manage_guild permission.

Deletes an invite.

After deletion the invite can no longer be used, as you might expect.

Deletes a message.

Requires the MANAGE_MESSAGES permission for messages not sent by the user.

Examples

content = "self destructing in 1s!!!"
{:ok, message} = Client.send_message(channel_id, content)
Process.sleep(1000)
Client.delete_message(message)

Deletes a list of messages.

Requires the MANAGE_MESSAGES permission for messages not posted by this user. Can only delete messages up to 2 weeks old.

 Cogs.def countdown do
   {:ok, m1} = Cogs.say "3..."
   Process.sleep(1000)
   {:ok, m2} = Cogs.say "2..."
   Process.sleep(1000)
   {:ok, m3} = Cogs.say "1..."
   Process.sleep(1000)
   Client.delete_messages(message.channel, [m1, m2, m3])
 end

Deletes a reaction added by another user.

Requires the MANAGE_MESSAGES permission.

Removes a role from a guild.

Requires the :manage_roles permission.

Edits a channel in a guild, referenced by id.

All the paramaters are optional. Some are mutually exclusive. I.E. you can’t use voice only and text only parameters in the same request.

Options

• name the name for the channel
• position the position in the left hand listing
• topic ~ text only ~ the topic of the channel
• bitrate ~ voice only ~ the bitrate, in bits, from 8000 to 96000, for the voice channel to take
• user_limit ~ voice only ~ the max amount of users allowed in this channel. From 1 to 99, or 0 for no limit.

Examples

Client.edit_channel(id, name: "the best channel", position: 1)

{:ok, new_voice_channel} = Client.edit_channel(id, bitrate: 8000)

Edits a previously sent embed.

Note that this can be accomplished via edit_message/3 as well, but that requires editing the content as well.

Cogs.def embed do
 embed = %Embed{description: "the best embed"}
         |> color(0xc13261)
 {:ok, message} = Embed.send(embed)
 Process.sleep(2000)
 Client.edit_embed(message, embed |> color(0x5aa4d4))
end

Modifies a guild’s settings.

Options

• name The name of the guild.
• region The id of the voice region.
• verification_level The level of verification of the guild.
• default_message_notifications The default message notification settings.
• afk_channel_id The id of the afk channel.
• afk_timeout The afk timeout in seconds.
• icon A url to the new icon. Must be a 128x128 jpeg image.
• splash A url to the new splash screen. This is only available for partnered guilds.

Examples

Client.edit_guild(guild_id, name: "new name")

Edits an integration of a guild.

Requires the :manage_guild permission.

Options

• expire_behaviour The behaviour when an integration subscription lapses.
• expire_grace_period Period (seconds) where the integration ignores lapsed subscriptions.
• enable_emoticons Whether or not emoticons should be synced for this integration.

Modifies a member in a guild.

Each option requires different permissions.

Options

• nick The nickname of the user. Requires :manage_nicknames
• roles A list of roles (ids) the user should have after the change. Requires :manage_roles
• mute Whether or not the user should be muted. Requires :mute_members
• deaf Whether or not the user should be deafened. Requires :deafen_members
• channel_id Voice channel to move the user too (if they are connected). Requires :move_members, and permission to connect to that channel.

Examples

Client.edit_member(guild_id, user_id, nick: "cool guy")

Edits a message’s contents.

Examples

{:ok, message} = Client.send_message(channel, "ping!")
Process.sleep(1000)
Client.edit_message(message, "not ping anymore!")

Edits the client’s user_name and/or avatar.

Options

• user_name A string specifiying the new user_name for the client
• avatar A link to an image for the client’s avatar

Examples

# Will edit "behind the scenes"
Client.edit_profile(username: "NewGuy", avatar: "imgur.com/image.jpeg")

iex> {:ok, user} = Client.edit_profile(username: "NewName")
{:ok, Alchemy.User%{....

Edits a preexisting role in a guild.

The same as create_role/2 except that this operates on a role that has already been created. See that function for discussion.

Gets a list of private channels open with this user.

Examples

Client.get_DMs()

Gets a list of users banned from this guild.

Requires the :ban_members permission.

Examples

{:ok, bans} = Client.get_bans(guild_id)

Gets a channel by its ID. Works on both private channels, and guild channels.

Examples

{:ok, channel} = Client.get_channel("id")

Gets a list of invites for a channel.

Only usable for guild channels.

Examples

Cogs.def count_invites do
  {:ok, invites} = Client.get_channel_invites(message.channel_id)
  Cogs.say("there are #{length(invites)} invites active in this channel")
end

Returns a list of channel objects for a guild.

As with most guild methods, the cache should be preferred over the api if possible.

Examples

Client.get_channels(guild_id)

Gets a list of guilds the client is currently a part of.

Examples

{:ok, guilds} = Client.current_guilds

Gets info about a certain guild.

The info returned here doesn’t contain as much info as contained in the cache. For guilds the user is a part of, the cache should be preferred over this method.

Client.get_guild(id)

Gets a list of integration objects for a guild.

Requires the :manage_guild permission.

Gets the information for a single invite.

Not to be confused with get_invites/1, which lists out the invites in a guild. This merely gets the information relating to a single invite, accessed by its code.

Returns a list of invites for a guild.

Requires the :manage_guild permission.

Gets info for a member of a guild.

For guilds the bot is in, use the corresponding cache method instead.

Examples

Client.get_member(guild_id, user_id)

Gets a list of members from a guild.

Options

• limit The number of members to fetch (max 1000).
• after Setting this to a user id will only fetch members that joined after that person.

Examples

Client.get_member_list(guild_id, limit: 10)

Gets a message by channel, and message_id

Use get_messages for a bulk request instead.

Examples

{:ok, message} = Client.get_message(channel, id)

Gets up to 100 messages from a channel.

around, before, after are all mutually exclusive.

Options

• around will search for messages around the time of a particular message
• before will get messages before a certain message
• after will get messages after a certain message
• limit the number of messages to get. Defaults to 100

Examples

{:ok, messages} = Client.get_messages(around: id, limit: 40)

Gets a list of pinned messages in a channel.

Examples

Cogs.def pins do
  {:ok, pinned} = Client.get_pins(message.channel_id)
  Cogs.say("there are #{length(pinned)} pins in this channel.")
end

Returns a count of members who would be kicked in a prune operation.

Days specifies the amount of days of inactivity to check for.

See prune_guild/2 for a discussion of this operation.

Gets a list of users who reacted to message with a particular emoji.

Examples

Cogs.def react do {:ok, message} = Cogs.say(“react to this!”) Process.sleep(10000) {:ok, users} = Client.get_reactions(message, “❤”) Cogs.say(“#{length(users)} users reacted with a ❤!”) end

Returns a list of voice regions in a guild.

Gets a list of roles available in a guild.

Requires the :manage_roles permission.

Examples

Client.get_roles(guild_id)

Gets a user by their client_id.

"@me" can be passed to get the info relevant to the Client.

Examples

iex> {:ok, user} = Client.get_user("client_id")
{:ok, Alchemy.User%{....

Kicks a member from a guild.

Not to be confused with ban_member/3.

Examples

Client.kick_member(guild_id, user_id)

Makes the client leave a guild.

Examples

Client.leave_guild(guild_id)

Returns a list of all possible voice regions.

Swaps the position of channels in a guild.

Examples

# alphabetizes a guild channel list
with {:ok, channels} <- Client.get_channels(guild_id) do
  channels
  |> Enum.sort_by(& &1.name)
  |> Stream.map(& &1.id)
  |> Enum.with_index
  |> (&Client.move_channels(guild_id, &1)).()
end

Modifies the position of roles in a guild.

Takes a list of {id, position} where position is an integer starting at 0, and id is the id of the role.

Returns a list of all the roles in the guild.

Requires the :manage_roles permission.

Pins a message to its channel.

Examples

Cogs.def pin_this do
  Client.pin(message)
end

Removes inactive members of a guild.

Days allows you to specify the amount of days of inactivity necessary to be kicked from the guild.

Requires the :manage_roles permission

Examples

Client.prune_guild(guild_id, )

Removes a reaction on a message, posted by this user.

This doesn’t require the MANAGE_MESSAGES permission, unlike delete_reaction.

Example

Cogs.def indecisive do
Client.add_reaction(message, "❤")
Process.sleep(3000)
Client.remove_reaction(message, "❤")
end

Removes all reactions from a message.

Requires the MANAGE_MESSAGES permission.

Examples

Cogs.def psyche do
  {:ok, message} = Cogs.say("react to this")
  Process.sleep(10000)
  Client.delete_reactions(message)
end

Removes a role of a guild member.

Requires the :manage_roles permission.

Examples

Client.remove_role(guild_id, user_id, role_id)

Sends a message to a particular channel

Options

• tts used to set whether or not a message should be text to speech
• embed used to send an Embed object along with the message
• file used to send a file along with the message

Examples

{:ok, message} = Client.send_message(chan_id, "pong!")

Sending files along with messages is simple as well.

Client.send_message(chan_id, "here you go!", "foo.txt")

Starts up a new Client with the given token.

An optional selfbot: id can be passed, indiciating that you’re using a user token instead of a normal bot token. SelfBots will only respond to themselves, and certain functionalities of the API may not work as well as for normal bots.

Syncs a guild integration.

Requires the :manage_guild permission.

Triggers the typing indicator.

This shouldn’t be used by bots usually.

Examples

Cogs.def hard_math do
  Client.trigger_typing(message.channel_id)
  Process.sleep(3000)
  Cogs.say("done!")
end

Unbans a user from the server.

Examples

Client.unban_member(guild_id, user_id)

Removes a pinned message from a channel.

Examples

Cogs.def unpin do
  {:ok, [first|_]} = Client.get_pins(message.channel_id)
  Client.unpin(first)
end

Updates the status of the client.

The status displays either “playing Game”, or a “streaming Game” message under the client, as well setting an inactivity based on idleness.

playing: game specifies that you’re playing, but not streaming a game. streaming: {game, twitch} acts in a similar way, except that it will also have a link to that twitch stream. You should only pass in the handle, and not the full stream link, i.e. “foobar” instead of “twitch.tv/foobar”. idle_since can be specified, using unix time, in milliseconds, to indicate for how long the client has been idle.

Note on ratelimiting

This functionality is heavily ratelimited, at a rate of 1 req / 12s. Because of this, this function will automatically error after 24s of waiting. Because of how long this may take, you might want to run this in a new task.

Examples

Client.update_status("Alchemy")