View Source Nostrum.Api (Nostrum v0.6.1)

Interface for Discord's rest API.

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

Examples

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

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

A note about Strings and Ints

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

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

Example

messages = Nostrum.Api.get_pinned_messages!(12345678912345)

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

Link to this section Summary

Types

Represents an emoji for interacting with reaction endpoints.

Represents a failed response from the API.

Represents a limit used to retrieve messages.

Represents a tuple used to locate messages.

Represents optional parameters for Api functions.

Represents different statuses the bot can have.

Functions

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

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.

Begins a guild prune to prune members within days.

Deletes multiple messages from a channel.

Overwrite the existing guild application commands on the specified guild.

Create a new DM channel with a user.

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

Creates a new group DM channel.

Create a guild application command on the specified guild.

Creates a channel for a guild.

Creates a new emoji for the given guild.

Creates a new guild integeration.

Creates a new scheduled event for the guild.

Create a response to an interaction received from the gateway.

Posts a message to a guild text or DM channel.

Creates a reaction for a message.

Deletes all reactions from a message.

Delete a channel permission for a user or role.

Deletes a guild.

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

Delete a scheduled event for a guild.

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

Deletes the original interaction response.

Deletes an invite by its invite_code.

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

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

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

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

Deletes all reactions of a given emoji from a message.

Deletes another user's reaction from a message.

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.

Edits the original interaction response.

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

Edits a previously sent message in a channel.

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

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

Gets the bot's OAuth2 application info.

Gets a channel.

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

Gets a list of invites for a channel.

Retrieves a message from a channel.

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

Gets a list of webhooks for a channel.

Gets info on the current user.

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

Gets a list of guilds the user is currently in.

Gets a guild.

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

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

Fetch all guild application commands for the given guild.

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

Gets a list of users banned from a guild.

Gets a list of guild channels.

Gets an emoji for the given guild and emoji ids.

Gets a list of guild integerations.

Gets a list of invites for a guild.

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

Gets a guild's roles.

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

Get a scheduled event for a guild.

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

Get a list of scheduled events for a guild.

Gets a list of webhooks for a guild.

Gets a guild embed.

Gets an invite by its invite_code.

Retrieves all pinned messages from a channel.

Gets all users who reacted with an emoji.

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

Returns a list of thread members for the specified thread.

Returns the token of the bot.

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

Gets a list of user connections.

Gets a list of our user's DM channels.

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

Gets a list of voice regions for the guild.

Gets a webhook by id.

Gets a webhook by id and token.

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

Leaves a guild.

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

Gets a list of emojis for a given guild.

Gets a list of a guild's members.

Return all active threads for the current guild.

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

Returns a list of archived threads for a given channel.

Gets a list of voice regions.

Changes the username or avatar of the current user.

Modifies the nickname of the current user in a guild.

Changes the settings and behaviours for a guild integeration.

Modifies a guild embed.

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

Create a thread on a channel without an associated message.

Triggers the typing indicator.

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

Updates the status of the bot for a certain shard.

Updates the status of the bot for all shards.

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

Link to this section Types

Specs

Represents an emoji for interacting with reaction endpoints.

Specs

error() :: {:error, Nostrum.Error.ApiError.t()}

Represents a failed response from the API.

This occurs when :gun fails, or when the API doesn't respond with 200 or 204.

Specs

limit() :: integer() | :infinity

Represents a limit used to retrieve messages.

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

Specs

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

Represents a tuple used to locate messages.

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

Specs

matrix() :: m1() | m2() | m3()

Specs

options() :: keyword() | map()

Represents optional parameters for Api functions.

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

Specs

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

Represents different statuses the bot can have.

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

thread_with_message_params()

View Source

Specs

thread_with_message_params() :: %{
  :name => String.t(),
  optional(:auto_archive_duration) => 60 | 1440 | 4320 | 10080,
  optional(:rate_limit_per_user) => 0..21600
}
Link to this type

thread_without_message_params()

View Source

Specs

thread_without_message_params() :: %{
  :name => String.t(),
  :type => non_neg_integer(),
  optional(:auto_archive_duration) => 60 | 1440 | 4320 | 10080,
  optional(:invitable) => boolean(),
  optional(:rate_limit_per_user) => 0..21600
}

Link to this section Functions

Link to this function

add_guild_member(guild_id, user_id, options)

View Source

Specs

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

add_guild_member!(guild_id, user_id, options)

View Source

Specs

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

Link to this function

add_guild_member_role(guild_id, user_id, role_id, reason \\ nil)

View Source

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.

Link to this function

add_pinned_channel_message(channel_id, message_id)

View Source

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

add_pinned_channel_message!(channel_id, message_id)

View Source

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.

Link to this function

add_thread_member(thread_id, user_id)

View Source (since 0.5.1)

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

Link to this function

batch_edit_application_command_permissions(application_id \\ Me.get().id, guild_id, permissions)

View Source (since 0.5.0)

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.

Link to this function

begin_guild_prune(guild_id, days, reason \\ nil)

View Source

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

begin_guild_prune!(guild_id, days, reason)

View Source

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.

Link to this function

bulk_delete_messages(channel_id, messages, filter \\ true)

View Source

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.

Link to this function

bulk_delete_messages!(channel_id, messages, filter \\ true)

View Source

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.

Link to this function

bulk_overwrite_global_application_commands(application_id \\ Me.get().id, commands)

View Source (since 0.5.0)

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

Link to this function

bulk_overwrite_guild_application_commands(application_id \\ Me.get().id, guild_id, commands)

View Source (since 0.5.0)

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

Link to this function

create_channel_invite(channel_id, options \\ [], reason \\ nil)

View Source

Specs

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

create_channel_invite!(channel_id, options \\ [], reason \\ nil)

View Source

Specs

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

Specs

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

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

Link to this function

create_followup_message(application_id \\ Me.get().id, token, webhook_payload)

View Source

Specs

Create a followup message for an interaction.

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

Link to this function

create_followup_message!(application_id \\ Me.get().id, token, webhook_payload)

View Source (since 0.5.0)

Specs

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

Link to this function

create_global_application_command(application_id \\ Me.get().id, command)

View Source

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: []}
)
Link to this function

create_group_dm(access_tokens, nicks)

View Source

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

create_group_dm!(access_tokens, nicks)

View Source

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.

Link to this function

create_guild_application_command(application_id \\ Me.get().id, guild_id, command)

View Source

Specs

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

Link to this function

create_guild_ban(guild_id, user_id, days_to_delete, reason \\ nil)

View Source

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.

Link to this function

create_guild_channel(guild_id, options)

View Source

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

create_guild_channel!(guild_id, options)

View Source

Specs

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

Link to this function

create_guild_emoji(guild_id, options, reason \\ nil)

View Source

Specs

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

create_guild_emoji!(guild_id, params, reason \\ nil)

View Source

Specs

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

Link to this function

create_guild_integrations(guild_id, options)

View Source

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

create_guild_role(guild_id, options, reason \\ nil)

View Source

Specs

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

create_guild_role!(guild_id, options, reason \\ nil)

View Source

Specs

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

Link to this function

create_guild_scheduled_event(guild_id, reason \\ nil, options)

View Source (since 0.5.0)

Specs

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.

Link to this function

create_interaction_response(interaction, response)

View Source

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.

Link to this function

create_interaction_response(id, token, options)

View Source

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.

Link to this function

create_interaction_response!(interaction, response)

View Source (since 0.5.0)

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.

Link to this function

create_interaction_response!(id, token, response)

View Source
Link to this function

create_message(channel_id, options)

View Source

Specs

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

create_message!(channel_id, options)

View Source

Specs

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

Link to this function

create_reaction(channel_id, message_id, emoji)

View Source

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.

Link to this function

create_reaction!(channel_id, message_id, emoji)

View Source

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.

Link to this function

create_webhook(channel_id, args, reason \\ nil)

View Source

Specs

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

delete_all_reactions(channel_id, message_id)

View Source

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.

Link to this function

delete_all_reactions!(channel_id, message_id)

View Source

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.

Link to this function

delete_channel(channel_id, reason \\ nil)

View Source

Specs

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

delete_channel!(channel_id, reason \\ nil)

View Source

Specs

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

Link to this function

delete_channel_permissions(channel_id, overwrite_id, reason \\ nil)

View Source

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.

Link to this function

delete_global_application_command(application_id \\ Me.get().id, command_id)

View Source

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.

Link to this function

delete_guild_application_command(application_id \\ Me.get().id, guild_id, command_id)

View Source

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

delete_guild_emoji(guild_id, emoji_id, reason \\ nil)

View Source

Specs

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.

Link to this function

delete_guild_emoji!(guild_id, emoji_id, reason \\ nil)

View Source

Specs

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

Link to this function

delete_guild_integrations(guild_id, integration_id)

View Source

Specs

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

Deletes a guild integeration.

Integration to delete is specified by guild_id and integeration_id.

Link to this function

delete_guild_role(guild_id, role_id, reason \\ nil)

View Source

Specs

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

delete_guild_role!(guild_id, role_id, reason \\ nil)

View Source

Specs

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

Link to this function

delete_guild_scheduled_event(guild_id, event_id)

View Source (since 0.5.0)

Specs

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

Delete a scheduled event for a guild.

Link to this function

delete_interaction_followup_message(application_id \\ Me.get().id, token, message_id)

View Source

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

delete_interaction_followup_message!(application_id \\ Me.get().id, token, message_id)

View Source (since 0.5.0)

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.

Link to this function

delete_interaction_response(interaction)

View Source (since 0.5.0)

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.

Link to this function

delete_interaction_response(id \\ Me.get().id, token)

View Source (since 0.5.0)

Specs

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

Deletes the original interaction response.

Link to this function

delete_interaction_response!(interaction)

View Source (since 0.5.0)

Specs

delete_interaction_response!(Nostrum.Struct.Interaction.t()) ::
  no_return() | {:ok}
Link to this function

delete_interaction_response!(id \\ Me.get().id, token)

View Source (since 0.5.0)

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.

Link to this function

delete_invite(invite_code)

View Source

Specs

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

delete_invite!(invite_code)

View Source

Specs

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.

Link to this function

delete_message(channel_id, message_id)

View Source

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

delete_message!(message)

View Source

Specs

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

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

Link to this function

delete_message!(channel_id, message_id)

View Source

Specs

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

Link to this function

delete_own_reaction(channel_id, message_id, emoji)

View Source

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.

Link to this function

delete_own_reaction!(channel_id, message_id, emoji)

View Source

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.

Link to this function

delete_pinned_channel_message(channel_id, message_id)

View Source

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.

Link to this function

delete_pinned_channel_message!(channel_id, message_id)

View Source

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.

Link to this function

delete_reaction(channel_id, message_id, emoji)

View Source

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.

Link to this function

delete_reaction!(channel_id, message_id, emoji)

View Source

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.

Link to this function

delete_user_reaction(channel_id, message_id, emoji, user_id)

View Source

Specs

Deletes another user's reaction from a message.

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

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

See create_reaction/3 for similar examples.

Link to this function

delete_user_reaction!(channel_id, message_id, emoji, user_id)

View Source

Specs

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

Link to this function

delete_webhook(webhook_id, reason \\ nil)

View Source

Specs

Deletes a webhook.

Parameters

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

edit_application_command_permissions(application_id \\ Me.get().id, guild_id, command_id, permissions)

View Source (since 0.5.0)

Specs

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.

Link to this function

edit_channel_permissions(channel_id, overwrite_id, permission_info, reason \\ nil)

View Source

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.

Link to this function

edit_channel_permissions!(channel_id, overwrite_id, permission_info, reason \\ nil)

View Source

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.

Link to this function

edit_global_application_command(application_id \\ Me.get().id, command_id, command)

View Source

Specs

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

Link to this function

edit_guild_application_command(application_id \\ Me.get().id, guild_id, command_id, command)

View Source

Specs

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

Link to this function

edit_interaction_response(interaction, response)

View Source (since 0.5.0)

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.

Link to this function

edit_interaction_response(id \\ Me.get().id, token, response)

View Source (since 0.5.0)

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

Link to this function

edit_interaction_response!(interaction, response)

View Source (since 0.5.0)

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.

Link to this function

edit_interaction_response!(id \\ Me.get().id, token, response)

View Source (since 0.5.0)

Specs

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

Link to this function

edit_message(message, options)

View Source

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.

Link to this function

edit_message(channel_id, message_id, options)

View Source

Specs

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

edit_message!(message, options)

View Source

Specs

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

Link to this function

edit_message!(channel_id, message_id, options)

View Source

Specs

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

Link to this function

edit_webhook_message(webhook_id, webhook_token, message_id, args)

View Source (since 0.5.0)

Specs

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

Link to this function

execute_git_webhook(webhook_id, webhook_token, wait \\ false)

View Source

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

execute_slack_webhook(webhook_id, webhook_token, wait \\ false)

View Source

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

execute_webhook(webhook_id, webhook_token, args, wait \\ false)

View Source

Specs

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.

Link to this function

get_application_command_permissions(application_id \\ Me.get().id, guild_id, command_id)

View Source (since 0.5.0)

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.

Link to this function

get_application_information()

View Source

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

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

get_channel!(channel_id)

View Source

Specs

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

Link to this function

get_channel_invites(channel_id)

View Source

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

get_channel_invites!(channel_id)

View Source

Specs

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

Link to this function

get_channel_message(channel_id, message_id)

View Source

Specs

Retrieves a message from a channel.

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

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

Examples

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

get_channel_message!(channel_id, message_id)

View Source

Specs

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

Link to this function

get_channel_messages(channel_id, limit, locator \\ {})

View Source

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

get_channel_messages!(channel_id, limit, locator \\ {})

View Source

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.

Link to this function

get_channel_webhooks(channel_id)

View Source

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.

Link to this function

get_current_user_guilds(options \\ [])

View Source

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

Examples

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

get_current_user_guilds!(options \\ [])

View Source

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.

Link to this function

get_global_application_commands(application_id \\ Me.get().id)

View Source

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

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

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

Link to this function

get_guild_application_command_permissions(application_id \\ Me.get().id, guild_id)

View Source (since 0.5.0)

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.

Link to this function

get_guild_application_commands(application_id \\ Me.get().id, guild_id)

View Source

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

Link to this function

get_guild_audit_log(guild_id, options \\ [])

View Source

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

get_guild_ban(guild_id, user_id)

View Source (since 0.5.0)

Specs

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

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

Link to this function

get_guild_bans(guild_id)

View Source

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.

Link to this function

get_guild_channels(guild_id)

View Source

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

get_guild_channels!(guild_id)

View Source

Specs

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

Link to this function

get_guild_emoji(guild_id, emoji_id)

View Source

Specs

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.

Link to this function

get_guild_emoji!(guild_id, emoji_id)

View Source

Specs

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

Link to this function

get_guild_integrations(guild_id)

View Source

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.

Link to this function

get_guild_invites(guild_id)

View Source

Specs

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

get_guild_invites!(guild_id)

View Source

Specs

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

Link to this function

get_guild_member(guild_id, user_id)

View Source

Specs

Gets a guild member.

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

Examples

Nostrum.Api.get_guild_member(4019283754613, 184937267485)
Link to this function

get_guild_member!(guild_id, user_id)

View Source

Specs

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

Link to this function

get_guild_prune_count(guild_id, days)

View Source

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

get_guild_prune_count!(guild_id, days)

View Source

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.

Link to this function

get_guild_roles(guild_id)

View Source

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

get_guild_roles!(guild_id)

View Source

Specs

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

Link to this function

get_guild_scheduled_event(guild_id, event_id)

View Source (since 0.5.0)

Specs

Get a scheduled event for a guild.

Link to this function

get_guild_scheduled_event_users(guild_id, event_id, params \\ [])

View Source (since 0.5.0)

Specs

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

get_guild_scheduled_events(guild_id)

View Source (since 0.5.0)

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.

Link to this function

get_guild_webhooks(guild_id)

View Source

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

get_guild_widget(guild_id)

View Source

Specs

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

Gets a guild embed.

Link to this function

get_invite(invite_code, options \\ [])

View Source

Specs

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

get_invite!(invite_code, options \\ [])

View Source

Specs

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

Link to this function

get_pinned_messages(channel_id)

View Source

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

get_pinned_messages!(channel_id)

View Source

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.

Link to this function

get_reactions(channel_id, message_id, emoji)

View Source

Specs

Gets all users who reacted with an emoji.

This endpoint requires the VIEW_CHANNEL and READ_MESSAGE_HISTORY permissions.

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

See create_reaction/3 for similar examples.

Link to this function

get_reactions!(channel_id, message_id, emoji)

View Source

Specs

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

Link to this function

get_thread_member(thread_id, user_id)

View Source (since 0.5.1)

Specs

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

Link to this function

get_thread_members(thread_id)

View Source (since 0.5.1)

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

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.

Link to this function

get_voice_region(guild_id)

View Source

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

Gets a webhook by id.

Parameters

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

get_webhook_with_token(webhook_id, webhook_token)

View Source

Specs

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

join_thread(thread_id)

View Source (since 0.5.1)

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.

Link to this function

leave_thread(thread_id)

View Source (since 0.5.1)

Specs

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

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

Link to this function

list_guild_emojis(guild_id)

View Source

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.

Link to this function

list_guild_emojis!(guild_id)

View Source

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.

Link to this function

list_guild_members(guild_id, options \\ %{})

View Source

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

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

View Source

Specs

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

Link to this function

list_guild_threads(guild_id)

View Source (since 0.5.1)

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

list_joined_private_archived_threads(channel_id, options \\ [])

View Source (since 0.5.1)

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.

Link to this function

list_private_archived_threads(channel_id, options \\ [])

View Source (since 0.5.1)

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.

Link to this function

list_public_archived_threads(channel_id, options \\ [])

View Source (since 0.5.1)

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.

Link to this function

modify_channel(channel_id, options, reason \\ nil)

View Source

Specs

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

Examples

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

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

modify_channel!(channel_id, options, reason \\ nil)

View Source

Specs

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

Link to this function

modify_current_user(options)

View Source

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

modify_current_user!(options)

View Source

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.

Link to this function

modify_current_user_nick(guild_id, options \\ %{})

View Source

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

modify_current_user_nick!(guild_id, options \\ %{})

View Source

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.

Link to this function

modify_guild(guild_id, options \\ [], reason \\ nil)

View Source

Specs

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

modify_guild!(guild_id, options \\ [])

View Source

Specs

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

Link to this function

modify_guild_channel_positions(guild_id, positions)

View Source

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

modify_guild_channel_positions!(guild_id, positions)

View Source

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.

Link to this function

modify_guild_emoji(guild_id, emoji_id, options \\ %{}, reason \\ nil)

View Source

Specs

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

modify_guild_emoji!(guild_id, emoji_id, options, reason \\ nil)

View Source

Specs

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

Link to this function

modify_guild_integrations(guild_id, integration_id, options)

View Source

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

modify_guild_member(guild_id, user_id, options \\ %{}, reason \\ nil)

View Source

Specs

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

modify_guild_member!(guild_id, user_id, options \\ %{}, reason \\ nil)

View Source

Specs

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

Link to this function

modify_guild_role(guild_id, role_id, options, reason \\ nil)

View Source

Specs

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

modify_guild_role!(guild_id, role_id, options, reason \\ nil)

View Source

Specs

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

Link to this function

modify_guild_role_positions(guild_id, positions, reason \\ nil)

View Source

Specs

Reorders a guild's roles.

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

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

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

Examples

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

modify_guild_role_positions!(guild_id, positions, reason \\ nil)

View Source

Specs

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

Link to this function

modify_guild_scheduled_event(guild_id, event_id, reason \\ nil, options)

View Source (since 0.5.0)

Specs

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

modify_guild_widget(guild_id, options)

View Source

Specs

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

Modifies a guild embed.

Link to this function

modify_webhook(webhook_id, args, reason \\ nil)

View Source

Specs

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

modify_webhook_with_token(webhook_id, webhook_token, args, reason \\ nil)

View Source

Specs

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

remove_guild_ban(guild_id, user_id, reason \\ nil)

View Source

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.

Link to this function

remove_guild_member(guild_id, user_id, reason \\ nil)

View Source

Specs

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

remove_guild_member!(guild_id, user_id, reason \\ nil)

View Source

Specs

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

Link to this function

remove_guild_member_role(guild_id, user_id, role_id, reason \\ nil)

View Source

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.

Link to this function

remove_thread_member(thread_id, user_id)

View Source (since 0.5.1)

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

request(method, route, body \\ "", params \\ [])

View Source

Specs

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

request_multipart(method, route, body, params \\ [])

View Source

Specs

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

start_thread(channel_id, options, reason \\ nil)

View Source (since 0.5.1)

Specs

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

start_thread_with_message(channel_id, message_id, options, reason \\ nil)

View Source (since 0.5.1)

Specs

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

start_typing(channel_id)

View Source

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.

Link to this function

start_typing!(channel_id)

View Source

Specs

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

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

Link to this function

sync_guild_integrations(guild_id, integration_id)

View Source

Specs

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

Syncs a guild integration.

Integration to sync is specified by guild_id and integeration_id.

Link to this function

update_shard_status(pid, status, game, type \\ 0, stream \\ nil)

View Source

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

update_status(status, game, type \\ 0, stream \\ nil)

View Source

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.

Link to this function

update_voice_state(guild_id, channel_id, self_mute \\ false, self_deaf \\ false)

View Source

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.