@spec 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

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

Examples

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

@spec 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.

@spec 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.

@spec 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

Examples

Nostrum.Api.add_pinned_channel_message(43189401384091, 18743893102394)

@spec 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.

@spec 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

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

Return value

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

@spec 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

Examples

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

@spec 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.

@spec 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.

@spec 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.

@spec 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

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

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

@spec 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

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

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

@spec 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

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

Examples

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

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

@spec 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.

@spec 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

Examples

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

@spec 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.

@spec 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.

@spec 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.

@spec 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

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

Return value

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

example

Example

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

@spec 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

Examples

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

@spec 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.

@spec 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

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

Return value

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

@spec create_guild_auto_moderation_rule(Nostrum.Struct.Guild.id(), options()) ::
  {:ok, Nostrum.Struct.AutoModerationRule.t()} | error()

Create a new auto-moderation rule for a guild.

options

Options

• :name (String.t/0) - The name of the rule.
• :event_type (t:AutoModerationRule.event_type/0) - The type of event that triggers the rule.
• :trigger_type (t:AutoModerationRule.trigger_type/0) - The type of content that triggers the rule.
• :trigger_metadata (t:AutoModerationRule.trigger_metadata/0) - The metadata associated with the rule trigger.
  • optional, based on the :trigger_type.
• :actions (t:AutoModerationRule.actions/0) - The actions to take when the rule is triggered.
• :enabled (t:AutoModerationRule.enabled/0) - Whether the rule is enabled or not.
  • optional, defaults to false.
• :exempt_roles - (t:AutoModerationRule.exempt_roles/0) - A list of role id's that are exempt from the rule.
  • optional, defaults to [], maximum of 20.
• :exempt_channels - (t:AutoModerationRule.exempt_channels/0) - A list of channel id's that are exempt from the rule.
  • optional, defaults to [], maximum of 50.

@spec 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.

@spec 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

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

Examples

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

@spec 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.

@spec 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

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

Examples

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

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

@spec 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.

@spec 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.

@spec 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

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)
• :icon (string) - URL role icon (default: nil)
• :unicode_emoji (string) - standard unicode character emoji role icon (default: nil)

examples

Examples

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

@spec 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.

@spec 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

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.

@spec 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.

@spec 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

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

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

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.

@spec 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.

@spec 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

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 (allowed_mentions/0) - see the allowed mentions type documentation
• :message_reference (map) - See "Message references" below

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

message-reference

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

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)

@spec 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.

@spec 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

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.

@spec 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.

@spec 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

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.

@spec 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.

@spec 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.

@spec 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

Examples

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

@spec 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.

@spec 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.

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

Delete an existing global application command.

parameters

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.

@spec 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

Examples

Nostrum.Api.delete_guild(81384788765712384)
{:ok}

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

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

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

Delete an existing guild application command.

parameters

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.

@spec delete_guild_auto_moderation_rule(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.AutoModerationRule.id()
) :: {:ok} | error()

Delete an auto-moderation rule for a guild.

@spec 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.

@spec 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.

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

Deletes a guild integeration.

Integration to delete is specified by guild_id and integeration_id.

@spec 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

Examples

Nostrum.Api.delete_guild_role(41771983423143937, 392817238471936)

@spec 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.

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

Delete a scheduled event for a guild.

@spec 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

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.

@spec 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.

@spec 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.

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

Deletes the original interaction response.

@spec 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.

@spec 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

Examples

Nostrum.Api.delete_invite("zsjUsC")

@spec 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.

@spec 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.

@spec 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

Examples

Nostrum.Api.delete_message(43189401384091, 43189401384091)

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

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

@spec 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.

@spec 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.

@spec 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.

@spec 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.

@spec 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.

@spec 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.

@spec 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.

@spec 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.

@spec 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.

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

Deletes a webhook.

parameters

Parameters

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

@spec 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

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

Return value

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

@spec 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.

@spec 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.

@spec 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

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

Return value

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

@spec 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

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

Return value

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

@spec 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.

@spec 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

@spec 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.

@spec 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.

@spec 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.

@spec 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

Options

• :content (string) - the message contents (up to 2000 characters)
• :embeds (Nostrum.Struct.Embed.t/0) - a list of embedded rich content
• :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. See create_message/2 for more information.

Note that if you edit a message with attachments, all attachments that should be present after edit must be included in your request body. This includes attachments that were sent in the original request.

examples

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

@spec 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.

@spec 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.

@spec 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.

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

Executes a git webhook.

parameters

Parameters

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

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

Executes a slack webhook.

parameters

Parameters

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

@spec 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

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.
  • allowed_mentions - Mentions to allow in the webhook message
• 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.

@spec 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

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

Return value

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

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

Gets the bot's OAuth2 application info.

example

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

@spec 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

Examples

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

@spec 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.

@spec 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

Examples

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

@spec 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.

@spec 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

Examples

Nostrum.Api.get_channel_message(43189401384091, 198238475613443)

@spec 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.

@spec 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

Examples

Nostrum.Api.get_channel_messages(43189401384091, 5, {:before, 130230401384})

@spec 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.

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

Gets a list of webhooks for a channel.

parameters

Parameters

• channel_id - Channel to get webhooks for.

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

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

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

@spec 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

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

Examples

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

@spec 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.

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

Fetch all global commands.

parameters

Parameters

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

return-value

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

Example

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

@spec 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

Examples

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

@spec 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.

@spec 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

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

Return value

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

@spec 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

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

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

@spec 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

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)

@spec get_guild_auto_moderation_rule(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.AutoModerationRule.id()
) ::
  {:ok, Nostrum.Struct.AutoModerationRule.t()} | error()

Get a single auto-moderation rule for a guild.

@spec get_guild_auto_moderation_rules(Nostrum.Struct.Guild.id()) ::
  {:ok, [Nostrum.Struct.AutoModerationRule.t()]} | error()

Get a list of all auto-moderation rules for a guild.

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

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

@spec 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.

@spec 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

Examples

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

@spec 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.

@spec 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.

@spec 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.

@spec 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.

@spec 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

Examples

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

@spec 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.

@spec 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

Examples

Nostrum.Api.get_guild_member(4019283754613, 184937267485)

@spec 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.

@spec 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

Examples

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

@spec 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.

@spec 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

Examples

Nostrum.Api.get_guild_roles(147362948571673)

@spec 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.

@spec 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.

@spec 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

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

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

Get a list of scheduled events for a guild.

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

Gets a list of webhooks for a guild.

parameters

Parameters

• guild_id - Guild to get webhooks for.

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

Gets a guild embed.

@spec 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

Options

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

examples

Examples

Nostrum.Api.get_invite("zsjUsC")

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

@spec 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.

@spec get_original_interaction_response(Nostrum.Struct.Interaction.t()) ::
  error() | {:ok, Nostrum.Struct.Message.t()}

Retrieves the original message of an interaction.

@spec 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

Examples

Nostrum.Api.get_pinned_messages(43189401384091)

@spec 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.

@spec get_reactions(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  emoji(),
  keyword()
) ::
  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.

The optional params are after, the user ID to query after, absent by default, and limit, the max number of users to return, 1-100, 25 by default.

See create_reaction/3 for similar examples.

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

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

@spec 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

@spec 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.

@spec get_token() :: String.t()

Returns the token of the bot.

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

@spec 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.

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

Gets a list of user connections.

@spec 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

Examples

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

@spec 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.

@spec 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.

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

Gets a webhook by id.

parameters

Parameters

• webhook_id - Id of the webhook to get.

@spec get_webhook_message(Nostrum.Struct.Webhook.t(), Nostrum.Struct.Message.id()) ::
  error() | {:ok, Nostrum.Struct.Message.t()}

Retrieves the original message of a webhook.

@spec 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

Parameters

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

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

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

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

Leaves a guild.

Guild to leave is specified by guild_id.

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

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

@spec 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.

@spec 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.

@spec 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

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

Examples

Nostrum.Api.list_guild_members(41771983423143937, limit: 1)

@spec 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.

@spec 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.

@spec 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.

@spec 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.

@spec 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

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

Options

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

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

Gets a list of voice regions.

@spec 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

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

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

@spec 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.

@spec modify_current_user(options()) :: error() | {:ok, Nostrum.Struct.User.t()}

Changes the username or avatar of the current user.

options

Options

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

examples

Examples

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

@spec 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.

@spec 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

Options

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

examples

Examples

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

@spec 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.