Specs

add_member(snowflake(), snowflake(), String.t(),
  nick: String.t(),
  roles: [snowflake()],
  mute: Boolean,
  deaf: Boolean,
  channel_id: snowflake()
) :: {:ok, nil} | {:error, term()}

Adds 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.add_member(guild_id, user_id, "abc123", nick: "cool guy")

Specs

add_reaction(
  Alchemy.Message.t() | {channel_id(), message_id()},
  unicode() | Alchemy.Reaction.Emoji.t()
) :: {:ok, nil} | {:error, term()}

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

Specs

add_role(snowflake(), snowflake(), snowflake()) :: {:ok, nil} | {:error, term()}

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)

Specs

change_nickname(snowflake(), String.t()) :: {:ok, nil} | {:error, term()}

Modifies the nickname of the current user.

Examples

Client.change_nickname(guild_id, "best bot")

Returns a specification to start this module under a supervisor.

See Supervisor.

Specs

create_DM(snowflake()) :: Alchemy.Channel.dm_channel()

Opens a new private channel with a user.

Examples

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

Specs

create_channel(snowflake(), String.t(),
  voice: Boolean,
  bitrate: Integer,
  user_limit: Integer
) :: {:ok, Alchemy.Channel.t()} | {:error, term()}

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)

Specs

create_invite(snowflake(),
  max_age: Integer,
  max_uses: Integer,
  temporary: Boolean,
  unique: True
) :: {:ok, Alchemy.Channel.invite()} | {:error, term()}

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

Specs

create_role(snowflake(),
  name: String.t(),
  permissions: Integer,
  color: Integer,
  hoist: Booean,
  mentionable: Boolean
) :: {:ok, Alchemy.Guild.role()} | {:error, term()}

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)

Specs

delete_channel(snowflake()) :: {:ok, Alchemy.Channel.t()} | {:error, term()}

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!"
    %TextChannel{} -> "this is a normal channel!"
  end
end

Specs

delete_integration(snowflake(), snowflake()) :: {:ok, nil} | {:error, term()}

Removes an integration from a guild.

Requires the :manage_guild permission.

Specs

delete_invite(String.t()) :: {:ok, nil} | {:error, term()}

Deletes an invite.

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

Specs

delete_message(Alchemy.Message.t() | {channel_id(), message_id()}) ::
  {:ok, nil} | {:error, term()}

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)

Specs

delete_messages(snowflake(), [Alchemy.Message.t() | snowflake()]) ::
  {:ok, nil} | {:error, term()}

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

Specs

delete_reaction(
  Alchemy.Message.t() | {channel_id(), message_id()},
  unicode() | Alchemy.Reaction.Emoji.t(),
  snowflake() | Alchemy.User.t()
) :: {:ok, nil} | {:error, term()}

Deletes a reaction added by another user.

Requires the MANAGE_MESSAGES permission.

Specs

delete_role(snowflake(), snowflake()) :: {:ok, nil} | {:error, term()}

Removes a role from a guild.

Requires the :manage_roles permission.

Specs

edit_channel(snowflake(),
  name: String.t(),
  position: Integer,
  topic: String.t(),
  bitrate: Integer,
  user_limit: Integer,
  nsfw: Boolean.t(),
  parent_id: snowflake()
) :: {:ok, Alchemy.Channel.t()} | {:error, term()}

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.
• nsfw whether or not the channel is nsfw
• parent_id the id of the new parent category for a channel

Examples

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

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

Specs

edit_embed(
  Alchemy.Message.t() | {channel_id(), message_id()},
  Alchemy.Embed.t()
) :: {:ok, Alchemy.Message.t()} | {:error, term()}

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

Specs

edit_guild(snowflake(),
  name: String.t(),
  region: snowflake(),
  verification_level: Integer,
  default_message_notifications: Integer,
  afk_channel_id: snowflake(),
  afk_timeout: snowflake(),
  icon: url(),
  splash: url()
) :: {:ok, Alchemy.Guild.t()} | {:error, term()}

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")

Specs

edit_integration(snowflake(), snowflake(),
  expire_behaviour: Integer,
  expire_grace_period: Integer,
  enable_emoticons: Boolean
) :: {:ok, nil} | {:error, term()}

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.

Specs

edit_member(snowflake(), snowflake(),
  nick: String.t(),
  roles: [snowflake()],
  mute: Boolean,
  deaf: Boolean,
  channel_id: snowflake()
) :: {:ok, nil} | {:error, term()}

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!")

Specs

edit_profile(username: String.t(), avatar: url()) ::
  {:ok, Alchemy.User.t()} | {:error, term()}

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%{....

Specs

edit_role(snowflake(), snowflake(),
  name: String.t(),
  permissions: Integer,
  color: Integer,
  hoist: Booean,
  mentionable: Boolean
) :: {:ok, Alchemy.Guild.role()} | {:error, term()}

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.

Specs

get_DMs() :: [Alchemy.Channel.dm_channel()]

Gets a list of private channels open with this user.

Examples

Client.get_DMs()

Specs

get_bans(snowflake()) :: {:ok, [Alchemy.User.t()]} | {:error, term()}

Gets a list of users banned from this guild.

Requires the :ban_members permission.

Examples

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

Specs

get_channel(snowflake()) :: {:ok, Alchemy.Channel.t()} | {:error, term()}

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

Examples

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

Specs

get_channel_invites(snowflake()) ::
  {:ok, [Alchemy.Channel.invite()]} | {:error, term()}

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

Specs

get_channels(snowflake()) :: {:ok, [Alchemy.Channel.t()]} | {:error, term()}

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)

Specs

get_current_guilds() :: {:ok, [Alchemy.User.user_guild()]} | {:error, term()}

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

Examples

{:ok, guilds} = Client.current_guilds

Specs

get_guild(snowflake()) :: {:ok, Alchemy.Guild.t()} | {:error, term()}

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)

Specs

get_integrations(snowflake()) :: {:ok, %{}} | {:error, term()}

Gets a list of integration objects for a guild.

Requires the :manage_guild permission.

Specs

get_invite(String.t()) :: {:ok, Alchemy.Channel.invite()} | {:error, term()}

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.

Specs

get_invites(snowflake()) :: {:ok, [Alchemy.Channel.invite()]} | {:error, term()}

Returns a list of invites for a guild.

Requires the :manage_guild permission.

Specs

get_member(snowflake(), snowflake()) ::
  {:ok, Alchemy.Guild.member()} | {:error, term()}

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)

Specs

get_member_list(snowflake(), limit: Integer, after: snowflake()) ::
  {:ok, [Alchemy.Guild.member()]} | {:error, term()}

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)

Specs

get_message(snowflake(), snowflake()) ::
  {:ok, Alchemy.Message.t()} | {:error, term()}

Gets a message by channel, and message_id

Use get_messages for a bulk request instead.

Examples

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

Specs

get_messages(snowflake(),
  around: snowflake(),
  before: snowflake(),
  after: snowflake(),
  limit: Integer
) :: {:ok, [Alchemy.Message.t()]} | {:error, term()}

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)

Specs

get_pins(snowflake()) :: {:ok, [Alchemy.Message.t()]} | {:error, term()}

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

Specs

get_prune_count(snowflake(), Integer) :: {:ok, nil} | {:error, term()}

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.

Specs

get_reactions(
  Alchemy.Message.t() | {channel_id(), message_id()},
  unicode() | Alchemy.Reaction.Emoji.t()
) :: {:ok, [Alchemy.User.t()]} | {:error, term()}

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

Specs

get_regions(snowflake()) :: {:ok, [Alchemy.VoiceRegion.t()]} | {:error, term()}

Returns a list of voice regions in a guild.

Specs

get_roles(snowflake()) :: {:ok, [Alchemy.Guild.role()]} | {:error, term()}

Gets a list of roles available in a guild.

Requires the :manage_roles permission.

Examples

Client.get_roles(guild_id)

Specs

get_user(snowflake()) :: {:ok, Alchemy.User.t()} | {:error, term()}

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%{....

Callback implementation for Supervisor.init/1.

Specs

kick_member(snowflake(), snowflake()) :: {:ok, nil} | {:error, term()}

Kicks a member from a guild.

Not to be confused with ban_member/3.

Examples

Client.kick_member(guild_id, user_id)

Specs

leave_guild(snowflake()) :: {:ok, nil} | {:error, term()}

Makes the client leave a guild.

Examples

Client.leave_guild(guild_id)

Specs

list_voice_regions() :: {:ok, [Alchemy.VoiceRegion.t()]} | {:error, term()}

Returns a list of all possible voice regions.

Specs

move_channels(snowflake(), [{snowflake(), Integer}]) ::
  {:ok, nil} | {:error, term()}

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

Specs

move_roles(snowflake(), [{snowflake(), Integer}]) ::
  {:ok, [Alchemy.Guild.role()]} | {:error, term()}

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.

Specs

pin(Alchemy.Message.t() | {channel_id(), message_id()}) ::
  {:ok, nil} | {:error, term()}

Pins a message to its channel.

Examples

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

Specs

prune_guild(snowflake(), Integer) :: {:ok, nil} | {:error, term()}

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, )

Specs

remove_reaction(
  Alchemy.Message.t() | {channel_id(), message_id()},
  unicode() | Alchemy.Reaction.Emoji.t()
) :: {:ok, nil} | {:error, term()}

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

Specs

remove_reactions(Alchemy.Message.t() | {channel_id(), message_id()}) ::
  {:ok, nil} | {:error, term()}

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

Specs

remove_role(snowflake(), snowflake(), snowflake()) ::
  {:ok, nil} | {:error, term()}

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!", file: "foo.txt")

Specs

start(token(), [{:selfbot, snowflake()}]) :: {:ok, pid()}

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.

Specs

sync_integration(snowflake(), snowflake()) :: {:ok, nil} | {:error, term()}

Syncs a guild integration.

Requires the :manage_guild permission.

Specs

trigger_typing(snowflake()) :: {:ok, nil} | {:error, term()}

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

Specs

unban_member(snowflake(), snowflake()) :: {:ok, nil} | {:error, term()}

Unbans a user from the server.

Examples

Client.unban_member(guild_id, user_id)

Specs

unpin(Alchemy.Message.t() | {channel_id(), message_id()}) ::
  {:ok, nil} | {:error, term()}

Removes a pinned message from a channel.

Examples

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

Specs

update_status(Integer, playing: String.t(), streaming: {String.t(), String.t()}) ::
  :ok | {:error, String.t()}

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")