Alchemy.Client (alchemy v0.6.8)

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

As you might have seen in other examples, this module is the main entry point for Alchemy. start/2 will start up the necessary modules and caches necessary to hook into discord. You generally want to do this before you do any other work in your bot really.

Blocking

All the requests here will block the process using them. Since all the event handles and commands created with this framework run in concurrent processes, this isn't usually an issue. If you do want to "fire and forget", it's easy to wrap these requests in a task.

Caching

In general, you should try and use the functions provided by Alchemy.Cache over the requests in this module, because the cache functions will be much faster, and avoid excess API requests.

Link to this section 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.

Returns a specification to start this module under a supervisor.

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.

Callback implementation for Supervisor.init/1.

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.

Updates the status of the client.

Link to this section Types

Link to this type

channel_id()

Specs

channel_id() :: snowflake()
Link to this type

message_id()

Specs

message_id() :: snowflake()

Specs

snowflake() :: String.t()

Specs

token() :: String.t()

Specs

unicode() :: String.t()

Specs

url() :: String.t()

Link to this section Functions

Link to this function

add_member(guild_id, user_id, access_token, options \\ [])

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")
Link to this function

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
Link to this function

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)
Link to this function

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)
Link to this function

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")
Link to this function

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

create_DM(user_id)

Specs

Opens a new private channel with a user.

Examples

Cogs.def dm_me do
 Client.create_DM(message.author.id)
end
Link to this function

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)
Link to this function

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

create_role(guild_id, options)

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)
Link to this function

delete_channel(channel_id)

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
Link to this function

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.

Link to this function

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.

Link to this function

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} = Client.send_message(channel_id, content)
Process.sleep(1000)
Client.delete_message(message)
Link to this function

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} = 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
Link to this function

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.

Link to this function

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.

Link to this function

edit_channel(channel_id, options)

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)
Link to this function

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} = Embed.send(embed)
 Process.sleep(2000)
 Client.edit_embed(message, embed |> color(0x5aa4d4))
end
Link to this function

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")
Link to this function

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.
Link to this function

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, 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")
Link to this function

edit_message(message, content, opts \\ [])

Edits a message's contents.

Examples

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

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} = Client.edit_profile(username: "NewName")
{:ok, Alchemy.User%{....
Link to this function

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.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()
Link to this function

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)
Link to this function

get_channel(channel_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")
Link to this function

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)
  Cogs.say("there are #{length(invites)} invites active in this channel")
end
Link to this function

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)
Link to this function

get_current_guilds()

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
Link to this function

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)
Link to this function

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.

Link to this function

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.

Link to this function

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.

Link to this function

get_member(guild_id, user_id)

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)
Link to this function

get_member_list(guild_id, options \\ [])

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)
Link to this function

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} = Client.get_message(channel, id)
Link to this function

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} = Client.get_messages(around: id, limit: 40)
Link to this function

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} = Client.get_pins(message.channel_id)
  Cogs.say("there are #{length(pinned)} pins in this channel.")
end
Link to this function

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.

Link to this function

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

Link to this function

get_regions(guild_id)

Specs

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

Returns a list of voice regions in a guild.

Link to this function

get_roles(guild_id)

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)
Link to this function

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} = Client.get_user("client_id")
{:ok, Alchemy.User%{....

Callback implementation for Supervisor.init/1.

Link to this function

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)
Link to this function

leave_guild(guild_id)

Specs

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

Makes the client leave a guild.

Examples

Client.leave_guild(guild_id)
Link to this function

list_voice_regions()

Specs

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

Returns a list of all possible voice regions.

Link to this function

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} <- 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
Link to this function

move_roles(guild_id, pairs)

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
Link to this function

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, )
Link to this function

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
Link to this function

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} = Cogs.say("react to this")
  Process.sleep(10000)
  Client.delete_reactions(message)
end
Link to this function

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)
Link to this function

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
  • 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")
Link to this function

start(token, options \\ [])

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.

Link to this function

sync_integration(guild_id, integration_id)

Specs

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

Syncs a guild integration.

Requires the :manage_guild permission.

Link to this function

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
Link to this function

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)

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
Link to this function

update_status(idle_since \\ nil, game_info)

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