Specs

add_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), options()) ::
  error() | {:ok, Nostrum.Struct.Guild.Member.t()} | {:ok}

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} or {:ok} if the user was already a member of the guild. 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]
)

Specs

add_guild_member!(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  options()
) ::
  no_return() | Nostrum.Struct.Guild.Member.t() | {:ok}

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

Specs

add_guild_member_role(
  integer(),
  integer(),
  integer(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: 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. An optional reason can be given for the audit log.

Specs

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)

Specs

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.

Add a user to a thread, requires the ability to send messages in the thread.

Specs

batch_edit_application_command_permissions(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id(),
  [
    %{
      id: Nostrum.Snowflake.t(),
      permissions: [
        Nostrum.Struct.ApplicationCommand.application_command_permissions()
      ]
    }
  ]
) :: {:ok, map()} | error()

Edits command permissions for a specific command for your application in a guild. You can only add up to 10 permission overwrites for a command.

Parameters

• application_id: Application ID commands are registered under. If not given, this will be fetched from Me.
• guild_id: Guild ID to fetch command permissions from.
• command_id: Command ID to fetch permissions for.
• permissions: List of partial guild application command permissions with id and permissions. You can add up to 10 overwrites per command.

Return value

This method returns a guild application command permission object, see all available values on the Discord API docs.

Specs

begin_guild_prune(
  Nostrum.Struct.Guild.id(),
  1..30,
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  error() | {:ok, %{pruned: integer()}}

Begins a guild prune to prune members within days.

An optional reason can be provided for the guild audit log.

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}}

Specs

begin_guild_prune!(
  Nostrum.Struct.Guild.id(),
  1..30,
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  no_return() | %{pruned: integer()}

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

Specs

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.

Specs

bulk_delete_messages!(integer(), [Nostrum.Struct.Message.id()], boolean()) ::
  no_return() | {:ok}

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

Specs

bulk_overwrite_global_application_commands(Nostrum.Struct.User.id(), [
  Nostrum.Struct.ApplicationCommand.application_command_map()
]) :: {:ok, [map()]} | error()

Overwrite the existing global application commands.

This action will:

• Create any command that was provided and did not already exist
• Update any command that was provided and already existed if its configuration changed
• Delete any command that was not provided but existed on Discord's end

Updates will be available in all guilds after 1 hour. Commands that do not already exist will count toward daily application command create limits.

Parameters

• application_id: Application ID for which to overwrite the commands. If not given, this will be fetched from Me.
• commands: List of command configurations, see the linked API documentation for reference.

Return value

Updated list of global application commands. See the official reference: https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-global-application-commands

Specs

bulk_overwrite_guild_application_commands(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id(),
  [
    Nostrum.Struct.ApplicationCommand.application_command_map()
  ]
) :: {:ok, [map()]} | error()

Overwrite the existing guild application commands on the specified guild.

This action will:

• Create any command that was provided and did not already exist
• Update any command that was provided and already existed if its configuration changed
• Delete any command that was not provided but existed on Discord's end

Parameters

• application_id: Application ID for which to overwrite the commands. If not given, this will be fetched from Me.
• guild_id: Guild on which to overwrite the commands.
• commands: List of command configurations, see the linked API documentation for reference.

Return value

Updated list of guild application commands. See the official reference: https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-guild-application-commands

Specs

create_channel_invite(
  Nostrum.Struct.Channel.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Invite.detailed_invite()}

Creates an invite for a guild channel.

An optional reason can be provided for the audit log.

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{}}

Specs

create_channel_invite!(
  Nostrum.Struct.Channel.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Invite.detailed_invite()

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

Specs

create_dm(Nostrum.Struct.User.id()) ::
  error() | {:ok, Nostrum.Struct.Channel.dm_channel()}

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}}

Specs

create_dm!(Nostrum.Struct.User.id()) ::
  no_return() | Nostrum.Struct.Channel.dm_channel()

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

Specs

create_followup_message(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Interaction.token(),
  map()
) ::
  {:ok, Nostrum.Struct.Message.t()} | error()

Create a followup message for an interaction.

Delegates to execute_webhook/3, see the function for more details.

Specs

create_followup_message!(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Interaction.token(),
  map()
) ::
  no_return() | Nostrum.Struct.Message.t()

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

Specs

create_global_application_command(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.ApplicationCommand.application_command_map()
) :: {:ok, map()} | error()

Create a new global application command.

The new command will be available on all guilds in around an hour. If you want to test commands, use create_guild_application_command/2 instead, as commands will become available instantly there. If an existing command with the same name exists, it will be overwritten.

Parameters

• application_id: Application ID for which to create the command. If not given, this will be fetched from Me.
• command: Command configuration, see the linked API documentation for reference.

Return value

The created command. See the official reference: https://discord.com/developers/docs/interactions/application-commands#create-global-application-command

Example

Nostrum.Api.create_application_command(
  %{name: "edit", description: "ed, man! man, ed", options: []}
)

Specs

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}}

Specs

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.

Specs

create_guild_application_command(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.ApplicationCommand.application_command_map()
) :: {:ok, map()} | error()

Create a guild application command on the specified guild.

The new command will be available immediately.

Parameters

• application_id: Application ID for which to create the command. If not given, this will be fetched from Me.
• guild_id: Guild on which to create the command.
• command: Command configuration, see the linked API documentation for reference.

Return value

The created command. See the official reference: https://discord.com/developers/docs/interactions/application-commands#create-guild-application-command

Specs

create_guild_ban(
  integer(),
  integer(),
  integer(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  error() | {:ok}

Bans a user from a guild.

User to delete is specified by guild_id and user_id. An optional reason can be specified for the audit log.

Specs

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}}

Specs

create_guild_channel!(Nostrum.Struct.Guild.id(), options()) ::
  no_return() | Nostrum.Struct.Channel.guild_channel()

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

Specs

create_guild_emoji(
  Nostrum.Struct.Guild.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: 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.

An optional reason can be provided for the audit log.

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.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: [])

Specs

create_guild_emoji!(
  Nostrum.Struct.Guild.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Emoji.t()

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

Specs

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.

Specs

create_guild_role(
  Nostrum.Struct.Guild.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Guild.Role.t()}

Creates a guild role.

An optional reason for the audit log can be provided via reason.

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)

Specs

create_guild_role!(
  Nostrum.Struct.Guild.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Guild.Role.t()

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

Specs

create_guild_scheduled_event(
  Nostrum.Struct.Guild.id(),
  reason :: Nostrum.Struct.Guild.AuditLogEntry.reason(),
  options()
) :: {:ok, Nostrum.Struct.Guild.ScheduledEvent.t()} | error()

Creates a new scheduled event for the guild.

Options

• :channel_id - (Nostrum.Snowflake.t/0) optional channel id for the event
• :entity_metadata - (Nostrum.Struct.Guild.ScheduledEvent.EntityMetadata.t/0) metadata for the event
• :name - (string) required name for the event
• :privacy_level - (integer) at the time of writing, this must always be 2 for GUILD_ONLY
• :scheduled_start_time - required time for the event to start as a DateTime or (ISO8601 timestamp)[DateTime.to_iso8601/3]
• :scheduled_end_time - optional time for the event to end as a DateTime or (ISO8601 timestamp)[DateTime.to_iso8601/3]
• :description - (string) optional description for the event
• :entity_type - (integer) an integer representing the type of entity the event is for
  • 1 - STAGE_INSTANCE
  • 2 - VOICE
  • 3 - EXTERNAL

See the (official documentation)[https://discord.com/developers/docs/resources/guild-scheduled-event] for more information.

An optional reason can be specified for the audit log.

Specs

create_interaction_response(Nostrum.Struct.Interaction.t(), map()) ::
  {:ok} | error()

Same as create_interaction_response/3, but directly takes the Nostrum.Struct.Interaction.t/0 received from the gateway.

Specs

create_interaction_response(
  Nostrum.Struct.Interaction.id(),
  Nostrum.Struct.Interaction.token(),
  map()
) :: {:ok} | error()

Create a response to an interaction received from the gateway.

Parameters

• id: The interaction ID to which the response should be created.
• token: The interaction token.
• response: An InteractionResponse object. See the linked documentation.

Attachments

To include attachments in the response, you can include a :files field in the response. This field expects a list of attachments which can be in either of the following formats:

• A path to the file to upload.
• A map with the following fields:
  • :body The file contents.
  • :name The filename of the file.

Example

response = %{
  type: 4,
  data: %{
    content: "I copy and pasted this code."
  }
}
Nostrum.Api.create_interaction_response(interaction, response)

As an alternative to passing the interaction ID and token, the original Nostrum.Struct.Interaction.t/0 can also be passed directly. See create_interaction_response/2.

Specs

create_interaction_response!(Nostrum.Struct.Interaction.t(), map()) ::
  no_return() | {:ok}

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

Specs

create_message(
  Nostrum.Struct.Channel.id() | Nostrum.Struct.Message.t(),
  options() | String.t()
) ::
  error() | {:ok, Nostrum.Struct.Message.t()}

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.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
• :files - a list of files where each element is the same format as the :file option. If both :file and :files are specified, :file will be prepended to the :files list.
• :embeds (Nostrum.Struct.Embed.t/0) - a list of embedded rich content
• :allowed_mentions - See "Allowed mentions" below
• :message_reference (map) - See "Message references" below

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

Allowed mentions

With this option you can control when content from a message should trigger a ping. Consider using this option when you are going to display user_generated content.

Allowed values

• :all (default) - Ping everything as usual
• :none - Nobody will be pinged
• :everyone - Allows to ping @here and @everyone
• :users - Allows to ping users
• :roles - Allows to ping roles
• {:users, list} - Allows to ping list of users. Can contain up to 100 ids of users.
• {:roles, list} - Allows to ping list of roles. Can contain up to 100 ids of roles.
• list - a list containing the values above.

Message reference

You can create a reply to another message on guilds using this option, given that you have the VIEW_MESSAGE_HISTORY permission. To do so, include the message_reference field in your call. The complete structure documentation can be found on the Discord Developer Portal, but simply passing message_id will suffice:

def my_command(msg) do
  # Reply to the author - ``msg`` is a ``Nostrum.Struct.Message``
  Nostrum.Api.create_message(
    msg.channel_id,
    content: "Hello",
    message_reference: %{message_id: msg.id}
  )
end

Passing a list will merge the settings provided

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, embeds: [embed])

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

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

Nostrum.Api.create_message(43189401384091, content: "Hello @everyone", allowed_mentions: :none)

Specs

create_message!(
  Nostrum.Struct.Channel.id() | Nostrum.Struct.Message.t(),
  options() | String.t()
) ::
  no_return() | Nostrum.Struct.Message.t()

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

Specs

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.

Specs

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.

Specs

create_webhook(
  Nostrum.Struct.Channel.id(),
  %{name: String.t(), avatar: String.t()},
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: 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.
• reason - An optional reason for the guild audit log.

Specs

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.

Specs

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.

Specs

delete_channel(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  error() | {:ok, Nostrum.Struct.Channel.t()}

Deletes a channel.

An optional reason can be provided for the guild audit log.

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.guild_category_channel/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}}

Specs

delete_channel!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  no_return() | Nostrum.Struct.Channel.t()

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

Specs

delete_channel_permissions(
  integer(),
  integer(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  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. An optional reason can be given for the audit log.

Specs

delete_global_application_command(
  Nostrum.Struct.User.id(),
  Nostrum.Snowflake.t()
) ::
  {:ok} | error()

Delete an existing global application command.

Parameters

• application_id: Application ID for which to create the command. If not given, this will be fetched from Me.
• command_id: The current snowflake of the command.

Specs

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}

Specs

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

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

Specs

delete_guild_application_command(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id(),
  Nostrum.Snowflake.t()
) :: {:ok} | error()

Delete an existing guild application command.

Parameters

• application_id: Application ID for which to create the command. If not given, this will be fetched from Me.
• guild_id: The guild on which the command exists.
• command_id: The current snowflake of the command.

Specs

delete_guild_emoji(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Emoji.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}

Deletes the given emoji.

An optional reason can be provided for the audit log.

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.

Specs

delete_guild_emoji!(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Emoji.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | {:ok}

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

Specs

delete_guild_integrations(integer(), integer()) :: error() | {:ok}

Deletes a guild integeration.

Integration to delete is specified by guild_id and integeration_id.

Specs

delete_guild_role(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Role.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}

Deletes a role from a guild.

An optional reason can be specified for the audit log.

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)

Specs

delete_guild_role!(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Role.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | {:ok}

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

Specs

delete_guild_scheduled_event(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.ScheduledEvent.id()
) ::
  error() | {:ok}

Delete a scheduled event for a guild.

Specs

delete_interaction_followup_message(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Interaction.token(),
  Nostrum.Struct.Message.id()
) :: {:ok} | error()

Delete a followup message for an interaction.

Parameters

• application_id: Application ID for which to create the command. If not given, this will be fetched from Me.
• token: Interaction token.
• message_id: Followup message ID.

Specs

delete_interaction_followup_message!(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Interaction.token(),
  Nostrum.Struct.Message.id()
) :: no_return() | {:ok}

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

Specs

delete_interaction_response(Nostrum.Struct.Interaction.t()) :: {:ok} | error()

Same as delete_interaction_response/3, but directly takes the Nostrum.Struct.Interaction.t/0 received from the gateway.

Specs

delete_interaction_response(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Interaction.token()
) ::
  {:ok} | error()

Deletes the original interaction response.

Specs

delete_interaction_response!(Nostrum.Struct.Interaction.t()) ::
  no_return() | {:ok}

Specs

delete_interaction_response!(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Interaction.token()
) ::
  no_return() | {:ok}

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

Specs

delete_invite(Nostrum.Struct.Invite.code()) ::
  error() | {:ok, Nostrum.Struct.Invite.simple_invite()}

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

Specs

delete_invite!(Nostrum.Struct.Invite.code()) ::
  no_return() | Nostrum.Struct.Invite.simple_invite()

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

Specs

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

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

Specs

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)

Specs

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

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

Specs

delete_message!(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  no_return() | {:ok}

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

Specs

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.

Specs

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.

Specs

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.

Specs

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.

Specs

delete_reaction(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji()
) ::
  error() | {:ok}

Deletes all reactions of a given emoji from a message.

This endpoint requires the MANAGE_MESSAGES permissions. It fires a Nostrum.Consumer.message_reaction_remove_emoji/0 event.

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

See create_reaction/3 for similar examples.

Specs

delete_reaction!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji()
) ::
  no_return() | {:ok}

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

Specs

delete_user_reaction(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji(),
  Nostrum.Struct.User.id()
) :: error() | {:ok}

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.

Specs

delete_user_reaction!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji(),
  Nostrum.Struct.User.id()
) :: no_return() | {:ok}

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

Specs

delete_webhook(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  error() | {:ok}

Deletes a webhook.

Parameters

• webhook_id - Id of webhook to delete.
• reason - An optional reason for the guild audit log.

Specs

edit_application_command_permissions(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id(),
  Nostrum.Snowflake.t(),
  [Nostrum.Struct.ApplicationCommand.application_command_permissions()]
) :: {:ok, map()} | error()

Edits command permissions for a specific command for your application in a guild. You can only add up to 10 permission overwrites for a command.

Parameters

• application_id: Application ID commands are registered under. If not given, this will be fetched from Me.
• guild_id: Guild ID to fetch command permissions from.
• command_id: Command ID to fetch permissions for.
• permissions: List of application command permissions

Return value

This method returns a guild application command permission object, see all available values on the Discord API docs.

Specs

edit_channel_permissions(
  integer(),
  integer(),
  %{
    :type => String.t(),
    optional(:allow) => integer(),
    optional(:deny) => integer()
  },
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}

Edit the permission overwrites for a user or role.

Role or user to overwrite is specified by overwrite_id.

permission_info is a map with the following keys:

• type - Required; member if editing a user, role if editing a role.
• allow - Bitwise value of allowed permissions.
• deny - Bitwise value of denied permissions.
• type - member if editing a user, role if editing a role.

An optional reason can be provided for the audit log.

allow and deny are defaulted to 0, meaning that even if you don't specify them, they will override their respective former values in an existing overwrite.

Specs

edit_channel_permissions!(
  integer(),
  integer(),
  %{
    :type => String.t(),
    optional(:allow) => integer(),
    optional(:deny) => integer()
  },
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | {:ok}

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

Specs

edit_global_application_command(
  Nostrum.Struct.User.id(),
  Nostrum.Snowflake.t(),
  Nostrum.Struct.ApplicationCommand.application_command_edit_map()
) :: {:ok, map()} | error()

Update an existing global application command.

The updated command will be available on all guilds in around an hour.

Parameters

• application_id: Application ID for which to edit the command. If not given, this will be fetched from Me.
• command_id: The current snowflake of the command.
• command: Command configuration, see the linked API documentation for reference.

Return value

The updated command. See the official reference: https://discord.com/developers/docs/interactions/application-commands#edit-global-application-command

Specs

edit_guild_application_command(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id(),
  Nostrum.Snowflake.t(),
  Nostrum.Struct.ApplicationCommand.application_command_edit_map()
) :: {:ok, map()} | error()

Update an existing guild application command.

The updated command will be available immediately.

Parameters

• application_id: Application ID for which to edit the command. If not given, this will be fetched from Me.
• guild_id: Guild for which to update the command.
• command_id: The current snowflake of the command.
• command: Command configuration, see the linked API documentation for reference.

Return value

The updated command. See the official reference: https://discord.com/developers/docs/interactions/application-commands#edit-guild-application-command

Specs

edit_interaction_response(Nostrum.Struct.Interaction.t(), map()) ::
  {:ok, Nostrum.Struct.Message.t()} | error()

Same as edit_interaction_response/3, but directly takes the Nostrum.Struct.Interaction.t/0 received from the gateway.

Specs

edit_interaction_response(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Interaction.token(),
  map()
) ::
  {:ok, Nostrum.Struct.Message.t()} | error()

Edits the original interaction response.

Functions the same as edit_webhook_message/3

Specs

edit_interaction_response!(Nostrum.Struct.Interaction.t(), map()) ::
  no_return() | Nostrum.Struct.Message.t()

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

Specs

edit_interaction_response!(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Interaction.token(),
  map()
) ::
  no_return() | Nostrum.Struct.Message.t()

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

Specs

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.

Specs

edit_message(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  options() | String.t()
) ::
  error() | {:ok, Nostrum.Struct.Message.t()}

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)
• :embeds (Nostrum.Struct.Embed.t/0) - a list of 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, embeds: [embed])

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

Specs

edit_message!(Nostrum.Struct.Message.t(), options()) ::
  no_return() | Nostrum.Struct.Message.t()

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

Specs

edit_message!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  options()
) ::
  no_return() | Nostrum.Struct.Message.t()

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

Specs

edit_webhook_message(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token(),
  Nostrum.Struct.Message.id(),
  map()
) :: error() | {:ok, Nostrum.Struct.Message.t()}

Edits a message previously created by the same webhook, args are the same as execute_webhook/3, however all fields are optional.

Specs

execute_git_webhook(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token(),
  boolean()
) ::
  error() | {:ok}

Executes a git webhook.

Parameters

• webhook_id - Id of the webhook to execute.
• webhook_token - Token of the webhook to execute.

Specs

execute_slack_webhook(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token(),
  boolean()
) ::
  error() | {:ok}

Executes a slack webhook.

Parameters

• webhook_id - Id of the webhook to execute.
• webhook_token - Token of the webhook to execute.

Specs

execute_webhook(
  Nostrum.Struct.Webhook.id() | Nostrum.Struct.User.id(),
  Nostrum.Struct.Webhook.token() | Nostrum.Struct.Interaction.token(),
  matrix(),
  boolean()
) :: error() | {:ok} | {:ok, Nostrum.Struct.Message.t()}

Executes a webhook.

## Parameters

• webhook_id - Id of the webhook to execute.
• webhook_token - Token of the webhook to execute.
• args - Map with the following allowed keys:
  • content - Message content.
  • files - List of Files to send.
  • embeds - List of embeds 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.
  • flags - Bitwise flags.
  • thread_id - Send a message to the specified thread within the webhook's channel.
• wait - Whether to return an error or not. Defaults to false.

Note: If wait is true, this method will return a Message.t() on success.

At least one of content, files or embeds should be supplied in the args parameter.

Specs

get_application_command_permissions(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id(),
  Nostrum.Snowflake.t()
) :: {:ok, map()} | error()

Fetches command permissions for a specific command for your application in a guild.

Parameters

• application_id: Application ID commands are registered under. If not given, this will be fetched from Me.
• guild_id: Guild ID to fetch command permissions from.
• command_id: Command ID to fetch permissions for.

Return value

This method returns a single guild application command permission object, see all available values on the Discord API docs.

Specs

get_application_information() :: error() | {:ok, map()}

Gets the bot's OAuth2 application info.

Example

Nostrum.Api.get_application_information
{:ok,
%{
  bot_public: false,
  bot_require_code_grant: false,
  description: "Test",
  icon: nil,
  id: "172150183260323840",
  name: "Baba O-Riley",
  owner: %{
    avatar: nil,
    discriminator: "0042",
    id: "172150183260323840",
    username: "i own a bot"
  },
}}

Specs

get_channel(Nostrum.Struct.Channel.id()) ::
  error() | {:ok, Nostrum.Struct.Channel.t()}

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}}

Specs

get_channel!(Nostrum.Struct.Channel.id()) ::
  no_return() | Nostrum.Struct.Channel.t()

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

Specs

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{} | _]}

Specs

get_channel_invites!(Nostrum.Struct.Channel.id()) ::
  no_return() | [Nostrum.Struct.Invite.detailed_invite()]

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

Specs

get_channel_message(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  error() | {:ok, Nostrum.Struct.Message.t()}

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)

Specs

get_channel_message!(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  no_return() | Nostrum.Struct.Message.t()

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

Specs

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

Retrieves 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})

Specs

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.

Specs

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

Gets a list of webhooks for a channel.

Parameters

• channel_id - Channel to get webhooks for.

Specs

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

Specs

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

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

Specs

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

• :before (Nostrum.Snowflake.t/0) - get guilds before this guild ID
• :after (Nostrum.Snowflake.t/0) - get guilds after this guild ID
• :limit (integer) - max number of guilds to return (1-100)

Examples

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

Specs

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.

Specs

get_global_application_commands(Nostrum.Struct.User.id()) ::
  {:ok, [map()]} | error()

Fetch all global commands.

Parameters

• application_id: Application ID for which to search commands. If not given, this will be fetched from Me.

Return value

A list of ApplicationCommands on success. See the official reference: https://discord.com/developers/docs/interactions/application-commands#application-command-object-application-command-structure

Example

iex> Nostrum.Api.get_global_application_commands
{:ok,
 [
   %{
     application_id: "455589479713865749",
     description: "ed, man! man, ed",
     id: "789841753196331029",
     name: "edit"
   }
 ]}

Specs

get_guild(Nostrum.Struct.Guild.id()) ::
  error() | {:ok, Nostrum.Struct.Guild.rest_guild()}

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}}

Specs

get_guild!(Nostrum.Struct.Guild.id()) ::
  no_return() | Nostrum.Struct.Guild.rest_guild()

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

Specs

get_guild_application_command_permissions(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id()
) ::
  {:ok, [map()]} | error()

Fetches command permissions for all commands for your application in a guild.

Parameters

• application_id: Application ID commands are registered under. If not given, this will be fetched from Me.
• guild_id: Guild ID to fetch command permissions from.

Return value

This method returns a list of guild application command permission objects, see all available values on the Discord API docs.

Specs

get_guild_application_commands(
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.id()
) ::
  {:ok, [map()]} | error()

Fetch all guild application commands for the given guild.

Parameters

• application_id: Application ID for which to fetch commands. If not given, this will be fetched from Me.
• guild_id: The guild ID for which guild application commands should be requested.

Return value

A list of ApplicationCommands on success. See the official reference: https://discord.com/developers/docs/interactions/application-commands#application-command-object-application-command-structure

Specs

get_guild_audit_log(Nostrum.Struct.Guild.id(), options()) ::
  {:ok, Nostrum.Struct.Guild.AuditLog.t()} | error()

Get the Nostrum.Struct.Guild.AuditLog.t/0 for the given guild_id.

Options

• :user_id (Nostrum.Struct.User.id/0) - filter the log for a user ID
• :action_type (integer/0) - filter the log by audit log type, see Audit Log Events
• :before (t:Nostrum.Struct.Snowflake.t/0) - filter the log before a certain entry ID
• :limit (pos_integer/0) - how many entries are returned (default 50, minimum 1, maximum 100)

Specs

get_guild_ban(integer(), integer()) ::
  error() | {:ok, Nostrum.Struct.Guild.Ban.t()}

Gets a ban object for the given user from a guild.

Specs

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

Gets a list of users banned from a guild.

Guild to get bans for is specified by guild_id.

Specs

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} | _]}

Specs

get_guild_channels!(Nostrum.Struct.Guild.id()) ::
  no_return() | [Nostrum.Struct.Channel.guild_channel()]

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

Specs

get_guild_emoji(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
  error() | {:ok, Nostrum.Struct.Emoji.t()}

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.

Specs

get_guild_emoji!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
  no_return() | Nostrum.Struct.Emoji.t()

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

Specs

get_guild_integrations(Nostrum.Struct.Guild.id()) ::
  error() | {:ok, [Nostrum.Struct.Guild.Integration.t()]}

Gets a list of guild integerations.

Guild to get integrations for is specified by guild_id.

Specs

get_guild_invites(Nostrum.Struct.Guild.id()) ::
  error() | {:ok, [Nostrum.Struct.Invite.detailed_invite()]}

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{} | _]}

Specs

get_guild_invites!(Nostrum.Struct.Guild.id()) ::
  no_return() | [Nostrum.Struct.Invite.detailed_invite()]

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

Specs

get_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
  error() | {:ok, Nostrum.Struct.Guild.Member.t()}

Gets a guild member.

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

Examples

Nostrum.Api.get_guild_member(4019283754613, 184937267485)

Specs

get_guild_member!(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
  no_return() | Nostrum.Struct.Guild.Member.t()

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

Specs

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}}

Specs

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.

Specs

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)

Specs

get_guild_roles!(Nostrum.Struct.Guild.id()) ::
  no_return() | [Nostrum.Struct.Guild.Role.t()]

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

Specs

get_guild_scheduled_event(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.ScheduledEvent.id()
) ::
  error() | {:ok, Nostrum.Struct.Guild.ScheduledEvent.t()}

Get a scheduled event for a guild.

Specs

get_guild_scheduled_event_users(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.ScheduledEvent.id(),
  options()
) :: error() | {:ok, [Nostrum.Struct.Guild.ScheduledEvent.User.t()]}

Get a list of users who have subscribed to an event.

Options

All are optional, with their default values listed.

• :limit (integer) maximum number of users to return, defaults to 100
• :with_member (boolean) whether to include the member object for each user, defaults to false
• :before (Nostrum.Snowflake.t/0) return only users before this user id, defaults to nil
• :after (Nostrum.Snowflake.t/0) return only users after this user id, defaults to nil

Specs

get_guild_scheduled_events(Nostrum.Struct.Guild.id()) ::
  error() | {:ok, [Nostrum.Struct.Guild.ScheduledEvent.t()]}

Get a list of scheduled events for a guild.

Specs

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

Gets a list of webhooks for a guild.

Parameters

• guild_id - Guild to get webhooks for.

Specs

get_guild_widget(integer()) :: error() | {:ok, map()}

Gets a guild embed.

Specs

get_invite(Nostrum.Struct.Invite.code(), options()) ::
  error() | {:ok, Nostrum.Struct.Invite.simple_invite()}

Gets an invite by its invite_code.

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

Options

• :with_counts (boolean) - whether to include member count fields

Examples

Nostrum.Api.get_invite("zsjUsC")

Nostrum.Api.get_invite("zsjUsC", with_counts: true)

Specs

get_invite!(Nostrum.Struct.Invite.code(), options()) ::
  no_return() | Nostrum.Struct.Invite.simple_invite()

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

Specs

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)

Specs

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.

Specs

get_reactions(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id(), emoji()) ::
  error() | {:ok, [Nostrum.Struct.User.t()]}

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.

Specs

get_reactions!(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji()
) ::
  no_return() | [Nostrum.Struct.User.t()]

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

Specs

get_thread_member(Nostrum.Struct.Channel.id(), Nostrum.Struct.User.id()) ::
  {:ok, Nostrum.Struct.ThreadMember.t()} | error()

Returns a thread member object for the specified user if they are a member of the thread

Specs

get_thread_members(Nostrum.Struct.Channel.id()) ::
  {:ok, [Nostrum.Struct.ThreadMember.t()]} | error()

Returns a list of thread members for the specified thread.

This endpoint is restricted according to whether the GUILD_MEMBERS privileged intent is enabled.

Specs

get_token() :: String.t()

Returns the token of the bot.

Specs

get_user(Nostrum.Struct.User.id()) :: error() | {:ok, Nostrum.Struct.User.t()}

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

Specs

get_user!(Nostrum.Struct.User.id()) :: no_return() | Nostrum.Struct.User.t()

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

Specs

get_user_connections() :: error() | {:ok, list()}

Gets a list of user connections.

Specs

get_user_dms() :: error() | {:ok, [Nostrum.Struct.Channel.dm_channel()]}

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} | _]}

Specs

get_user_dms!() :: no_return() | [Nostrum.Struct.Channel.dm_channel()]

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

Specs

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.

Specs

get_webhook(Nostrum.Struct.Webhook.id()) ::
  error() | {:ok, Nostrum.Struct.Webhook.t()}

Gets a webhook by id.

Parameters

• webhook_id - Id of the webhook to get.

Specs

get_webhook_with_token(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token()
) ::
  error() | {:ok, Nostrum.Struct.Webhook.t()}

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 the webhook to get.
• webhook_token - Token of the webhook to get.

Specs

join_thread(Nostrum.Struct.Channel.id()) :: {:ok} | error()

Join an existing thread, requires that the thread is not archived.

Specs

leave_guild(integer()) :: error() | {:ok}

Leaves a guild.

Guild to leave is specified by guild_id.

Specs

leave_thread(Nostrum.Struct.Channel.id()) :: {:ok} | error()

Leave a thread, requires that the thread is not archived.

Specs

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.

Specs

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.

Specs

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)

Specs

list_guild_members!(Nostrum.Struct.Guild.id(), options()) ::
  no_return() | [Nostrum.Struct.Guild.Member.t()]

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

Specs

list_guild_threads(Nostrum.Struct.Guild.id()) ::
  {:ok,
   %{
     threads: [Nostrum.Struct.Channel.t()],
     members: [Nostrum.Struct.ThreadMember.t()]
   }}
  | error()

Return all active threads for the current guild.

Response body is a map with the following keys:

• threads: A list of channel objects.
• members: A list of ThreadMember objects, one for each returned thread the current user has joined.

Specs

list_joined_private_archived_threads(Nostrum.Struct.Channel.id(), options()) ::
  {:ok,
   %{
     threads: [Nostrum.Struct.Channel.t()],
     members: [Nostrum.Struct.ThreadMember.t()],
     has_more: boolean()
   }}
  | error()

Same as list_public_archived_threads/2, but only returns private threads that the current user has joined.

Specs

list_private_archived_threads(Nostrum.Struct.Channel.id(), options()) ::
  {:ok,
   %{
     threads: [Nostrum.Struct.Channel.t()],
     members: [Nostrum.Struct.ThreadMember.t()],
     has_more: boolean()
   }}
  | error()

Same as list_public_archived_threads/2, but for private threads instead of public.

Specs

list_public_archived_threads(Nostrum.Struct.Channel.id(), options()) ::
  {:ok,
   %{
     threads: [Nostrum.Struct.Channel.t()],
     members: [Nostrum.Struct.ThreadMember.t()],
     has_more: boolean()
   }}
  | error()

Returns a list of archived threads for a given channel.

Threads are sorted by the archive_timestamp field, in descending order.

Response body

Response body is a map with the following keys:

• threads: A list of channel objects.
• members: A list of ThreadMember objects, one for each returned thread the current user has joined.
• has_more: A boolean indicating whether there are more archived threads that can be fetched.

Options

• before: Returns threads before this timestamp, can be either a DateTime or ISO8601 timestamp.
• limit: Optional maximum number of threads to return.

Specs

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

Gets a list of voice regions.

Specs

modify_channel(
  Nostrum.Struct.Channel.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Channel.t()}

Modifies a channel's settings.

An optional reason can be given for the guild audit log.

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.guild_category_channel/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

• :name (string) - 2-100 character channel name
• :position (integer) - the position of the channel in the left-hand listing
• :topic (string) (Nostrum.Struct.Channel.text_channel/0 only) - 0-1024 character channel topic
• :nsfw (boolean) (Nostrum.Struct.Channel.text_channel/0 only) - if the channel is nsfw
• :bitrate (integer) (Nostrum.Struct.Channel.voice_channel/0 only) - the bitrate (in bits) of the voice channel; 8000 to 96000 (128000 for VIP servers)
• :user_limit (integer) (Nostrum.Struct.Channel.voice_channel/0 only) - the user limit of the voice channel; 0 refers to no limit, 1 to 99 refers to a user limit
• :permission_overwrites (list of Nostrum.Struct.Overwrite.t/0 or equivalent map) - channel or category-specific permissions
• :parent_id (Nostrum.Struct.Channel.id/0) (Nostrum.Struct.Channel.guild_channel/0 only) - id of the new parent category for a channel

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}}

Specs

modify_channel!(
  Nostrum.Struct.Channel.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Channel.t()

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

Specs

modify_current_user(options()) :: 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=")

Specs

modify_current_user!(options()) :: no_return() | Nostrum.Struct.User.t()

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

Specs

modify_current_user_nick(Nostrum.Struct.Guild.id(), options()) ::
  error() | {:ok, %{nick: String.t()}}

Modifies the nickname of the current user in a guild.

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

Options

• :nick (string) - value to set users nickname to

Examples

Nostrum.Api.modify_current_user_nick(41771983423143937, nick: "Nostrum")
{:ok, %{nick: "Nostrum"}}

Specs

modify_current_user_nick!(Nostrum.Struct.Guild.id(), options()) ::
  no_return() | %{nick: String.t()}

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

Specs

modify_guild(
  Nostrum.Struct.Guild.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  error() | {:ok, Nostrum.Struct.Guild.rest_guild()}

Modifies a guild's settings.

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

An optional reason can be provided for the audit log.

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.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.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.Snowflake.t/0) - the id of the channel to which system messages are sent
• :rules_channel_id (Nostrum.Snowflake.t/0) - the id of the channel that is used for rules in public guilds
• :public_updates_channel_id (Nostrum.Snowflake.t/0) - the id of the channel where admins and moderators receive notices from Discord in public guilds

Examples

Nostrum.Api.modify_guild(451824027976073216, name: "Nose Drum")
{:ok, %Nostrum.Struct.Guild{id: 451824027976073216, name: "Nose Drum", ...}}

Specs

modify_guild!(Nostrum.Struct.Guild.id(), options()) ::
  no_return() | Nostrum.Struct.Guild.rest_guild()

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

Specs

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}

Specs

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.

Specs

modify_guild_emoji(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Emoji.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Emoji.t()}

Modify the given emoji.

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

An optional reason can be provided for the audit log.

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

Options

• :name (string) - name of the emoji
• :roles (list of Nostrum.Snowflake.t/0) - roles to which this emoji will be whitelisted

Examples

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

Specs

modify_guild_emoji!(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Emoji.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Emoji.t()

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

Specs

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.

Specs

modify_guild_member(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Guild.Member.t()}

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, member}. Otherwise, returns a Nostrum.Api.error/0.

An optional reason argument can be given for the audit log.

Options

• :nick (string) - value to set users nickname to
• :roles (list of Nostrum.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.Snowflake.t/0) - id of channel to move user to (if they are connected to voice)
• :communication_disabled_until (DateTime.t/0 or nil) - datetime to disable user communication (timeout) until, or nil to remove timeout.

Examples

Nostrum.Api.modify_guild_member(41771983423143937, 637162356451, nick: "Nostrum")
{:ok, %Nostrum.Struct.Member{}}

Specs

modify_guild_member!(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}

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

Specs

modify_guild_role(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Role.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Guild.Role.t()}

Modifies a guild role.

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

An optional reason can be specified for the audit log.

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

Specs

modify_guild_role!(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Role.id(),
  options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Guild.Role.t()

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

Specs

modify_guild_role_positions(
  Nostrum.Struct.Guild.id(),
  [%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}],
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: 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}])

Specs

modify_guild_role_positions!(
  Nostrum.Struct.Guild.id(),
  [%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}],
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | [Nostrum.Struct.Guild.Role.t()]

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

Specs

modify_guild_scheduled_event(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.ScheduledEvent.id(),
  reason :: Nostrum.Struct.Guild.AuditLogEntry.reason(),
  options()
) :: error() | {:ok, Nostrum.Struct.Guild.ScheduledEvent.t()}

Modify a scheduled event for a guild.

Options are the same as for create_guild_scheduled_event/2 except all fields are optional, with the additional optional integer field :status which can be one of:

• 1 - SCHEDULED
• 2 - ACTIVE
• 3 - COMPLETED
• 4 - CANCELLED

Copied from the official documentation:

• If updating entity_type to EXTERNAL:
  • channel_id is required and must be set to null
  • entity_metadata with a location field must be provided
  • scheduled_end_time must be provided

Specs

modify_guild_widget(integer(), map()) :: error() | {:ok, map()}

Modifies a guild embed.

Specs

modify_webhook(
  Nostrum.Struct.Webhook.id(),
  %{name: String.t(), avatar: String.t()},
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: 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.
• reason - An optional reason for the guild audit log.

Specs

modify_webhook_with_token(
  Nostrum.Struct.Webhook.id(),
  Nostrum.Struct.Webhook.token(),
  %{name: String.t(), avatar: String.t()},
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: 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.
• reason - An optional reason for the guild audit log.

Specs

remove_guild_ban(
  integer(),
  integer(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  error() | {:ok}

Removes a ban for a user.

User to unban is specified by guild_id and user_id. An optional reason can be specified for the audit log.

Specs

remove_guild_member(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: 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.

An optional reason can be provided for the audit log with reason.

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

Examples

Nostrum.Api.remove_guild_member(1453827904102291, 18739485766253)
{:ok}

Specs

remove_guild_member!(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | {:ok}

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

Specs

remove_guild_member_role(
  integer(),
  integer(),
  integer(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: 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. An optional reason can be given for the audit log.

Specs

remove_thread_member(Nostrum.Struct.Channel.id(), Nostrum.Struct.User.id()) ::
  {:ok} | error()

Removes another user from a thread, requires that the thread is not archived.

Also requires the MANAGE_THREADS permission, or the creator of the thread if the thread is private.

Specs

request(map()) :: {:ok} | {:ok, String.t()} | error()

Specs

request(atom(), String.t(), any(), keyword() | map()) ::
  {:ok} | {:ok, String.t()} | error()

Specs

request_multipart(atom(), String.t(), any(), keyword() | map()) ::
  {:ok} | {:ok, String.t()} | error()

Specs

start_thread(
  Nostrum.Struct.Channel.id(),
  thread_without_message_params(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: {:ok, Nostrum.Struct.Channel.t()} | error()

Create a thread on a channel without an associated message.

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

An optional reason argument can be given for the audit log.

Options

• name: Name of the thread, max 100 characters.
• type: Type of thread, can be either 11 (GUILD_PUBLIC_THREAD) or 12 (GUILD_PRIVATE_THREAD).
• auto_archive_duration: Duration in minutes to auto-archive the thread after it has been inactive, can be set to 60, 1440, 4320, or 10080.
• invitable: whether non-moderators can add other non-moderators to a thread; only available when creating a private thread defaults to false.
• rate_limit_per_user: Rate limit per user in seconds, can be set to any value in 0..21600.

Specs

start_thread_with_message(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  thread_with_message_params(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: {:ok, Nostrum.Struct.Channel.t()} | error()

Create a thread on a channel message.

The thread_id will be the same as the id of the message, as such no message can have more than one thread.

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

An optional reason argument can be given for the audit log.

Options

• name: Name of the thread, max 100 characters.
• auto_archive_duration: Duration in minutes to auto-archive the thread after it has been inactive, can be set to 60, 1440, 4320, or 10080.
• rate_limit_per_user: Rate limit per user in seconds, can be set to any value in 0..21600.

Specs

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.

Specs

start_typing!(integer()) :: no_return() | {:ok}

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

Specs

sync_guild_integrations(integer(), integer()) :: error() | {:ok}

Syncs a guild integration.

Integration to sync is specified by guild_id and integeration_id.

Specs

update_shard_status(pid(), status(), String.t(), integer(), String.t() | nil) ::
  :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

Specs

update_status(status(), String.t(), integer(), String.t() | nil) :: :ok

Updates the status of the bot for all shards.

See update_shard_status/5 for usage.

Specs

update_voice_state(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Channel.id() | nil,
  boolean(),
  boolean()
) :: no_return() | :ok

Joins, moves, or disconnects the bot from a voice channel.

The correct shard to send the update to will be inferred from the guild_id. If a corresponding guild_id is not found a cache error will be raised.

To disconnect from a channel, channel_id should be set to nil.