alchemy v0.1.9 Alchemy.Client

Represents a Client connection to the Discord API. This is the main public interface for the REST API.

Summary

Functions

Adds a reaction to a message

Adds a role to a member of a guild

Bans a member from a guild

Modifies the nickname of the current user

Opens a new private channel with a user

Creates a new channel in a guild

Creates a new invite for a channel

Creates a new role in the guild

Deletes a channel from a guild

Removes an integration from a guild

Deletes an invite

Deletes a message

Deletes a list of messages

Deletes a reaction added by another user

Removes a role from a guild

Edits a channel in a guild, referenced by id

Edits a previously sent embed

Modifies a guild’s settings

Edits an integration of a guild

Modifies a member in a guild

Edits a message’s contents

Edits the client’s user_name and/or avatar

Edits a preexisting role in a guild

Gets a list of private channels open with this user

Gets a list of users banned from this guild

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

Gets a list of invites for a channel

Returns a list of channel objects for a guild

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

Gets info about a certain guild

Gets a list of integration objects for a guild

Gets the information for a single invite

Returns a list of invites for a guild

Gets info for a member of a guild

Gets a list of members from a guild

Gets a message by channel, and message_id

Gets up to 100 messages from a channel

Gets a list of pinned messages in a channel

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

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

Returns a list of voice regions in a guild

Gets a list of roles available in a guild

Gets a user by their client_id

Kicks a member from a guild

Makes the client leave a guild

Returns a list of all possible voice regions

Swaps the position of channels in a guild

Modifies the position of roles in a guild

Pins a message to its channel

Removes inactive members of a guild

Removes a reaction on a message, posted by this user

Removes all reactions from a message

Removes a role of a guild member

Sends a message to a particular channel

Starts up a new Client with the given token

Syncs a guild integration

Triggers the typing indicator

Unbans a user from the server

Removes a pinned message from a channel

Types

Functions

add_reaction(message, emoji)

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
add_role(guild_id, user_id, role_id)

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)
ban_member(guild_id, user_id, days \\ 0)

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)
change_nickname(guild_id, name)

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")
create_DM(user_id)

Opens a new private channel with a user.

Examples

Cogs.def dm_me do
 Client.create_DM(message.author.id)
end
create_channel(guild_id, name, options \\ [])

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)
create_invite(channel_id, options \\ [])

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} = Task.await Client.create_invite(message.channel_id, max_age: 0)
  Cogs.say("Here you go:\nhttps://discord.gg/#{invite.code}")
end
create_role(guild_id, options)

Specs

create_role(snowflake, name: String.t, permissions: Integer, color: Integer, hoist: Booean, mentionable: Boolean) ::
  {:ok, Alchemy.Role.t} |
  {: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)
delete_channel(channel_id)

Specs

delete_channel(snowflake) ::
  {:ok, Alchemy.Channel.t} |
  {:ok, Alchemy.Channel.dm_channel} |
  {: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} = Task.await Client.delete_channel(id)
  case channel do
    %DMChannel{} -> "this is a private channel!"
    %Channel{} -> "this is a normal channel!"
  end
end
delete_integration(guild_id, integration_id)

Specs

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

Removes an integration from a guild.

Requires the :manage_guild permission.

delete_invite(invite_code)

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.

delete_message(message)

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} = Task.await Client.send_message(channel_id, content)
Process.sleep(1000)
Client.delete_message(message)
delete_messages(channel_id, messages)

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} = Task.await Cogs.say "3..."
   Process.sleep(1000)
   {:ok, m2} = Task.await Cogs.say "2..."
   Process.sleep(1000)
   {:ok, m3} = Task.await Cogs.say "1..."
   Process.sleep(1000)
   Client.delete_messages(message.channel, [m1, m2, m3])
 end

delete_reaction(message, emoji, user)

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.

delete_role(guild_id, role_id)

Specs

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

Removes a role from a guild.

Requires the :manage_roles permission.

edit_channel(channel_id, options)

Specs

edit_channel(snowflake, name: String.t, position: Integer, topic: String.t, bitrate: Integer, user_limit: Integer) ::
  {: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.

Examples

Client.edit_channel(id, name: "the best channel", position: 1)
{:ok, new_voice_channel} = Task.await Client.edit_channel(id, bitrate: 8000)
edit_embed(message, embed)

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} = Task.await Cogs.send(embed)
 Process.sleep(2000)
 Client.edit_embed(message, embed |> color(0x5aa4d4))
end
edit_guild(guild_id, options)

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")
edit_integration(guild_id, integration_id, options)

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.
edit_member(guild_id, user_id, options)

Specs

edit_member(snowflake, snowflake, nick: String.t, roles: [snowflake], mute: Boolean, deaf: Boolean, channel_id: snowflake) ::
  {:ok, Alchemy.GuildMember.t} |
  {: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")
edit_message(message, content, opts \\ [])

Edits a message’s contents.

Examples

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

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} = Task.await Client.edit_profile(username: "NewName")
{:ok, Alchemy.User%{....
edit_role(guild_id, role_id, options)

Specs

edit_role(snowflake, snowflake, name: String.t, permissions: Integer, color: Integer, hoist: Booean, mentionable: Boolean) ::
  {:ok, Alchemy.Role.t} |
  {: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.

get_DMs()

Specs

Gets a list of private channels open with this user.

Examples

Client.get_DMs()
get_bans(guild_id)

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)
get_channel(channel_id)

Specs

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

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

Examples

{:ok, channel} = Task.await Client.get_channel("id")
get_channel_invites(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)
                 |> Task.await
  Cogs.say("there are #{length(invites)} invites active in this channel")
end

get_channels(guild_id)

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)
get_current_guilds()

Specs

get_current_guilds ::
  {:ok, [Alchemy.UserGuild.t]} |
  {:error, term}

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

Examples

{:ok, guilds} = Task.await Client.current_guilds
get_guild(guild_id)

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)
get_integrations(guild_id)

Specs

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

Gets a list of integration objects for a guild.

Requires the :manage_guild permission.

get_invite(invite_code)

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.

get_invites(guild_id)

Specs

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

Returns a list of invites for a guild.

Requires the :manage_guild permission.

get_member(guild_id, user_id)

Specs

get_member(snowflake, snowflake) ::
  {:ok, Alchemy.GuildMember.t} |
  {: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)
get_member_list(guild_id, options \\ [])

Specs

get_member_list(snowflake, limit: Integer, after: snowflake) ::
  {:ok, [Alchemy.GuildMember.t]} |
  {: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)
get_message(channel_id, message_id)

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} = Task.await Client.get_message(channel, id)

get_messages(channel_id, options)

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} = Task.await Client.get_messages(around: id, limit: 40)
get_pins(channel_id)

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} = Task.await Client.get_pins(message.channel_id)
  Cogs.say("there are #{length(pinned)} pins in this channel.")
end
get_prune_count(guild_id, days)

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.

get_reactions(arg1, emoji)

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} = Task.await Cogs.say(“react to this!”) Process.sleep(10000) {:ok, users} = Task.await Client.get_reactions(message, “❤”) Cogs.say(“#{length(users)} users reacted with a ❤!”) end

get_regions(guild_id)

Specs

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

Returns a list of voice regions in a guild.

get_roles(guild_id)

Specs

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

Gets a list of roles available in a guild.

Requires the :manage_roles permission.

Examples

Client.get_roles(guild_id)
get_user(client_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} = Task.await Client.get_user("client_id")
{:ok, Alchemy.User%{....
kick_member(guild_id, user_id)

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)
leave_guild(guild_id)

Specs

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

Makes the client leave a guild.

Examples

Client.leave_guild(guild_id)
list_voice_regions()

Specs

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

Returns a list of all possible voice regions.

move_channels(guild_id, pairs)

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} <- Task.await 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

move_roles(guild_id, pairs)

Specs

move_roles(snowflake, [{snowflake, Integer}]) ::
  {:ok, [Alchemy.Role.t]} |
  {: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.

pin(arg1)

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
prune_guild(guild_id, days)

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, )
remove_reaction(message, emoji)

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
remove_reactions(message)

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} = Task.await Cogs.say("react to this")
  Process.sleep(10000)
  Client.delete_reactions(message)
end
remove_role(guild_id, user_id, role_id)

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)
send_message(channel_id, content, options \\ [])

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

Examples

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

Starts up a new Client with the given token.

start(token, list)

Specs

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

Specs

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

Syncs a guild integration.

Requires the :manage_guild permission.

trigger_typing(channel_id)

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
unban_member(guild_id, user_id)

Specs

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

Unbans a user from the server.

Examples

Client.unban_member(guild_id, user_id)
unpin(arg1)

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|_]} = Task.await Client.get_pins(message.channel_id)
  Client.unpin(first)
end