Nostrum v0.3.1 Nostrum.Api View Source

Interface for Discord's rest API.

By default all methods in this module are ran synchronously. If you wish to have async rest operations I recommend you execute these functions inside of a task.

Examples

# Async Task
t = Task.async fn ->
  Nostrum.Api.get_channel_messages(12345678912345, :infinity, {})
end
messages = Task.await t

# A lot of times we don't care about the return value of the function
Task.start fn ->
  messages = ["in", "the", "end", "it", "doesn't", "even", "matter"]
  Enum.each messages, &Nostrum.Api.create_message!(12345678912345, &1)
end

A note about Strings and Ints

Currently, responses from the REST api will have id fields as string. Everything received from the WS connection will have id fields as int.

If you're processing a response from the API and trying to access something in the cache based off of an id in the response, you will need to conver it to an int using String.to_integer/1. I'm open to suggestions for how this should be handled going forward.

Example

messages = Nostrum.Api.get_pinned_messages!(12345678912345)

authors =
  Enum.map messages, fn msg ->
    author_id = String.to_integer(msg.author.id)
    Nostrum.Cache.User.get!(id: author_id)
  end

Link to this section Summary

Types

Represents an emoji for interacting with reaction endpoints

Represents a failed response from the API

Represents a limit used to retrieve messages

Represents a tuple used to locate messages

Represents optional parameters for Api functions

Represents different statuses the bot can have

Functions

Begins a guild prune to prune members within days

Deletes multiple messages from a channel

Deletes multiple messages from a channel

Creates an invite for a guild channel

Create a new DM channel with a user

Same as create_dm/1, but raises Nostrum.Error.ApiError in case of failure

Creates a new group DM channel

Creates a channel for a guild

Creates a new emoji for the given guild

Creates a new guild integeration

Posts a message to a guild text or DM channel

Creates a reaction for a message

Deletes all reactions from a message

Deletes a channel

Delete a channel permission for a user or role

Deletes a guild

Same as delete_guild/1, but raises Nostrum.Error.ApiError in case of failure

Deletes the given emoji

Deletes a role from a guild

Deletes an invite by its invite_code

Same as delete_invite/1, but raises Nostrum.Error.ApiError in case of failure

Same as delete_message/1, but raises Nostrum.Error.ApiError in case of failure

Deletes a reaction the current user has made for the message

Deletes another user's reaction from a message

Deletes a webhook

Edit the permission overwrites for a user or role

Edit the permission overwrites for a user or role

Same as edit_message/3, but takes a Nostrum.Struct.Message instead of a channel_id and message_id

Edits a previously sent message in a channel

Gets a channel

Same as get_channel/1, but raises Nostrum.Error.ApiError in case of failure

Gets a list of invites for a channel

Retrieves a message from a channel

Retrives a channel's messages around a locator up to a limit

Gets a list of webook for a channel

Gets info on the current user

Same as get_current_user/0, but raises Nostrum.Error.ApiError in case of failure

Gets a list of guilds the user is currently in

Gets a guild

Same as get_guild/1, but raises Nostrum.Error.ApiError in case of failure

Gets a list of users banend from a guild

Gets a list of guild channels

Gets a guild embed

Gets an emoji for the given guild and emoji ids

Gets a list of guild integerations

Gets a list of invites for a guild

Gets the number of members that would be removed in a prune given days

Gets a guild's roles

Gets a list of webooks for a guild

Gets an invite by its invite_code

Same as get_invite/1, but raises Nostrum.Error.ApiError in case of failure

Retrieves all pinned messages from a channel

Gets all users who reacted with an emoji

Returns the token of the bot

Same as get_user/1, but raises Nostrum.Error.ApiError in case of failure

Gets a list of user connections

Gets a list of our user's DM channels

Same as get_user_dms/0, but raises Nostrum.Error.ApiError in case of failure

Gets a list of voice regions for the guild

Gets a webhook by id

Gets a webhook by id and token

Leaves a guild

Gets a list of emojis for a given guild

Gets a list of a guild's members

Gets a list of voice regions

Modifies a channel's settings

Changes the username or avatar of the current user

Same as modify_current_user/3, but raises Nostrum.Error.ApiError in case of failure

Modifies a guild's settings

Modifies a guild imbed

Changes the settings and behaviours for a guild integeration

Modifies a guild member's attributes

Removes a ban for a user

Removes a member from a guild

Triggers the typing indicator

Triggers the typing indicator

Updates the status of the bot for a certain shard

Updates the status of the bot for all shards

Link to this section Types

Represents an emoji for interacting with reaction endpoints.

Represents a failed response from the API.

This occurs when hackney or HTTPoison fail, or when the API doesn't respond with 200 or 204.

Link to this type

limit() View Source
limit() :: integer() | :infinity

Represents a limit used to retrieve messages.

Integer number of messages, or :infinity to retrieve all messages.

Link to this type

locator() View Source
locator() ::
  {:before, integer()} | {:after, integer()} | {:around, integer()} | {}

Represents a tuple used to locate messages.

The first element of the tuple is an atom. The second element will be a message_id as an integer. The tuple can also be empty to search from the most recent message in the channel

Link to this type

options() View Source
options() :: keyword() | map()

Represents optional parameters for Api functions.

Each function has documentation regarding what parameters it supports or needs.

Link to this type

status() View Source
status() :: :dnd | :idle | :online | :invisible

Represents different statuses the bot can have.

  • :dnd - Red circle.
  • :idle - Yellow circle.
  • :online - Green circle.
  • :invisible - The bot will appear offline.

Link to this section Functions

Link to this function

add_guild_member(guild_id, user_id, options) View Source

Puts a user in a guild.

This endpoint fires the Nostrum.Consumer.guild_member_add/0 event. It requires the CREATE_INSTANT_INVITE permission. Additionally, it situationally requires the MANAGE_NICKNAMES, MANAGE_ROLES, MUTE_MEMBERS, and DEAFEN_MEMBERS permissions.

If successful, returns {:ok, member}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :access_token (string) - the user's oauth2 access token
  • :nick (string) - value to set users nickname to
  • :roles (list of Nostrum.Struct.Guild.Role.id/0) - array of role ids the member is assigned
  • :mute (boolean) - if the user is muted
  • :deaf (boolean) - if the user is deafened

:access_token is always required.

Examples

Nostrum.Api.add_guild_member(
  41771983423143937,
  18374719829378473,
  access_token: "6qrZcUqja7812RVdnEKjpzOL4CvHBFG",
  nick: "nostrum",
  roles: [431849301, 913809431]
)
Link to this function

add_guild_member!(guild_id, user_id, options) View Source

Same as add_guild_member/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

add_guild_member_role(guild_id, user_id, role_id) View Source
add_guild_member_role(integer(), integer(), integer()) :: error() | {:ok}

Adds a role to a member.

Role to add is specified by role_id. User to add role to is specified by guild_id and user_id.

Link to this function

add_pinned_channel_message(channel_id, message_id) View Source
add_pinned_channel_message(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id()
) :: error() | {:ok}

Pins a message in a channel.

This endpoint requires the 'VIEW_CHANNEL', 'READ_MESSAGE_HISTORY', and 'MANAGE_MESSAGES' permissions. It fires the Nostrum.Consumer.message_update/0 and Nostrum.Consumer.channel_pins_update/0 events.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.add_pinned_channel_message(43189401384091, 18743893102394)
Link to this function

add_pinned_channel_message!(channel_id, message_id) View Source
add_pinned_channel_message!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id()
) :: no_return() | {:ok}

Same as add_pinned_channel_message/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

begin_guild_prune(guild_id, days) View Source
begin_guild_prune(Nostrum.Struct.Guild.id(), 1..30) ::
  error() | {:ok, %{pruned: integer()}}

Begins a guild prune to prune members within days.

This endpoint requires the KICK_MEMBERS permission. It fires multiple Nostrum.Consumer.guild_member_remove/0 events.

If successful, returns {:ok, %{pruned: pruned}}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.begin_guild_prune(81384788765712384, 1)
{:ok, %{pruned: 0}}
Link to this function

begin_guild_prune!(guild_id, days) View Source
begin_guild_prune!(Nostrum.Struct.Guild.id(), 1..30) ::
  no_return() | %{pruned: integer()}

Same as begin_guild_prune/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

bulk_delete_messages(channel_id, messages, filter \\ true) View Source
bulk_delete_messages(integer(), [Nostrum.Struct.Message.id()], boolean()) ::
  error() | {:ok}

Deletes multiple messages from a channel.

messages is a list of Nostrum.Struct.Message.id that you wish to delete. When given more than 100 messages, this function will chunk the given message list into blocks of 100 and send them off to the API. It will stop deleting on the first error that occurs. Keep in mind that deleting thousands of messages will take a pretty long time and it may be proper to just delete the channel you want to bulk delete in and recreate it.

This method can only delete messages sent within the last two weeks. Filter is an optional parameter that specifies whether messages sent over two weeks ago should be filtered out; defaults to true.

Link to this function

bulk_delete_messages!(channel_id, messages, filter \\ true) View Source
bulk_delete_messages!(integer(), [Nostrum.Struct.Message.id()], boolean()) ::
  no_return() | {:ok}

Deletes multiple messages from a channel.

See bulk_delete_messages/2 for more info.

Raises Nostrum.Error.ApiError if error occurs while making the rest call.

Link to this function

create_channel_invite(channel_id, options \\ []) View Source

Creates an invite for a guild channel.

This endpoint requires the CREATE_INSTANT_INVITE permission.

If successful, returns {:ok, invite}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :max_age (integer) - duration of invite in seconds before expiry, or 0 for never. (default: 86400)
  • :max_uses (integer) - max number of uses or 0 for unlimited. (default: 0)
  • :temporary (boolean) - Whether the invite should grant temporary membership. (default: false)
  • :unique (boolean) - used when creating unique one time use invites. (default: false)

Examples

Nostrum.Api.create_channel_invite(41771983423143933)
{:ok, Nostrum.Struct.Invite{}}

Nostrum.Api.create_channel_invite(41771983423143933, max_uses: 20)
{:ok, %Nostrum.Struct.Invite{}}
Link to this function

create_channel_invite!(channel_id, options \\ []) View Source

Same as create_channel_invite/2, but raises Nostrum.Error.ApiError in case of failure.

Create a new DM channel with a user.

If successful, returns {:ok, dm_channel}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.create_dm(150061853001777154)
{:ok, %Nostrum.Struct.Channel{type: 1}}

Same as create_dm/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

create_group_dm(access_tokens, nicks) View Source
create_group_dm([String.t()], %{
  optional(Nostrum.Struct.User.id()) => String.t()
}) :: error() | {:ok, Nostrum.Struct.Channel.group_dm_channel()}

Creates a new group DM channel.

If successful, returns {:ok, group_dm_channel}. Otherwise, returns a Nostrum.Api.error/0.

access_tokens are user oauth2 tokens. nicks is a map that maps a user id to a nickname.

Examples

Nostrum.Api.create_group_dm(["6qrZcUqja7812RVdnEKjpzOL4CvHBFG"], %{41771983423143937 => "My Nickname"})
{:ok, %Nostrum.Struct.Channel{type: 3}}
Link to this function

create_group_dm!(access_tokens, nicks) View Source
create_group_dm!([String.t()], %{
  optional(Nostrum.Struct.User.id()) => String.t()
}) :: no_return() | Nostrum.Struct.Channel.group_dm_channel()

Same as create_group_dm/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

create_guild_ban(guild_id, user_id, days_to_delete) View Source
create_guild_ban(integer(), integer(), integer()) :: error() | {:ok}

Bans a user from a guild.

User to delete is specified by guild_id and user_id.

Link to this function

create_guild_channel(guild_id, options) View Source
create_guild_channel(Nostrum.Struct.Guild.id(), options()) ::
  error() | {:ok, Nostrum.Struct.Channel.guild_channel()}

Creates a channel for a guild.

This endpoint requires the MANAGE_CHANNELS permission. It fires a Nostrum.Consumer.channel_create/0 event.

If successful, returns {:ok, channel}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :name (string) - channel name (2-100 characters)
  • :type (integer) - the type of channel (See Nostrum.Struct.Channel)
  • :topic (string) - channel topic (0-1024 characters)
  • :bitrate (integer) - the bitrate (in bits) of the voice channel (voice only)
  • :user_limit (integer) - the user limit of the voice channel (voice only)
  • :permission_overwrites (list of Nostrum.Struct.Overwrite.t/0 or equivalent map) - the channel's permission overwrites
  • :parent_id (Nostrum.Struct.Channel.id/0) - id of the parent category for a channel
  • :nsfw (boolean) - if the channel is nsfw

:name is always required.

Examples

Nostrum.Api.create_guild_channel(81384788765712384, name: "elixir-nostrum", topic: "craig's domain")
{:ok, %Nostrum.Struct.Channel{guild_id: 81384788765712384}}
Link to this function

create_guild_channel!(guild_id, options) View Source

Same as create_guild_channel/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

create_guild_emoji(guild_id, options) View Source
create_guild_emoji(Nostrum.Struct.Guild.id(), options()) ::
  error() | {:ok, Nostrum.Struct.Emoji.t()}

Creates a new emoji for the given guild.

This endpoint requires the MANAGE_EMOJIS permission. It fires a Nostrum.Consumer.guild_emojis_update/0 event.

If successful, returns {:ok, emoji}. Otherwise, returns Nostrum.Api.error/0.

Options

  • :name (string) - name of the emoji
  • :image (base64 data URI) - the 128x128 emoji image. Maximum size of 256kb
  • :roles (list of Nostrum.Struct.Snowflake.t/0) - roles for which this emoji will be whitelisted (default: [])

:name and :image are always required.

Examples

image = "data:image/png;base64,YXl5IGJieSB1IGx1a2luIDQgc3VtIGZ1az8="

Nostrum.Api.create_guild_emoji(43189401384091, name: "nostrum", image: image, roles: [])
Link to this function

create_guild_emoji!(guild_id, params) View Source

Same as create_guild_emoji/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

create_guild_integrations(guild_id, options) View Source
create_guild_integrations(integer(), %{type: String.t(), id: integer()}) ::
  error() | {:ok}

Creates a new guild integeration.

Guild to create integration with is specified by guild_id.

options is a map with the following requires keys:

  • type - Integration type.
  • id - Integeration id.
Link to this function

create_guild_role(guild_id, options) View Source
create_guild_role(Nostrum.Struct.Guild.id(), options()) ::
  error() | {:ok, Nostrum.Struct.Guild.Role.t()}

Creates a guild role.

This endpoint requires the MANAGE_ROLES permission. It fires a Nostrum.Consumer.guild_role_create/0 event.

If successful, returns {:ok, role}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :name (string) - name of the role (default: "new role")
  • :permissions (integer) - bitwise of the enabled/disabled permissions (default: @everyone perms)
  • :color (integer) - RGB color value (default: 0)
  • :hoist (boolean) - whether the role should be displayed separately in the sidebar (default: false)
  • :mentionable (boolean) - whether the role should be mentionable (default: false)

Examples

Nostrum.Api.create_guild_role(41771983423143937, name: "nostrum-club", hoist: true)
Link to this function

create_guild_role!(guild_id, options) View Source

Same as create_guild_role/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

create_message(channel_id, options) View Source

Posts a message to a guild text or DM channel.

This endpoint requires the VIEW_CHANNEL and SEND_MESSAGES permissions. It may situationally need the SEND_MESSAGES_TTS permission. It fires the Nostrum.Consumer.message_create/0 event.

If options is a string, options will be used as the message's content.

If successful, returns {:ok, message}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :content (string) - the message contents (up to 2000 characters)
  • :nonce (Nostrum.Struct.Snowflake.t/0) - a nonce that can be used for optimistic message sending
  • :tts (boolean) - true if this is a TTS message
  • :file (Path.t/0 | map) - the path of the file being sent, or a map with the following keys if sending a binary from memory

    • :name (string) - the name of the file
    • :body (string) - binary you wish to send
  • :embed (Nostrum.Struct.Embed.t/0) - embedded rich content

    At least one of the following is required: :content, :file, :embed.

Examples

Nostrum.Api.create_message(43189401384091, content: "hello world!")

Nostrum.Api.create_message(43189401384091, "hello world!")

import Nostrum.Struct.Embed
embed =
  %Nostrum.Struct.Embed{}
  |> put_title("embed")
  |> put_description("new desc")
Nostrum.Api.create_message(43189401384091, embed: embed)

Nostrum.Api.create_message(43189401384091, file: "/path/to/file.txt")

Nostrum.Api.create_message(43189401384091, content: "hello world!", embed: embed, file: "/path/to/file.txt")

Same as create_message/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

create_reaction(channel_id, message_id, emoji) View Source
create_reaction(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji()
) :: error() | {:ok}

Creates a reaction for a message.

This endpoint requires the VIEW_CHANNEL and READ_MESSAGE_HISTORY permissions. Additionally, if nobody else has reacted to the message with the emoji, this endpoint requires the ADD_REACTIONS permission. It fires a Nostrum.Consumer.message_reaction_add/0 event.

If successful, returns {:ok}. Otherwise, returns Nostrum.Api.error/0.

Examples

# Using a Nostrum.Struct.Emoji.
emoji = %Nostrum.Struct.Emoji{id: 43819043108, name: "foxbot"}
Nostrum.Api.create_reaction(123123123123, 321321321321, emoji)

# Using a base 16 emoji string.
Nostrum.Api.create_reaction(123123123123, 321321321321, "\xF0\x9F\x98\x81")

For other emoji string examples, see Nostrum.Struct.Emoji.api_name/0.

Link to this function

create_reaction!(channel_id, message_id, emoji) View Source
create_reaction!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji()
) :: no_return() | {:ok}

Same as create_reaction/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

create_webhook(channel_id, args) View Source
create_webhook(Nostrum.Struct.Channel.id(), %{
  name: String.t(),
  avatar: String.t()
}) :: error() | {:ok, Nostrum.Struct.Webhook.t()}

Creates a webhook.

Parameters

  • channel_id - Id of the channel to send the message to.
  • args - Map with the following required keys:

    • name - Name of the webhook.
    • avatar - Base64 128x128 jpeg image for the default avatar.
Link to this function

delete_all_reactions(channel_id, message_id) View Source
delete_all_reactions(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  error() | {:ok}

Deletes all reactions from a message.

This endpoint requires the VIEW_CHANNEL, READ_MESSAGE_HISTORY, and MANAGE_MESSAGES permissions. It fires a Nostrum.Consumer.message_reaction_remove_all/0 event.

If successful, returns {:ok}. Otherwise, return Nostrum.Api.error/0.

Link to this function

delete_all_reactions!(channel_id, message_id) View Source
delete_all_reactions!(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  no_return() | {:ok}

Same as delete_all_reactions/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_channel(channel_id) View Source
delete_channel(Nostrum.Struct.Channel.id()) ::
  error() | {:ok, Nostrum.Struct.Channel.t()}

Deletes a channel.

If deleting a Nostrum.Struct.Channel.guild_channel/0, this endpoint requires the MANAGE_CHANNELS permission. It fires a Nostrum.Consumer.channel_delete/0. If a Nostrum.Struct.Channel.channel_category/0 is deleted, then a Nostrum.Consumer.channel_update/0 event will fire for each channel under the category.

If successful, returns {:ok, channel}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.delete_channel(421533712753360896)
{:ok, %Nostrum.Struct.Channel{id: 421533712753360896}}

Same as delete_channel/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_channel_permissions(channel_id, overwrite_id) View Source
delete_channel_permissions(integer(), integer()) :: error() | {:ok}

Delete a channel permission for a user or role.

Role or user overwrite to delete is specified by channel_id and overwrite_id.

Link to this function

delete_guild(guild_id) View Source
delete_guild(Nostrum.Struct.Guild.id()) :: error() | {:ok}

Deletes a guild.

This endpoint requires that the current user is the owner of the guild. It fires the Nostrum.Consumer.guild_delete/0 event.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.delete_guild(81384788765712384)
{:ok}
Link to this function

delete_guild!(guild_id) View Source
delete_guild!(Nostrum.Struct.Guild.id()) :: no_return() | {:ok}

Same as delete_guild/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_guild_emoji(guild_id, emoji_id) View Source
delete_guild_emoji(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
  error() | {:ok}

Deletes the given emoji.

This endpoint requires the MANAGE_EMOJIS permission. It fires a Nostrum.Consumer.guild_emojis_update/0 event.

If successful, returns {:ok}. Otherwise, returns Nostrum.Api.error/0.

Link to this function

delete_guild_emoji!(guild_id, emoji_id) View Source
delete_guild_emoji!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
  no_return() | {:ok}

Same as delete_guild_emoji/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_guild_integrations(guild_id, integration_id) View Source
delete_guild_integrations(integer(), integer()) :: error() | {:ok}

Deletes a guild integeration.

Integration to delete is specified by guild_id and integeration_id.

Link to this function

delete_guild_role(guild_id, role_id) View Source
delete_guild_role(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id()) ::
  error() | {:ok}

Deletes a role from a guild.

This endpoint requires the MANAGE_ROLES permission. It fires a Nostrum.Consumer.guild_role_delete/0 event.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.delete_guild_role(41771983423143937, 392817238471936)
Link to this function

delete_guild_role!(guild_id, role_id) View Source
delete_guild_role!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id()) ::
  no_return() | {:ok}

Same as delete_guild_role/2, but raises Nostrum.Error.ApiError in case of failure.

Deletes an invite by its invite_code.

This endpoint requires the MANAGE_CHANNELS permission.

If successful, returns {:ok, invite}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.delete_invite("zsjUsC")
{:ok, %Nostrum.Struct.Invite{code: "zsjUsC"}}

Same as delete_invite/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_message(message) View Source
delete_message(Nostrum.Struct.Message.t()) :: error() | {:ok}

Same as delete_message/2, but takes a Nostrum.Struct.Message.

Link to this function

delete_message(channel_id, message_id) View Source
delete_message(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  error() | {:ok}

Deletes a message.

This endpoint requires the 'VIEW_CHANNEL' and 'MANAGE_MESSAGES' permission. It fires the MESSAGE_DELETE event.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.delete_message(43189401384091, 43189401384091)
Link to this function

delete_message!(message) View Source
delete_message!(Nostrum.Struct.Message.t()) :: error() | {:ok}

Same as delete_message/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_message!(channel_id, message_id) View Source

Same as delete_message/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_own_reaction(channel_id, message_id, emoji) View Source
delete_own_reaction(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji()
) :: error() | {:ok}

Deletes a reaction the current user has made for the message.

This endpoint requires the VIEW_CHANNEL and READ_MESSAGE_HISTORY permissions. It fires a Nostrum.Consumer.message_reaction_remove/0 event.

If successful, returns {:ok}. Otherwise, returns Nostrum.Api.error/0.

See create_reaction/3 for similar examples.

Link to this function

delete_own_reaction!(channel_id, message_id, emoji) View Source
delete_own_reaction!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji()
) :: no_return() | {:ok}

Same as delete_own_reaction/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_pinned_channel_message(channel_id, message_id) View Source
delete_pinned_channel_message(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id()
) :: error() | {:ok}

Unpins a message in a channel.

This endpoint requires the 'VIEW_CHANNEL', 'READ_MESSAGE_HISTORY', and 'MANAGE_MESSAGES' permissions. It fires the Nostrum.Consumer.message_update/0 and Nostrum.Consumer.channel_pins_update/0 events.

Returns {:ok} if successful. error otherwise.

Link to this function

delete_pinned_channel_message!(channel_id, message_id) View Source
delete_pinned_channel_message!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id()
) :: no_return() | {:ok}

Same as delete_pinned_channel_message/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_user_reaction(channel_id, message_id, emoji, user_id) View Source

Deletes another user's reaction from a message.

This endpoint requires the VIEW_CHANNEL, READ_MESSAGE_HISTORY, and MANAGE_MESSAGES permissions. It fires a Nostrum.Consumer.message_reaction_remove/0 event.

If successful, returns {:ok}. Otherwise, returns Nostrum.Api.error/0.

See create_reaction/3 for similar examples.

Link to this function

delete_user_reaction!(channel_id, message_id, emoji, user_id) View Source

Same as delete_user_reaction/4, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

delete_webhook(webhook_id) View Source
delete_webhook(Nostrum.Struct.Webhook.id()) :: error() | {:ok}

Deletes a webhook.

Parameters

  • webhook_id - Id of webhook to delete.
  • webhook_token - Token of the webhook to delete.
Link to this function

edit_channel_permissions(channel_id, overwrite_id, permission_info) View Source
edit_channel_permissions(integer(), integer(),
  allow: integer(),
  deny: integer(),
  type: String.t()
) :: error() | {:ok}

Edit the permission overwrites for a user or role.

Role or user to overwrite is specified by channel_id and overwrite_id.

permission_info is a kwl with the following required keys:

  • allow - Bitwise value of allowed permissions.
  • deny - Bitwise value of denied permissions.
  • type - member if editing a user, role if editing a role.
Link to this function

edit_channel_permissions!(channel_id, overwrite_id, permission_info) View Source
edit_channel_permissions!(integer(), integer(),
  allow: integer(),
  deny: integer(),
  type: String.t()
) :: no_return() | {:ok}

Edit the permission overwrites for a user or role.

See edit_channel_permissions/2 for more info.

Raises Nostrum.Error.ApiError if error occurs while making the rest call.

Link to this function

edit_message(message, options) View Source
edit_message(Nostrum.Struct.Message.t(), options()) ::
  error() | {:ok, Nostrum.Struct.Message.t()}

Same as edit_message/3, but takes a Nostrum.Struct.Message instead of a channel_id and message_id.

Link to this function

edit_message(channel_id, message_id, options) View Source

Edits a previously sent message in a channel.

This endpoint requires the VIEW_CHANNEL permission. It fires the Nostrum.Consumer.message_update/0 event.

If options is a string, options will be used as the message's content.

If successful, returns {:ok, message}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :content (string) - the message contents (up to 2000 characters)
  • :embed (Nostrum.Struct.Embed.t/0) - embedded rich content

Examples

Nostrum.Api.edit_message(43189401384091, 1894013840914098, content: "hello world!")

Nostrum.Api.edit_message(43189401384091, 1894013840914098, "hello world!")

import Nostrum.Struct.Embed
embed =
  %Nostrum.Struct.Embed{}
  |> put_title("embed")
  |> put_description("new desc")
Nostrum.Api.edit_message(43189401384091, 1894013840914098, embed: embed)

Nostrum.Api.edit_message(43189401384091, 1894013840914098, content: "hello world!", embed: embed)

Same as edit_message/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

edit_message!(channel_id, message_id, options) View Source

Same as edit_message/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

execute_git_webhook(webhook_id, webhook_token, wait \\ false) View Source
execute_git_webhook(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token(),
  boolean()
) :: error() | {:ok}

Executes a git webhook.

Parameters

  • webhook_id - Id of webhook to delete.
  • webhook_token - Token of the webhook to delete.
Link to this function

execute_slack_webhook(webhook_id, webhook_token, wait \\ false) View Source
execute_slack_webhook(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token(),
  boolean()
) :: error() | {:ok}

Executes a slack webhook.

Parameters

  • webhook_id - Id of webhook to delete.
  • webhook_token - Token of the webhook to delete.
Link to this function

execute_webhook(webhook_id, webhook_token, args, wait \\ false) View Source
execute_webhook(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token(),
  %{
    content: String.t(),
    username: String.t(),
    avatar_url: String.t(),
    tts: boolean(),
    file: String.t(),
    embeds: Nostrum.Struct.Embed.t()
  },
  boolean()
) :: error() | {:ok}

Executes a webhook.

Parameters

  • webhook_id - Id of webhook to delete.
  • webhook_token - Token of the webhook to delete.
  • args - Map with the following required keys:

    • content - Message content.
    • file - File to send.
    • embeds - Embed to send.
    • username - Overrides the default name of the webhook.
    • avatar_url - Overrides the default avatar of the webhook.
    • tts - Whether the message should be read over text to speech.
  • wait - Whether to return an error or not. Defaults to false.

Only one of content, file or embed should be supplied in the args parameter.

Link to this function

get_application_information() View Source

Gets a channel.

If successful, returns {:ok, channel}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_channel(381889573426429952)
{:ok, %Nostrum.Struct.Channel{id: 381889573426429952}}

Same as get_channel/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_channel_invites(channel_id) View Source
get_channel_invites(Nostrum.Struct.Channel.id()) ::
  error() | {:ok, [Nostrum.Struct.Invite.detailed_invite()]}

Gets a list of invites for a channel.

This endpoint requires the 'VIEW_CHANNEL' and 'MANAGE_CHANNELS' permissions.

If successful, returns {:ok, invite}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_channel_invites(43189401384091)
{:ok, [%Nostrum.Struct.Invite{} | _]}

Same as get_channel_invites/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_channel_message(channel_id, message_id) View Source

Retrieves a message from a channel.

This endpoint requires the 'VIEW_CHANNEL' and 'READ_MESSAGE_HISTORY' permissions.

If successful, returns {:ok, message}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_channel_message(43189401384091, 198238475613443)
Link to this function

get_channel_message!(channel_id, message_id) View Source

Same as get_channel_message/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_channel_messages(channel_id, limit, locator \\ {}) View Source
get_channel_messages(Nostrum.Struct.Channel.id(), limit(), locator()) ::
  error() | {:ok, [Nostrum.Struct.Message.t()]}

Retrives a channel's messages around a locator up to a limit.

This endpoint requires the 'VIEW_CHANNEL' permission. If the current user is missing the 'READ_MESSAGE_HISTORY' permission, then this function will return no messages.

If successful, returns {:ok, messages}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_channel_messages(43189401384091, 5, {:before 130230401384})
Link to this function

get_channel_messages!(channel_id, limit, locator \\ {}) View Source
get_channel_messages!(Nostrum.Struct.Channel.id(), limit(), locator()) ::
  no_return() | [Nostrum.Struct.Message.t()]

Same as get_channel_messages/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_channel_webhooks(channel_id) View Source
get_channel_webhooks(Nostrum.Struct.Channel.id()) ::
  error() | {:ok, [Nostrum.Struct.Webhook.t()]}

Gets a list of webook for a channel.

Parameters

  • channel_id - Channel to get webhooks for.
Link to this function

get_current_user() View Source
get_current_user() :: error() | {:ok, Nostrum.Struct.User.t()}

Gets info on the current user.

If nostrum's caching is enabled, it is recommended to use Nostrum.Cache.Me.get/0 instead of this function. This is because sending out an API request is much slower than pulling from our cache.

If the request is successful, this function returns {:ok, user}, where user is nostrum's Nostrum.Struct.User. Otherwise, returns {:error, reason}.

Link to this function

get_current_user!() View Source
get_current_user!() :: no_return() | Nostrum.Struct.User.t()

Same as get_current_user/0, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_current_user_guilds(options \\ []) View Source
get_current_user_guilds(options()) ::
  error() | {:ok, [Nostrum.Struct.Guild.user_guild()]}

Gets a list of guilds the user is currently in.

This endpoint requires the guilds OAuth2 scope.

If successful, returns {:ok, guilds}. Otherwise, returns a Nostrum.Api.error/0.

Options

Examples

iex> Nostrum.Api.get_current_user_guilds(limit: 1)
{:ok, [%Nostrum.Struct.Guild{}]}
Link to this function

get_current_user_guilds!(options \\ []) View Source
get_current_user_guilds!(options()) ::
  no_return() | [Nostrum.Struct.Guild.user_guild()]

Same as get_current_user_guilds/1, but raises Nostrum.Error.ApiError in case of failure.

Gets a guild.

If successful, returns {:ok, guild}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_guild(81384788765712384)
{:ok, %Nostrum.Struct.Guild{id: 81384788765712384}}

Same as get_guild/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_guild_bans(guild_id) View Source
get_guild_bans(integer()) :: error() | {:ok, [Nostrum.Struct.User.t()]}

Gets a list of users banend from a guild.

Guild to get bans for is specified by guild_id.

Link to this function

get_guild_channels(guild_id) View Source
get_guild_channels(Nostrum.Struct.Guild.id()) ::
  error() | {:ok, [Nostrum.Struct.Channel.guild_channel()]}

Gets a list of guild channels.

If successful, returns {:ok, channels}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_guild_channels(81384788765712384)
{:ok, [%Nostrum.Struct.Channel{guild_id: 81384788765712384} | _]}

Same as get_guild_channels/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_guild_embed(guild_id) View Source
get_guild_embed(integer()) :: error() | {:ok, map()}

Gets a guild embed.

Link to this function

get_guild_emoji(guild_id, emoji_id) View Source

Gets an emoji for the given guild and emoji ids.

This endpoint requires the MANAGE_EMOJIS permission.

If successful, returns {:ok, emoji}. Otherwise, returns Nostrum.Api.error/0.

Same as get_guild_emoji/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_guild_integrations(guild_id) View Source
get_guild_integrations(integer()) ::
  error() | {:ok, [Nostrum.Struct.Guild.Integration.t()]}

Gets a list of guild integerations.

Guild to get integrations for is specified by guild_id.

Link to this function

get_guild_invites(guild_id) View Source

Gets a list of invites for a guild.

This endpoint requires the MANAGE_GUILD permission.

If successful, returns {:ok, invites}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_guild_invites(81384788765712384)
{:ok, [%Nostrum.Struct.Invite{} | _]}

Same as get_guild_invites/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_guild_member(guild_id, user_id) View Source

Gets a guild member.

If successful, returns {:ok, member}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_guild_member(4019283754613, 184937267485)

Same as get_guild_member/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_guild_prune_count(guild_id, days) View Source
get_guild_prune_count(Nostrum.Struct.Guild.id(), 1..30) ::
  error() | {:ok, %{pruned: integer()}}

Gets the number of members that would be removed in a prune given days.

This endpoint requires the KICK_MEMBERS permission.

If successful, returns {:ok, %{pruned: pruned}}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_guild_prune_count(81384788765712384, 1)
{:ok, %{pruned: 0}}
Link to this function

get_guild_prune_count!(guild_id, days) View Source
get_guild_prune_count!(Nostrum.Struct.Guild.id(), 1..30) ::
  no_return() | %{pruned: integer()}

Same as get_guild_prune_count/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_guild_roles(guild_id) View Source
get_guild_roles(Nostrum.Struct.Guild.id()) ::
  error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}

Gets a guild's roles.

If successful, returns {:ok, roles}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_guild_roles(147362948571673)

Same as get_guild_roles/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_guild_webhooks(guild_id) View Source
get_guild_webhooks(Nostrum.Struct.Guild.id()) ::
  error() | {:ok, [Nostrum.Struct.Webhook.t()]}

Gets a list of webooks for a guild.

Parameters

  • guild_id - Guild to get webhooks for.

Gets an invite by its invite_code.

If successful, returns {:ok, invite}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_invite("zsjUsC")
{:ok, %Nostrum.Struct.Invite{code: "zsjUsC"}}

Same as get_invite/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_pinned_messages(channel_id) View Source
get_pinned_messages(Nostrum.Struct.Channel.id()) ::
  error() | {:ok, [Nostrum.Struct.Message.t()]}

Retrieves all pinned messages from a channel.

This endpoint requires the 'VIEW_CHANNEL' and 'READ_MESSAGE_HISTORY' permissions.

If successful, returns {:ok, messages}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_pinned_messages(43189401384091)
Link to this function

get_pinned_messages!(channel_id) View Source
get_pinned_messages!(Nostrum.Struct.Channel.id()) ::
  no_return() | [Nostrum.Struct.Message.t()]

Same as get_pinned_messages/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_reactions(channel_id, message_id, emoji) View Source

Gets all users who reacted with an emoji.

This endpoint requires the VIEW_CHANNEL and READ_MESSAGE_HISTORY permissions.

If successful, returns {:ok, users}. Otherwise, returns Nostrum.Api.error/0.

See create_reaction/3 for similar examples.

Link to this function

get_reactions!(channel_id, message_id, emoji) View Source

Same as get_reactions/3, but raises Nostrum.Error.ApiError in case of failure.

Returns the token of the bot.

Gets a user by its Nostrum.Struct.User.id/0.

If the request is successful, this function returns {:ok, user}, where user is a Nostrum.Struct.User. Otherwise, returns {:error, reason}.

Same as get_user/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_user_connections() View Source
get_user_connections() :: error() | {:ok, Nostrum.Struct.User.Connection.t()}

Gets a list of user connections.

Gets a list of our user's DM channels.

If successful, returns {:ok, dm_channels}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.get_user_dms()
{:ok, [%Nostrum.Struct.Channel{type: 1} | _]}

Same as get_user_dms/0, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

get_voice_region(guild_id) View Source
get_voice_region(integer()) :: error() | {:ok, [Nostrum.Struct.VoiceRegion.t()]}

Gets a list of voice regions for the guild.

Guild to get voice regions for is specified by guild_id.

Gets a webhook by id.

Parameters

  • webhook_id - Id of webhook to get.
Link to this function

get_webhook_with_token(webhook_id, webhook_token) View Source

Gets a webhook by id and token.

This method is exactly like get_webhook/1 but does not require authentication.

Parameters

  • webhook_id - Id of webhook to get.
  • webhook_token - Token of the webhook to get.
Link to this function

leave_guild(guild_id) View Source
leave_guild(integer()) :: error() | {:ok}

Leaves a guild.

Guild to leave is specified by guild_id.

Link to this function

list_guild_emojis(guild_id) View Source
list_guild_emojis(Nostrum.Struct.Guild.id()) ::
  error() | {:ok, [Nostrum.Struct.Emoji.t()]}

Gets a list of emojis for a given guild.

This endpoint requires the MANAGE_EMOJIS permission.

If successful, returns {:ok, emojis}. Otherwise, returns Nostrum.Api.error/0.

Link to this function

list_guild_emojis!(guild_id) View Source
list_guild_emojis!(Nostrum.Struct.Guild.id()) ::
  no_return() | [Nostrum.Struct.Emoji.t()]

Same as list_guild_emojis/1, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

list_guild_members(guild_id, options \\ %{}) View Source
list_guild_members(Nostrum.Struct.Guild.id(), options()) ::
  error() | {:ok, [Nostrum.Struct.Guild.Member.t()]}

Gets a list of a guild's members.

If successful, returns {:ok, members}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :limit (integer) - max number of members to return (1-1000) (default: 1)
  • :after (Nostrum.Struct.User.id/0) - the highest user id in the previous page (default: 0)

Examples

Nostrum.Api.list_guild_members(41771983423143937, limit: 1)
Link to this function

list_guild_members!(guild_id, options \\ %{}) View Source

Same as list_guild_members/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

list_voice_regions() View Source
list_voice_regions() :: error() | {:ok, [Nostrum.Struct.VoiceRegion.t()]}

Gets a list of voice regions.

Link to this function

modify_channel(channel_id, options) View Source
modify_channel(Nostrum.Struct.Channel.id(), options()) ::
  error() | {:ok, Nostrum.Struct.Channel.t()}

Modifies a channel's settings.

If a Nostrum.Struct.Channel.guild_channel/0 is being modified, this endpoint requires the MANAGE_CHANNEL permission. It fires a Nostrum.Consumer.channel_update/0 event. If a Nostrum.Struct.Channel.channel_category/0 is being modified, then this endpoint fires multiple Nostrum.Consumer.channel_update/0 events.

If successful, returns {:ok, channel}. Otherwise, returns a Nostrum.Api.error/0.

Options

Examples

Nostrum.Api.modify_channel(41771983423143933, name: "elixir-nostrum", topic: "nostrum discussion")
{:ok, %Nostrum.Struct.Channel{id: 41771983423143933, name: "elixir-nostrum", topic: "nostrum discussion"}}

Nostrum.Api.modify_channel(41771983423143933)
{:ok, %Nostrum.Struct.Channel{id: 41771983423143933}}
Link to this function

modify_channel!(channel_id, options) View Source

Same as modify_channel/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

modify_current_user(options) View Source
modify_current_user(keyword() | map()) ::
  error() | {:ok, Nostrum.Struct.User.t()}

Changes the username or avatar of the current user.

Options

  • :username (string) - new username
  • :avatar (string) - the user's avatar as avatar data

Examples

Nostrum.Api.modify_current_user(avatar: "data:image/jpeg;base64,YXl5IGJieSB1IGx1a2luIDQgc3VtIGZ1az8=")
Link to this function

modify_current_user!(options) View Source
modify_current_user!(keyword() | map()) ::
  no_return() | Nostrum.Struct.User.t()

Same as modify_current_user/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

modify_guild(guild_id, options \\ []) View Source

Modifies a guild's settings.

This endpoint requires the MANAGE_GUILD permission. It fires the Nostrum.Consumer.guild_update/0 event.

If successful, returns {:ok, guild}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :name (string) - guild name
  • :region (string) - guild voice region id
  • :verification_level (integer) - verification level
  • :default_message_notifications (integer) - default message notification level
  • :explicit_content_filter (integer) - explicit content filter level
  • :afk_channel_id (Nostrum.Struct.Snowflake.t/0) - id for afk channel
  • :afk_timeout (integer) - afk timeout in seconds
  • :icon (base64 data URI) - 128x128 jpeg image for the guild icon
  • :owner_id (Nostrum.Struct.Snowflake.t/0) - user id to transfer guild ownership to (must be owner)
  • :splash (base64 data URI) - 128x128 jpeg image for the guild splash (VIP only)
  • :system_channel_id (Nostrum.Struct.Snowflake.t/0) - the id of the channel to which system messages are sent

Examples

Nostrum.Api.modify_guild(81384788765712384, name: "Elixir Guild")
{:ok, %Nostrum.Struct.Channel{id: 81384788765712384, name: "Elixir Guild"}}

Nostrum.Api.modify_channel(81384788765712384)
{:ok, %Nostrum.Struct.Channel{id: 81384788765712384}}
Link to this function

modify_guild!(guild_id, options \\ []) View Source

Same as modify_guild/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

modify_guild_channel_positions(guild_id, positions) View Source
modify_guild_channel_positions(Nostrum.Struct.Guild.id(), [
  %{id: integer(), position: integer()}
]) :: error() | {:ok}

Reorders a guild's channels.

This endpoint requires the MANAGE_CHANNELS permission. It fires multiple Nostrum.Consumer.channel_update/0 events.

If successful, returns {:ok, channels}. Otherwise, returns a Nostrum.Api.error/0.

positions is a list of maps that each map a channel id with a position.

Examples

Nostrum.Api.modify_guild_channel_positions(279093381723062272, [%{id: 351500354581692420, position: 2}])
{:ok}
Link to this function

modify_guild_channel_positions!(guild_id, positions) View Source
modify_guild_channel_positions!(Nostrum.Struct.Guild.id(), [
  %{id: integer(), position: integer()}
]) :: no_return() | {:ok}

Same as modify_guild_channel_positions/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

modify_guild_embed(guild_id, options) View Source
modify_guild_embed(integer(), map()) :: error() | {:ok, map()}

Modifies a guild imbed.

Link to this function

modify_guild_emoji(guild_id, emoji_id, options \\ %{}) View Source

Modify the given emoji.

This endpoint requires the MANAGE_EMOJIS permission. It fires a Nostrum.Consumer.guild_emojis_update/0 event.

If successful, returns {:ok, emoji}. Otherwise, returns Nostrum.Api.error/0.

Options

Examples

Nostrum.Api.modify_guild_emoji(43189401384091, 4314301984301, name: "elixir", roles: [])
Link to this function

modify_guild_emoji!(guild_id, emoji_id, options) View Source

Same as modify_guild_emoji/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

modify_guild_integrations(guild_id, integration_id, options) View Source
modify_guild_integrations(integer(), integer(), %{
  expire_behaviour: integer(),
  expire_grace_period: integer(),
  enable_emoticons: boolean()
}) :: error() | {:ok}

Changes the settings and behaviours for a guild integeration.

Integration to modify is specified by guild_id and integeration_id.

options is a map with the following keys:

  • expire_behavior - Expiry behavior.
  • expire_grace_period - Period where the integration will ignore elapsed subs.
  • enable_emoticons - Whether emoticons should be synced.
Link to this function

modify_guild_member(guild_id, user_id, options \\ %{}) View Source
modify_guild_member(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  options()
) :: error() | {:ok}

Modifies a guild member's attributes.

This endpoint fires the Nostrum.Consumer.guild_member_update/0 event. It situationally requires the MANAGE_NICKNAMES, MANAGE_ROLES, MUTE_MEMBERS, DEAFEN_MEMBERS, and MOVE_MEMBERS permissions.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :nick (string) - value to set users nickname to
  • :roles (list of Nostrum.Struct.Snowflake.t/0) - array of role ids the member is assigned
  • :mute (boolean) - if the user is muted
  • :deaf (boolean) - if the user is deafened
  • :channel_id (Nostrum.Struct.Snowflake.t/0) - id of channel to move user to (if they are connected to voice)

Examples

Nostrum.Api.modify_guild_member(41771983423143937, 637162356451, nick: "Nostrum")
{:ok}
Link to this function

modify_guild_member!(guild_id, user_id, options \\ %{}) View Source
modify_guild_member!(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  options()
) :: error() | {:ok}

Same as modify_guild_member/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

modify_guild_role(guild_id, role_id, options) View Source

Modifies a guild role.

This endpoint requires the MANAGE_ROLES permission. It fires a Nostrum.Consumer.guild_role_update/0 event.

If successful, returns {:ok, role}. Otherwise, returns a Nostrum.Api.error/0.

Options

  • :name (string) - name of the role
  • :permissions (integer) - bitwise of the enabled/disabled permissions
  • :color (integer) - RGB color value (default: 0)
  • :hoist (boolean) - whether the role should be displayed separately in the sidebar
  • :mentionable (boolean) - whether the role should be mentionable

Examples

Nostrum.Api.modify_guild_role(41771983423143937, 392817238471936, hoist: false, name: "foo-bar")
Link to this function

modify_guild_role!(guild_id, role_id, options) View Source

Same as modify_guild_role/3, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

modify_guild_role_positions(guild_id, positions) View Source
modify_guild_role_positions(Nostrum.Struct.Guild.id(), [
  %{id: Nostrum.Struct.Guild.Role.id(), position: integer()}
]) :: error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}

Reorders a guild's roles.

This endpoint requires the MANAGE_ROLES permission. It fires multiple Nostrum.Consumer.guild_role_update/0 events.

If successful, returns {:ok, roles}. Otherwise, returns a Nostrum.Api.error/0.

positions is a list of maps that each map a role id with a position.

Examples

Nostrum.Api.modify_guild_role_positions(41771983423143937, [%{id: 41771983423143936, position: 2}])
Link to this function

modify_guild_role_positions!(guild_id, positions) View Source
modify_guild_role_positions!(Nostrum.Struct.Guild.id(), [
  %{id: Nostrum.Struct.Guild.Role.id(), position: integer()}
]) :: no_return() | [Nostrum.Struct.Guild.Role.t()]

Same as modify_guild_role_positions/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

modify_webhook(webhook_id, args) View Source
modify_webhook(Nostrum.Struct.Webhook.id(), %{
  name: String.t(),
  avatar: String.t()
}) :: error() | {:ok, Nostrum.Struct.Webhook.t()}

Modifies a webhook.

Parameters

  • webhook_id - Id of the webhook to modify.
  • args - Map with the following optional keys:

    • name - Name of the webhook.
    • avatar - Base64 128x128 jpeg image for the default avatar.
Link to this function

modify_webhook_with_token(webhook_id, webhook_token, args) View Source
modify_webhook_with_token(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token(),
  %{name: String.t(), avatar: String.t()}
) :: error() | {:ok, Nostrum.Struct.Webhook.t()}

Modifies a webhook with a token.

This method is exactly like modify_webhook/1 but does not require authentication.

Parameters

  • webhook_id - Id of the webhook to modify.
  • webhook_token - Token of the webhook to get.
  • args - Map with the following optional keys:

    • name - Name of the webhook.
    • avatar - Base64 128x128 jpeg image for the default avatar.
Link to this function

remove_guild_ban(guild_id, user_id) View Source
remove_guild_ban(integer(), integer()) :: error() | {:ok}

Removes a ban for a user.

User to unban is specified by guild_id and user_id.

Link to this function

remove_guild_member(guild_id, user_id) View Source
remove_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
  error() | {:ok}

Removes a member from a guild.

This event requires the KICK_MEMBERS permission. It fires a Nostrum.Consumer.guild_member_remove/0 event.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.remove_guild_member(1453827904102291, 18739485766253)
{:ok}
Link to this function

remove_guild_member!(guild_id, user_id) View Source
remove_guild_member!(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
  no_return() | {:ok}

Same as remove_guild_member/2, but raises Nostrum.Error.ApiError in case of failure.

Link to this function

remove_guild_member_role(guild_id, user_id, role_id) View Source
remove_guild_member_role(integer(), integer(), integer()) :: error() | {:ok}

Removes a role from a member.

Role to remove is specified by role_id. User to remove role from is specified by guild_id and user_id.

Link to this function

request(method, route, body \\ "", options \\ []) View Source

Link to this function

request_multipart(method, route, body \\ "", options \\ []) View Source

Link to this function

start_typing(channel_id) View Source
start_typing(integer()) :: error() | {:ok}

Triggers the typing indicator.

Triggers the typing indicator in the channel specified by channel_id. The typing indicator lasts for about 8 seconds and then automatically stops.

Returns {:ok} if successful. error otherwise.

Link to this function

start_typing!(channel_id) View Source
start_typing!(integer()) :: no_return() | {:ok}

Triggers the typing indicator.

Triggers the typing indicator in the channel specified by channel_id. The typing indicator lasts for about 8 seconds and then automatically stops.

Raises Nostrum.Error.ApiError if error occurs while making the rest call. Returns {:ok} if successful.

Link to this function

sync_guild_integrations(guild_id, integration_id) View Source
sync_guild_integrations(integer(), integer()) :: error() | {:ok}

Syncs a guild integration.

Integration to sync is specified by guild_id and integeration_id.

Link to this function

update_shard_status(pid, status, game, type \\ 0, stream \\ nil) View Source
update_shard_status(pid(), status(), String.t(), integer(), String.t()) :: :ok

Updates the status of the bot for a certain shard.

Parameters

  • pid - Pid of the shard.
  • status - Status of the bot.
  • game - The 'playing' text of the bot. Empty will clear.
  • type - The type of status to show. 0 (Playing) | 1 (Streaming) | 2 (Listening) | 3 (Watching)
  • stream - URL of twitch.tv stream
Link to this function

update_status(status, game, type \\ 0, stream \\ nil) View Source
update_status(status(), String.t(), integer(), String.t()) :: :ok

Updates the status of the bot for all shards.

See update_shard_status/4 for usage.