Nostrum v0.4.1 Nostrum.Api View Source
Interface for Discord's rest API.
By default all methods in this module are ran synchronously. If you wish to have async rest operations I recommend you execute these functions inside of a task.
Examples
# Async Task
t = Task.async fn ->
Nostrum.Api.get_channel_messages(12345678912345, :infinity, {})
end
messages = Task.await t
# A lot of times we don't care about the return value of the function
Task.start fn ->
messages = ["in", "the", "end", "it", "doesn't", "even", "matter"]
Enum.each messages, &Nostrum.Api.create_message!(12345678912345, &1)
end
A note about Strings and Ints
Currently, responses from the REST api will have id
fields as string
.
Everything received from the WS connection will have id
fields as int
.
If you're processing a response from the API and trying to access something in the cache
based off of an id
in the response, you will need to conver it to an int
using
String.to_integer/1
. I'm open to suggestions for how this should be handled going forward.
Example
messages = Nostrum.Api.get_pinned_messages!(12345678912345)
authors =
Enum.map messages, fn msg ->
author_id = String.to_integer(msg.author.id)
Nostrum.Cache.User.get!(id: author_id)
end
Link to this section Summary
Types
Represents an emoji for interacting with reaction endpoints.
Represents a failed response from the API.
Represents a limit used to retrieve messages.
Represents a tuple used to locate messages.
Represents optional parameters for Api functions.
Represents different statuses the bot can have.
Functions
Puts a user in a guild.
Same as add_guild_member/3
, but raises Nostrum.Error.ApiError
in case of failure.
Adds a role to a member.
Pins a message in a channel.
Same as add_pinned_channel_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
Begins a guild prune to prune members within days
.
Same as begin_guild_prune/2
, but raises Nostrum.Error.ApiError
in case of failure.
Deletes multiple messages from a channel.
Same as bulk_delete_messages/2
, but raises Nostrum.Error.ApiError
in case of failure.
Creates an invite for a guild channel.
Same as create_channel_invite/2
, but raises Nostrum.Error.ApiError
in case of failure.
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.
Same as create_group_dm/2
, but raises Nostrum.Error.ApiError
in case of failure.
Bans a user from a guild.
Creates a channel for a guild.
Same as create_guild_channel/2
, but raises Nostrum.Error.ApiError
in case of failure.
Creates a new emoji for the given guild.
Same as create_guild_emoji/2
, but raises Nostrum.Error.ApiError
in case of failure.
Creates a new guild integeration.
Creates a guild role.
Same as create_guild_role/2
, but raises Nostrum.Error.ApiError
in case of failure.
Posts a message to a guild text or DM channel.
Same as create_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
Creates a reaction for a message.
Same as create_reaction/3
, but raises Nostrum.Error.ApiError
in case of failure.
Creates a webhook.
Deletes all reactions from a message.
Same as delete_all_reactions/2
, but raises Nostrum.Error.ApiError
in case of failure.
Deletes a channel.
Same as delete_channel/1
, but raises Nostrum.Error.ApiError
in case of failure.
Delete a channel permission for a user or role.
Deletes a guild.
Same as delete_guild/1
, but raises Nostrum.Error.ApiError
in case of failure.
Deletes the given emoji.
Same as delete_guild_emoji/2
, but raises Nostrum.Error.ApiError
in case of failure.
Deletes a guild integeration.
Deletes a role from a guild.
Same as delete_guild_role/2
, but raises Nostrum.Error.ApiError
in case of failure.
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
.
Deletes a message.
Same as delete_message/1
, but raises Nostrum.Error.ApiError
in case of failure.
Same as delete_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
Deletes a reaction the current user has made for the message.
Same as delete_own_reaction/3
, but raises Nostrum.Error.ApiError
in case of failure.
Unpins a message in a channel.
Same as delete_pinned_channel_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
Deletes another user's reaction from a message.
Same as delete_user_reaction/4
, but raises Nostrum.Error.ApiError
in case of failure.
Deletes a webhook.
Edit the permission overwrites for a user or role.
Same as edit_channel_permissions/3
, but raises Nostrum.Error.ApiError
in case of failure.
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.
Same as edit_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
Same as edit_message/3
, but raises Nostrum.Error.ApiError
in case of failure.
Executes a git webhook.
Executes a slack webhook.
Executes a webhook.
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.
Same as get_channel_invites/1
, but raises Nostrum.Error.ApiError
in case of failure.
Retrieves a message from a channel.
Same as get_channel_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
Retrieves a channel's messages around a locator
up to a limit
.
Same as get_channel_messages/3
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a list of webook for a channel.
Gets info on the current user.
Same as get_current_user/0
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a list of guilds the user is currently in.
Same as get_current_user_guilds/1
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a guild.
Same as get_guild/1
, but raises Nostrum.Error.ApiError
in case of failure.
Get the Nostrum.Struct.Guild.AuditLog.t/0
for the given guild_id
.
Gets a list of users banend from a guild.
Gets a list of guild channels.
Same as get_guild_channels/1
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a guild embed.
Gets an emoji for the given guild and emoji ids.
Same as get_guild_emoji/2
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a list of guild integerations.
Gets a list of invites for a guild.
Same as get_guild_invites/1
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a guild member.
Same as get_guild_member/2
, but raises Nostrum.Error.ApiError
in case of failure.
Gets the number of members that would be removed in a prune given days
.
Same as get_guild_prune_count/2
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a guild's roles.
Same as get_guild_roles/1
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a list of webooks for a guild.
Gets an invite by its invite_code
.
Same as get_invite/1
, but raises Nostrum.Error.ApiError
in case of failure.
Retrieves all pinned messages from a channel.
Same as get_pinned_messages/1
, but raises Nostrum.Error.ApiError
in case of failure.
Gets all users who reacted with an emoji.
Same as get_reactions/3
, but raises Nostrum.Error.ApiError
in case of failure.
Returns the token of the bot.
Gets a user by its Nostrum.Struct.User.id/0
.
Same as get_user/1
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a list of user connections.
Gets a list of our user's DM channels.
Same as get_user_dms/0
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a list of voice regions for the guild.
Gets a webhook by id.
Gets a webhook by id and token.
Leaves a guild.
Gets a list of emojis for a given guild.
Same as list_guild_emojis/1
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a list of a guild's members.
Same as list_guild_members/2
, but raises Nostrum.Error.ApiError
in case of failure.
Gets a list of voice regions.
Modifies a channel's settings.
Same as modify_channel/2
, but raises Nostrum.Error.ApiError
in case of failure.
Changes the username or avatar of the current user.
Same as modify_current_user/1
, but raises Nostrum.Error.ApiError
in case of failure.
Modifies a guild's settings.
Same as modify_guild/2
, but raises Nostrum.Error.ApiError
in case of failure.
Reorders a guild's channels.
Same as modify_guild_channel_positions/2
, but raises Nostrum.Error.ApiError
in case of failure.
Modifies a guild imbed.
Modify the given emoji.
Same as modify_guild_emoji/3
, but raises Nostrum.Error.ApiError
in case of failure.
Changes the settings and behaviours for a guild integeration.
Modifies a guild member's attributes.
Same as modify_guild_member/3
, but raises Nostrum.Error.ApiError
in case of failure.
Modifies a guild role.
Same as modify_guild_role/3
, but raises Nostrum.Error.ApiError
in case of failure.
Reorders a guild's roles.
Same as modify_guild_role_positions/2
, but raises Nostrum.Error.ApiError
in case of failure.
Modifies a webhook.
Modifies a webhook with a token.
Removes a ban for a user.
Removes a member from a guild.
Same as remove_guild_member/2
, but raises Nostrum.Error.ApiError
in case of failure.
Removes a role from a member.
Triggers the typing indicator.
Same as start_typing/1
, but raises Nostrum.Error.ApiError
in case of failure.
Syncs a guild integration.
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
emoji()
View Source
emoji() :: Nostrum.Struct.Emoji.t() | Nostrum.Struct.Emoji.api_name()
emoji() :: Nostrum.Struct.Emoji.t() | Nostrum.Struct.Emoji.api_name()
Represents an emoji for interacting with reaction endpoints.
error()
View Source
error() :: {:error, Nostrum.Error.ApiError.t() | HTTPoison.Error.t()}
error() :: {:error, Nostrum.Error.ApiError.t() | HTTPoison.Error.t()}
Represents a failed response from the API.
This occurs when hackney or HTTPoison fail, or when the API doesn't respond with 200
or 204
.
limit()
View Source
limit() :: integer() | :infinity
limit() :: integer() | :infinity
Represents a limit used to retrieve messages.
Integer number of messages, or :infinity to retrieve all messages.
locator() View Source
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
options() View Source
Represents optional parameters for Api functions.
Each function has documentation regarding what parameters it supports or needs.
status()
View Source
status() :: :dnd | :idle | :online | :invisible
status() :: :dnd | :idle | :online | :invisible
Represents different statuses the bot can have.
:dnd
- Red circle.:idle
- Yellow circle.:online
- Green circle.:invisible
- The bot will appear offline.
Link to this section Functions
add_guild_member(guild_id, user_id, options)
View Source
add_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), options()) ::
error() | {:ok, Nostrum.Struct.Guild.Member.t()} | {:ok}
add_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), options()) :: error() | {:ok, Nostrum.Struct.Guild.Member.t()} | {:ok}
Puts a user in a guild.
This endpoint fires the Nostrum.Consumer.guild_member_add/0
event.
It requires the CREATE_INSTANT_INVITE
permission. Additionally, it
situationally requires the MANAGE_NICKNAMES
, MANAGE_ROLES
,
MUTE_MEMBERS
, and DEAFEN_MEMBERS
permissions.
If successful, returns {:ok, member}
or {:ok}
if the user was already a member of the
guild. Otherwise, returns a Nostrum.Api.error/0
.
Options
:access_token
(string) - the user's oauth2 access token:nick
(string) - value to set users nickname to:roles
(list ofNostrum.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]
)
add_guild_member!(guild_id, user_id, options)
View Source
add_guild_member!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.User.id(),
options()
) :: no_return() | Nostrum.Struct.Guild.Member.t() | {:ok}
add_guild_member!( Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), options() ) :: no_return() | Nostrum.Struct.Guild.Member.t() | {:ok}
Same as add_guild_member/3
, but raises Nostrum.Error.ApiError
in case of failure.
add_guild_member_role(guild_id, user_id, role_id, reason \\ nil)
View Source
add_guild_member_role(
integer(),
integer(),
integer(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
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.
add_pinned_channel_message(channel_id, message_id)
View Source
add_pinned_channel_message(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id()
) :: error() | {:ok}
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)
add_pinned_channel_message!(channel_id, message_id)
View Source
add_pinned_channel_message!(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id()
) :: no_return() | {:ok}
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.
begin_guild_prune(guild_id, days, reason \\ nil)
View Source
begin_guild_prune(
Nostrum.Struct.Guild.id(),
1..30,
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, %{pruned: integer()}}
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}}
begin_guild_prune!(guild_id, days, reason)
View Source
begin_guild_prune!(
Nostrum.Struct.Guild.id(),
1..30,
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | %{pruned: integer()}
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.
bulk_delete_messages(channel_id, messages, filter \\ true)
View Source
bulk_delete_messages(integer(), [Nostrum.Struct.Message.id()], boolean()) ::
error() | {:ok}
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
.
bulk_delete_messages!(channel_id, messages, filter \\ true)
View Source
bulk_delete_messages!(integer(), [Nostrum.Struct.Message.id()], boolean()) ::
no_return() | {:ok}
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.
create_channel_invite(channel_id, options \\ [], reason \\ nil)
View Source
create_channel_invite(
Nostrum.Struct.Channel.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Invite.detailed_invite()}
create_channel_invite( Nostrum.Struct.Channel.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Invite.detailed_invite()}
Creates an invite for a guild channel.
An optional reason
can be provided for the audit log.
This endpoint requires the CREATE_INSTANT_INVITE
permission.
If successful, returns {:ok, invite}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:max_age
(integer) - duration of invite in seconds before expiry, or 0 for never. (default:86400
):max_uses
(integer) - max number of uses or 0 for unlimited. (default:0
):temporary
(boolean) - Whether the invite should grant temporary membership. (default:false
):unique
(boolean) - used when creating unique one time use invites. (default:false
)
Examples
Nostrum.Api.create_channel_invite(41771983423143933)
{:ok, Nostrum.Struct.Invite{}}
Nostrum.Api.create_channel_invite(41771983423143933, max_uses: 20)
{:ok, %Nostrum.Struct.Invite{}}
create_channel_invite!(channel_id, options \\ [], reason \\ nil)
View Source
create_channel_invite!(
Nostrum.Struct.Channel.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Invite.detailed_invite()
create_channel_invite!( Nostrum.Struct.Channel.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | Nostrum.Struct.Invite.detailed_invite()
Same as create_channel_invite/2
, but raises Nostrum.Error.ApiError
in case of failure.
create_dm(user_id)
View Source
create_dm(Nostrum.Struct.User.id()) ::
error() | {:ok, Nostrum.Struct.Channel.dm_channel()}
create_dm(Nostrum.Struct.User.id()) :: error() | {:ok, Nostrum.Struct.Channel.dm_channel()}
Create a new DM channel with a user.
If successful, returns {:ok, dm_channel}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.create_dm(150061853001777154)
{:ok, %Nostrum.Struct.Channel{type: 1}}
create_dm!(user_id)
View Source
create_dm!(Nostrum.Struct.User.id()) ::
no_return() | Nostrum.Struct.Channel.dm_channel()
create_dm!(Nostrum.Struct.User.id()) :: no_return() | Nostrum.Struct.Channel.dm_channel()
Same as create_dm/1
, but raises Nostrum.Error.ApiError
in case of failure.
create_group_dm(access_tokens, nicks)
View Source
create_group_dm([String.t()], %{
optional(Nostrum.Struct.User.id()) => String.t()
}) :: error() | {:ok, Nostrum.Struct.Channel.group_dm_channel()}
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}}
create_group_dm!(access_tokens, nicks)
View Source
create_group_dm!([String.t()], %{
optional(Nostrum.Struct.User.id()) => String.t()
}) :: no_return() | Nostrum.Struct.Channel.group_dm_channel()
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.
create_guild_ban(guild_id, user_id, days_to_delete, reason \\ nil)
View Source
create_guild_ban(
integer(),
integer(),
integer(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
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.
create_guild_channel(guild_id, options)
View Source
create_guild_channel(Nostrum.Struct.Guild.id(), options()) ::
error() | {:ok, Nostrum.Struct.Channel.guild_channel()}
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 (SeeNostrum.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 ofNostrum.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}}
create_guild_channel!(guild_id, options)
View Source
create_guild_channel!(Nostrum.Struct.Guild.id(), options()) ::
no_return() | Nostrum.Struct.Channel.guild_channel()
create_guild_channel!(Nostrum.Struct.Guild.id(), options()) :: no_return() | Nostrum.Struct.Channel.guild_channel()
Same as create_guild_channel/2
, but raises Nostrum.Error.ApiError
in case of failure.
create_guild_emoji(guild_id, options, reason \\ nil)
View Source
create_guild_emoji(
Nostrum.Struct.Guild.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Emoji.t()}
create_guild_emoji( Nostrum.Struct.Guild.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Emoji.t()}
Creates a new emoji for the given guild.
This endpoint requires the MANAGE_EMOJIS
permission. It fires a
Nostrum.Consumer.guild_emojis_update/0
event.
An optional reason
can be provided for the audit log.
If successful, returns {:ok, emoji}
. Otherwise, returns Nostrum.Api.error/0
.
Options
:name
(string) - name of the emoji:image
(base64 data URI) - the 128x128 emoji image. Maximum size of 256kb:roles
(list ofNostrum.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: [])
create_guild_emoji!(guild_id, params, reason \\ nil)
View Source
create_guild_emoji!(
Nostrum.Struct.Guild.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Emoji.t()
create_guild_emoji!( Nostrum.Struct.Guild.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | Nostrum.Struct.Emoji.t()
Same as create_guild_emoji/2
, but raises Nostrum.Error.ApiError
in case of failure.
create_guild_integrations(guild_id, options) View Source
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.
create_guild_role(guild_id, options, reason \\ nil)
View Source
create_guild_role(
Nostrum.Struct.Guild.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Guild.Role.t()}
create_guild_role( Nostrum.Struct.Guild.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Guild.Role.t()}
Creates a guild role.
An optional reason for the audit log can be provided via reason
.
This endpoint requires the MANAGE_ROLES
permission. It fires a
Nostrum.Consumer.guild_role_create/0
event.
If successful, returns {:ok, role}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:name
(string) - name of the role (default: "new role"):permissions
(integer) - bitwise of the enabled/disabled permissions (default: @everyone perms):color
(integer) - RGB color value (default: 0):hoist
(boolean) - whether the role should be displayed separately in the sidebar (default: false):mentionable
(boolean) - whether the role should be mentionable (default: false)
Examples
Nostrum.Api.create_guild_role(41771983423143937, name: "nostrum-club", hoist: true)
create_guild_role!(guild_id, options, reason \\ nil)
View Source
create_guild_role!(
Nostrum.Struct.Guild.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Guild.Role.t()
create_guild_role!( Nostrum.Struct.Guild.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | Nostrum.Struct.Guild.Role.t()
Same as create_guild_role/2
, but raises Nostrum.Error.ApiError
in case of failure.
create_message(channel_id, options)
View Source
create_message(
Nostrum.Struct.Channel.id() | Nostrum.Struct.Message.t(),
options() | String.t()
) :: error() | {:ok, Nostrum.Struct.Message.t()}
create_message( Nostrum.Struct.Channel.id() | Nostrum.Struct.Message.t(), options() | String.t() ) :: error() | {:ok, Nostrum.Struct.Message.t()}
Posts a message to a guild text or DM channel.
This endpoint requires the VIEW_CHANNEL
and SEND_MESSAGES
permissions. It
may situationally need the SEND_MESSAGES_TTS
permission. It fires the
Nostrum.Consumer.message_create/0
event.
If options
is a string, options
will be used as the message's content.
If successful, returns {:ok, message}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:content
(string) - the message contents (up to 2000 characters):nonce
(Nostrum.Snowflake.t/0
) - a nonce that can be used for optimistic message sending:tts
(boolean) - true if this is a TTS message:file
(Path.t/0
| map) - the path of the file being sent, or a map with the following keys if sending a binary from memory:name
(string) - the name of the file:body
(string) - binary you wish to send
:embed
(Nostrum.Struct.Embed.t/0
) - embedded rich contentAt least one of the following is required:
:content
,:file
,:embed
.
Examples
Nostrum.Api.create_message(43189401384091, content: "hello world!")
Nostrum.Api.create_message(43189401384091, "hello world!")
import Nostrum.Struct.Embed
embed =
%Nostrum.Struct.Embed{}
|> put_title("embed")
|> put_description("new desc")
Nostrum.Api.create_message(43189401384091, embed: embed)
Nostrum.Api.create_message(43189401384091, file: "/path/to/file.txt")
Nostrum.Api.create_message(43189401384091, content: "hello world!", embed: embed, file: "/path/to/file.txt")
create_message!(channel_id, options)
View Source
create_message!(
Nostrum.Struct.Channel.id() | Nostrum.Struct.Message.t(),
options()
) :: no_return() | Nostrum.Struct.Message.t()
create_message!( Nostrum.Struct.Channel.id() | Nostrum.Struct.Message.t(), options() ) :: no_return() | Nostrum.Struct.Message.t()
Same as create_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
create_reaction(channel_id, message_id, emoji)
View Source
create_reaction(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
emoji()
) :: error() | {:ok}
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
.
create_reaction!(channel_id, message_id, emoji)
View Source
create_reaction!(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
emoji()
) :: no_return() | {:ok}
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.
create_webhook(channel_id, args, reason \\ nil)
View Source
create_webhook(
Nostrum.Struct.Channel.id(),
%{name: String.t(), avatar: String.t()},
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
create_webhook( Nostrum.Struct.Channel.id(), %{name: String.t(), avatar: String.t()}, Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
Creates a webhook.
Parameters
channel_id
- Id of the channel to send the message to.args
- Map with the following required keys:name
- Name of the webhook.avatar
- Base64 128x128 jpeg image for the default avatar.
reason
- An optional reason for the guild audit log.
delete_all_reactions(channel_id, message_id)
View Source
delete_all_reactions(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
error() | {:ok}
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
.
delete_all_reactions!(channel_id, message_id)
View Source
delete_all_reactions!(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
no_return() | {:ok}
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.
delete_channel(channel_id, reason \\ nil)
View Source
delete_channel(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Channel.t()}
delete_channel( Nostrum.Struct.Channel.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Channel.t()}
Deletes a channel.
An optional reason
can be provided for the guild audit log.
If deleting a Nostrum.Struct.Channel.guild_channel/0
, this endpoint requires
the MANAGE_CHANNELS
permission. It fires a
Nostrum.Consumer.channel_delete/0
. If a Nostrum.Struct.Channel.channel_category/0
is deleted, then a Nostrum.Consumer.channel_update/0
event will fire
for each channel under the category.
If successful, returns {:ok, channel}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.delete_channel(421533712753360896)
{:ok, %Nostrum.Struct.Channel{id: 421533712753360896}}
delete_channel!(channel_id, reason \\ nil)
View Source
delete_channel!(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Channel.t()
delete_channel!( Nostrum.Struct.Channel.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | Nostrum.Struct.Channel.t()
Same as delete_channel/1
, but raises Nostrum.Error.ApiError
in case of failure.
delete_channel_permissions(channel_id, overwrite_id, reason \\ nil)
View Source
delete_channel_permissions(
integer(),
integer(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
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.
delete_guild(guild_id)
View Source
delete_guild(Nostrum.Struct.Guild.id()) :: error() | {:ok}
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}
delete_guild!(guild_id)
View Source
delete_guild!(Nostrum.Struct.Guild.id()) :: no_return() | {:ok}
delete_guild!(Nostrum.Struct.Guild.id()) :: no_return() | {:ok}
Same as delete_guild/1
, but raises Nostrum.Error.ApiError
in case of failure.
delete_guild_emoji(guild_id, emoji_id, reason \\ nil)
View Source
delete_guild_emoji(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Emoji.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
delete_guild_emoji( Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok}
Deletes the given emoji.
An optional reason
can be provided for the audit log.
This endpoint requires the MANAGE_EMOJIS
permission. It fires a
Nostrum.Consumer.guild_emojis_update/0
event.
If successful, returns {:ok}
. Otherwise, returns Nostrum.Api.error/0
.
delete_guild_emoji!(guild_id, emoji_id, reason \\ nil)
View Source
delete_guild_emoji!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Emoji.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | {:ok}
delete_guild_emoji!( Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | {:ok}
Same as delete_guild_emoji/2
, but raises Nostrum.Error.ApiError
in case of failure.
delete_guild_integrations(guild_id, integration_id) View Source
Deletes a guild integeration.
Integration to delete is specified by guild_id
and integeration_id
.
delete_guild_role(guild_id, role_id, reason \\ nil)
View Source
delete_guild_role(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Guild.Role.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
delete_guild_role( Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok}
Deletes a role from a guild.
An optional reason
can be specified for the audit log.
This endpoint requires the MANAGE_ROLES
permission. It fires a
Nostrum.Consumer.guild_role_delete/0
event.
If successful, returns {:ok}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.delete_guild_role(41771983423143937, 392817238471936)
delete_guild_role!(guild_id, role_id, reason \\ nil)
View Source
delete_guild_role!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Guild.Role.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | {:ok}
delete_guild_role!( Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | {:ok}
Same as delete_guild_role/2
, but raises Nostrum.Error.ApiError
in case of failure.
delete_invite(invite_code)
View Source
delete_invite(Nostrum.Struct.Invite.code()) ::
error() | {:ok, Nostrum.Struct.Invite.simple_invite()}
delete_invite(Nostrum.Struct.Invite.code()) :: error() | {:ok, Nostrum.Struct.Invite.simple_invite()}
Deletes an invite by its invite_code
.
This endpoint requires the MANAGE_CHANNELS
permission.
If successful, returns {:ok, invite}
. Otherwise, returns a
Nostrum.Api.error/0
.
Examples
Nostrum.Api.delete_invite("zsjUsC")
{:ok, %Nostrum.Struct.Invite{code: "zsjUsC"}}
delete_invite!(invite_code)
View Source
delete_invite!(Nostrum.Struct.Invite.code()) ::
no_return() | Nostrum.Struct.Invite.simple_invite()
delete_invite!(Nostrum.Struct.Invite.code()) :: no_return() | Nostrum.Struct.Invite.simple_invite()
Same as delete_invite/1
, but raises Nostrum.Error.ApiError
in case of failure.
delete_message(message)
View Source
delete_message(Nostrum.Struct.Message.t()) :: error() | {:ok}
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
.
delete_message(channel_id, message_id)
View Source
delete_message(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
error() | {:ok}
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)
delete_message!(message)
View Source
delete_message!(Nostrum.Struct.Message.t()) :: error() | {:ok}
delete_message!(Nostrum.Struct.Message.t()) :: error() | {:ok}
Same as delete_message/1
, but raises Nostrum.Error.ApiError
in case of failure.
delete_message!(channel_id, message_id)
View Source
delete_message!(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
no_return() | {:ok}
delete_message!(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) :: no_return() | {:ok}
Same as delete_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
delete_own_reaction(channel_id, message_id, emoji)
View Source
delete_own_reaction(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
emoji()
) :: error() | {:ok}
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.
delete_own_reaction!(channel_id, message_id, emoji)
View Source
delete_own_reaction!(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
emoji()
) :: no_return() | {:ok}
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.
delete_pinned_channel_message(channel_id, message_id)
View Source
delete_pinned_channel_message(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id()
) :: error() | {:ok}
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.
delete_pinned_channel_message!(channel_id, message_id)
View Source
delete_pinned_channel_message!(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id()
) :: no_return() | {:ok}
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.
delete_user_reaction(channel_id, message_id, emoji, user_id)
View Source
delete_user_reaction(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
emoji(),
Nostrum.Struct.User.id()
) :: error() | {:ok}
delete_user_reaction( Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id(), emoji(), Nostrum.Struct.User.id() ) :: error() | {:ok}
Deletes another user's reaction from a message.
This endpoint requires the VIEW_CHANNEL
, READ_MESSAGE_HISTORY
, and
MANAGE_MESSAGES
permissions. It fires a Nostrum.Consumer.message_reaction_remove/0
event.
If successful, returns {:ok}
. Otherwise, returns Nostrum.Api.error/0
.
See create_reaction/3
for similar examples.
delete_user_reaction!(channel_id, message_id, emoji, user_id)
View Source
delete_user_reaction!(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
emoji(),
Nostrum.Struct.User.id()
) :: no_return() | {:ok}
delete_user_reaction!( Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id(), emoji(), Nostrum.Struct.User.id() ) :: no_return() | {:ok}
Same as delete_user_reaction/4
, but raises Nostrum.Error.ApiError
in case of failure.
delete_webhook(webhook_id, reason \\ nil)
View Source
delete_webhook(
Nostrum.Struct.Webhook.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
delete_webhook( Nostrum.Struct.Webhook.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok}
Deletes a webhook.
Parameters
webhook_id
- Id of webhook to delete.reason
- An optional reason for the guild audit log.
edit_channel_permissions(channel_id, overwrite_id, permission_info, reason \\ nil) View Source
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.
edit_channel_permissions!(channel_id, overwrite_id, permission_info, reason \\ nil) View Source
Same as edit_channel_permissions/3
, but raises Nostrum.Error.ApiError
in case of failure.
edit_message(message, options)
View Source
edit_message(Nostrum.Struct.Message.t(), options()) ::
error() | {:ok, Nostrum.Struct.Message.t()}
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
.
edit_message(channel_id, message_id, options)
View Source
edit_message(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
options() | String.t()
) :: error() | {:ok, Nostrum.Struct.Message.t()}
edit_message( Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id(), options() | String.t() ) :: error() | {:ok, Nostrum.Struct.Message.t()}
Edits a previously sent message in a channel.
This endpoint requires the VIEW_CHANNEL
permission. It fires the
Nostrum.Consumer.message_update/0
event.
If options
is a string, options
will be used as the message's content.
If successful, returns {:ok, message}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:content
(string) - the message contents (up to 2000 characters):embed
(Nostrum.Struct.Embed.t/0
) - embedded rich content
Examples
Nostrum.Api.edit_message(43189401384091, 1894013840914098, content: "hello world!")
Nostrum.Api.edit_message(43189401384091, 1894013840914098, "hello world!")
import Nostrum.Struct.Embed
embed =
%Nostrum.Struct.Embed{}
|> put_title("embed")
|> put_description("new desc")
Nostrum.Api.edit_message(43189401384091, 1894013840914098, embed: embed)
Nostrum.Api.edit_message(43189401384091, 1894013840914098, content: "hello world!", embed: embed)
edit_message!(message, options)
View Source
edit_message!(Nostrum.Struct.Message.t(), options()) ::
no_return() | Nostrum.Struct.Message.t()
edit_message!(Nostrum.Struct.Message.t(), options()) :: no_return() | Nostrum.Struct.Message.t()
Same as edit_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
edit_message!(channel_id, message_id, options)
View Source
edit_message!(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
options()
) :: no_return() | Nostrum.Struct.Message.t()
edit_message!( Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id(), options() ) :: no_return() | Nostrum.Struct.Message.t()
Same as edit_message/3
, but raises Nostrum.Error.ApiError
in case of failure.
execute_git_webhook(webhook_id, webhook_token, wait \\ false)
View Source
execute_git_webhook(
Nostrum.Struct.Webhook.id(),
Nostrum.Struct.Webhook.token(),
boolean()
) :: error() | {:ok}
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.
execute_slack_webhook(webhook_id, webhook_token, wait \\ false)
View Source
execute_slack_webhook(
Nostrum.Struct.Webhook.id(),
Nostrum.Struct.Webhook.token(),
boolean()
) :: error() | {:ok}
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.
execute_webhook(webhook_id, webhook_token, args, wait \\ false)
View Source
execute_webhook(
Nostrum.Struct.Webhook.id(),
Nostrum.Struct.Webhook.token(),
%{
content: String.t(),
username: String.t(),
avatar_url: String.t(),
tts: boolean(),
file: String.t(),
embeds: [Nostrum.Struct.Embed.t()]
},
boolean()
) :: error() | {:ok}
execute_webhook( Nostrum.Struct.Webhook.id(), Nostrum.Struct.Webhook.token(), %{ content: String.t(), username: String.t(), avatar_url: String.t(), tts: boolean(), file: String.t(), embeds: [Nostrum.Struct.Embed.t()] }, boolean() ) :: error() | {:ok}
Executes a webhook.
Parameters
webhook_id
- Id of the webhook to execute.webhook_token
- Token of the webhook to execute.args
- Map with the following required keys:content
- Message content.file
- File 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.
wait
- Whether to return an error or not. Defaults tofalse
.
Only one of content
, file
or embeds
should be supplied in the args
parameter.
get_application_information() View Source
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"
},
}}
get_channel(channel_id)
View Source
get_channel(Nostrum.Struct.Channel.id()) ::
error() | {:ok, Nostrum.Struct.Channel.t()}
get_channel(Nostrum.Struct.Channel.id()) :: error() | {:ok, Nostrum.Struct.Channel.t()}
Gets a channel.
If successful, returns {:ok, channel}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.get_channel(381889573426429952)
{:ok, %Nostrum.Struct.Channel{id: 381889573426429952}}
get_channel!(channel_id)
View Source
get_channel!(Nostrum.Struct.Channel.id()) ::
no_return() | Nostrum.Struct.Channel.t()
get_channel!(Nostrum.Struct.Channel.id()) :: no_return() | Nostrum.Struct.Channel.t()
Same as get_channel/1
, but raises Nostrum.Error.ApiError
in case of failure.
get_channel_invites(channel_id)
View Source
get_channel_invites(Nostrum.Struct.Channel.id()) ::
error() | {:ok, [Nostrum.Struct.Invite.detailed_invite()]}
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{} | _]}
get_channel_invites!(channel_id)
View Source
get_channel_invites!(Nostrum.Struct.Channel.id()) ::
no_return() | [Nostrum.Struct.Invite.detailed_invite()]
get_channel_invites!(Nostrum.Struct.Channel.id()) :: no_return() | [Nostrum.Struct.Invite.detailed_invite()]
Same as get_channel_invites/1
, but raises Nostrum.Error.ApiError
in case of failure.
get_channel_message(channel_id, message_id)
View Source
get_channel_message(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
error() | {:ok, Nostrum.Struct.Message.t()}
get_channel_message(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) :: error() | {:ok, Nostrum.Struct.Message.t()}
Retrieves a message from a channel.
This endpoint requires the 'VIEW_CHANNEL' and 'READ_MESSAGE_HISTORY' permissions.
If successful, returns {:ok, message}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.get_channel_message(43189401384091, 198238475613443)
get_channel_message!(channel_id, message_id)
View Source
get_channel_message!(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
no_return() | Nostrum.Struct.Message.t()
get_channel_message!(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) :: no_return() | Nostrum.Struct.Message.t()
Same as get_channel_message/2
, but raises Nostrum.Error.ApiError
in case of failure.
get_channel_messages(channel_id, limit, locator \\ {})
View Source
get_channel_messages(Nostrum.Struct.Channel.id(), limit(), locator()) ::
error() | {:ok, [Nostrum.Struct.Message.t()]}
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})
get_channel_messages!(channel_id, limit, locator \\ {})
View Source
get_channel_messages!(Nostrum.Struct.Channel.id(), limit(), locator()) ::
no_return() | [Nostrum.Struct.Message.t()]
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.
get_channel_webhooks(channel_id)
View Source
get_channel_webhooks(Nostrum.Struct.Channel.id()) ::
error() | {:ok, [Nostrum.Struct.Webhook.t()]}
get_channel_webhooks(Nostrum.Struct.Channel.id()) :: error() | {:ok, [Nostrum.Struct.Webhook.t()]}
Gets a list of webook for a channel.
Parameters
channel_id
- Channel to get webhooks for.
get_current_user()
View Source
get_current_user() :: error() | {:ok, Nostrum.Struct.User.t()}
get_current_user() :: error() | {:ok, Nostrum.Struct.User.t()}
Gets info on the current user.
If nostrum's caching is enabled, it is recommended to use Nostrum.Cache.Me.get/0
instead of this function. This is because sending out an API request is much slower
than pulling from our cache.
If the request is successful, this function returns {:ok, user}
, where
user
is nostrum's Nostrum.Struct.User
. Otherwise, returns {:error, reason}
.
get_current_user!()
View Source
get_current_user!() :: no_return() | Nostrum.Struct.User.t()
get_current_user!() :: no_return() | Nostrum.Struct.User.t()
Same as get_current_user/0
, but raises Nostrum.Error.ApiError
in case of failure.
get_current_user_guilds(options \\ [])
View Source
get_current_user_guilds(options()) ::
error() | {:ok, [Nostrum.Struct.Guild.user_guild()]}
get_current_user_guilds(options()) :: error() | {:ok, [Nostrum.Struct.Guild.user_guild()]}
Gets a list of guilds the user is currently in.
This endpoint requires the guilds
OAuth2 scope.
If successful, returns {:ok, guilds}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:before
(Nostrum.Snowflake.t/0
) - get guilds before this guild ID:after
(Nostrum.Snowflake.t/0
) - get guilds after this guild ID:limit
(integer) - max number of guilds to return (1-100)
Examples
iex> Nostrum.Api.get_current_user_guilds(limit: 1)
{:ok, [%Nostrum.Struct.Guild{}]}
get_current_user_guilds!(options \\ [])
View Source
get_current_user_guilds!(options()) ::
no_return() | [Nostrum.Struct.Guild.user_guild()]
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.
get_guild(guild_id)
View Source
get_guild(Nostrum.Struct.Guild.id()) ::
error() | {:ok, Nostrum.Struct.Guild.rest_guild()}
get_guild(Nostrum.Struct.Guild.id()) :: error() | {:ok, Nostrum.Struct.Guild.rest_guild()}
Gets a guild.
If successful, returns {:ok, guild}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.get_guild(81384788765712384)
{:ok, %Nostrum.Struct.Guild{id: 81384788765712384}}
get_guild!(guild_id)
View Source
get_guild!(Nostrum.Struct.Guild.id()) ::
no_return() | Nostrum.Struct.Guild.rest_guild()
get_guild!(Nostrum.Struct.Guild.id()) :: no_return() | Nostrum.Struct.Guild.rest_guild()
Same as get_guild/1
, but raises Nostrum.Error.ApiError
in case of failure.
get_guild_audit_log(guild_id, options \\ [])
View Source
get_guild_audit_log(Nostrum.Struct.Guild.id(), options()) ::
{:ok, Nostrum.Struct.Guild.AuditLog.t()} | error()
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.t/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
(t:positive_integer/0
) - how many entries are returned (default 50, minimum 1, maximum 100)
get_guild_bans(guild_id)
View Source
get_guild_bans(integer()) :: error() | {:ok, [Nostrum.Struct.User.t()]}
get_guild_bans(integer()) :: error() | {:ok, [Nostrum.Struct.User.t()]}
Gets a list of users banend from a guild.
Guild to get bans for is specified by guild_id
.
get_guild_channels(guild_id)
View Source
get_guild_channels(Nostrum.Struct.Guild.id()) ::
error() | {:ok, [Nostrum.Struct.Channel.guild_channel()]}
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} | _]}
get_guild_channels!(guild_id)
View Source
get_guild_channels!(Nostrum.Struct.Guild.id()) ::
no_return() | [Nostrum.Struct.Channel.guild_channel()]
get_guild_channels!(Nostrum.Struct.Guild.id()) :: no_return() | [Nostrum.Struct.Channel.guild_channel()]
Same as get_guild_channels/1
, but raises Nostrum.Error.ApiError
in case of failure.
get_guild_embed(guild_id) View Source
Gets a guild embed.
get_guild_emoji(guild_id, emoji_id)
View Source
get_guild_emoji(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
error() | {:ok, Nostrum.Struct.Emoji.t()}
get_guild_emoji(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) :: error() | {:ok, Nostrum.Struct.Emoji.t()}
Gets an emoji for the given guild and emoji ids.
This endpoint requires the MANAGE_EMOJIS
permission.
If successful, returns {:ok, emoji}
. Otherwise, returns Nostrum.Api.error/0
.
get_guild_emoji!(guild_id, emoji_id)
View Source
get_guild_emoji!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
no_return() | Nostrum.Struct.Emoji.t()
get_guild_emoji!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) :: no_return() | Nostrum.Struct.Emoji.t()
Same as get_guild_emoji/2
, but raises Nostrum.Error.ApiError
in case of failure.
get_guild_integrations(guild_id)
View Source
get_guild_integrations(integer()) ::
error() | {:ok, [Nostrum.Struct.Guild.Integration.t()]}
get_guild_integrations(integer()) :: error() | {:ok, [Nostrum.Struct.Guild.Integration.t()]}
Gets a list of guild integerations.
Guild to get integrations for is specified by guild_id
.
get_guild_invites(guild_id)
View Source
get_guild_invites(Nostrum.Struct.Guild.id()) ::
error() | {:ok, [Nostrum.Struct.Invite.detailed_invite()]}
get_guild_invites(Nostrum.Struct.Guild.id()) :: error() | {:ok, [Nostrum.Struct.Invite.detailed_invite()]}
Gets a list of invites for a guild.
This endpoint requires the MANAGE_GUILD
permission.
If successful, returns {:ok, invites}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.get_guild_invites(81384788765712384)
{:ok, [%Nostrum.Struct.Invite{} | _]}
get_guild_invites!(guild_id)
View Source
get_guild_invites!(Nostrum.Struct.Guild.id()) ::
no_return() | [Nostrum.Struct.Invite.detailed_invite()]
get_guild_invites!(Nostrum.Struct.Guild.id()) :: no_return() | [Nostrum.Struct.Invite.detailed_invite()]
Same as get_guild_invites/1
, but raises Nostrum.Error.ApiError
in case of failure.
get_guild_member(guild_id, user_id)
View Source
get_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
error() | {:ok, Nostrum.Struct.Guild.Member.t()}
get_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) :: error() | {:ok, Nostrum.Struct.Guild.Member.t()}
Gets a guild member.
If successful, returns {:ok, member}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.get_guild_member(4019283754613, 184937267485)
get_guild_member!(guild_id, user_id)
View Source
get_guild_member!(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
no_return() | Nostrum.Struct.Guild.Member.t()
get_guild_member!(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) :: no_return() | Nostrum.Struct.Guild.Member.t()
Same as get_guild_member/2
, but raises Nostrum.Error.ApiError
in case of failure.
get_guild_prune_count(guild_id, days)
View Source
get_guild_prune_count(Nostrum.Struct.Guild.id(), 1..30) ::
error() | {:ok, %{pruned: integer()}}
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}}
get_guild_prune_count!(guild_id, days)
View Source
get_guild_prune_count!(Nostrum.Struct.Guild.id(), 1..30) ::
no_return() | %{pruned: integer()}
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.
get_guild_roles(guild_id)
View Source
get_guild_roles(Nostrum.Struct.Guild.id()) ::
error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}
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)
get_guild_roles!(guild_id)
View Source
get_guild_roles!(Nostrum.Struct.Guild.id()) ::
no_return() | [Nostrum.Struct.Guild.Role.t()]
get_guild_roles!(Nostrum.Struct.Guild.id()) :: no_return() | [Nostrum.Struct.Guild.Role.t()]
Same as get_guild_roles/1
, but raises Nostrum.Error.ApiError
in case of failure.
get_guild_webhooks(guild_id)
View Source
get_guild_webhooks(Nostrum.Struct.Guild.id()) ::
error() | {:ok, [Nostrum.Struct.Webhook.t()]}
get_guild_webhooks(Nostrum.Struct.Guild.id()) :: error() | {:ok, [Nostrum.Struct.Webhook.t()]}
Gets a list of webooks for a guild.
Parameters
guild_id
- Guild to get webhooks for.
get_invite(invite_code)
View Source
get_invite(Nostrum.Struct.Invite.code()) ::
error() | {:ok, Nostrum.Struct.Invite.simple_invite()}
get_invite(Nostrum.Struct.Invite.code()) :: error() | {:ok, Nostrum.Struct.Invite.simple_invite()}
Gets an invite by its invite_code
.
If successful, returns {:ok, invite}
. Otherwise, returns a
Nostrum.Api.error/0
.
Examples
Nostrum.Api.get_invite("zsjUsC")
{:ok, %Nostrum.Struct.Invite{code: "zsjUsC"}}
get_invite!(invite_code)
View Source
get_invite!(Nostrum.Struct.Invite.code()) ::
no_return() | Nostrum.Struct.Invite.simple_invite()
get_invite!(Nostrum.Struct.Invite.code()) :: no_return() | Nostrum.Struct.Invite.simple_invite()
Same as get_invite/1
, but raises Nostrum.Error.ApiError
in case of failure.
get_pinned_messages(channel_id)
View Source
get_pinned_messages(Nostrum.Struct.Channel.id()) ::
error() | {:ok, [Nostrum.Struct.Message.t()]}
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)
get_pinned_messages!(channel_id)
View Source
get_pinned_messages!(Nostrum.Struct.Channel.id()) ::
no_return() | [Nostrum.Struct.Message.t()]
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.
get_reactions(channel_id, message_id, emoji)
View Source
get_reactions(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id(), emoji()) ::
error() | {:ok, [Nostrum.Struct.User.t()]}
get_reactions(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id(), emoji()) :: error() | {:ok, [Nostrum.Struct.User.t()]}
Gets all users who reacted with an emoji.
This endpoint requires the VIEW_CHANNEL
and READ_MESSAGE_HISTORY
permissions.
If successful, returns {:ok, users}
. Otherwise, returns Nostrum.Api.error/0
.
See create_reaction/3
for similar examples.
get_reactions!(channel_id, message_id, emoji)
View Source
get_reactions!(
Nostrum.Struct.Channel.id(),
Nostrum.Struct.Message.id(),
emoji()
) :: no_return() | [Nostrum.Struct.User.t()]
get_reactions!( Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id(), emoji() ) :: no_return() | [Nostrum.Struct.User.t()]
Same as get_reactions/3
, but raises Nostrum.Error.ApiError
in case of failure.
get_token()
View Source
get_token() :: String.t()
get_token() :: String.t()
Returns the token of the bot.
get_user(user_id)
View Source
get_user(Nostrum.Struct.User.id()) :: error() | {:ok, Nostrum.Struct.User.t()}
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}
.
get_user!(user_id)
View Source
get_user!(Nostrum.Struct.User.id()) :: no_return() | Nostrum.Struct.User.t()
get_user!(Nostrum.Struct.User.id()) :: no_return() | Nostrum.Struct.User.t()
Same as get_user/1
, but raises Nostrum.Error.ApiError
in case of failure.
get_user_connections()
View Source
get_user_connections() :: error() | {:ok, Nostrum.Struct.User.Connection.t()}
get_user_connections() :: error() | {:ok, Nostrum.Struct.User.Connection.t()}
Gets a list of user connections.
get_user_dms()
View Source
get_user_dms() :: error() | {:ok, [Nostrum.Struct.Channel.dm_channel()]}
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} | _]}
get_user_dms!()
View Source
get_user_dms!() :: no_return() | [Nostrum.Struct.Channel.dm_channel()]
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.
get_voice_region(guild_id)
View Source
get_voice_region(integer()) :: error() | {:ok, [Nostrum.Struct.VoiceRegion.t()]}
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
.
get_webhook(webhook_id)
View Source
get_webhook(Nostrum.Struct.Webhook.id()) ::
error() | {:ok, Nostrum.Struct.Webhook.t()}
get_webhook(Nostrum.Struct.Webhook.id()) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
Gets a webhook by id.
Parameters
webhook_id
- Id of the webhook to get.
get_webhook_with_token(webhook_id, webhook_token)
View Source
get_webhook_with_token(
Nostrum.Struct.Webhook.id(),
Nostrum.Struct.Webhook.token()
) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
get_webhook_with_token( Nostrum.Struct.Webhook.id(), Nostrum.Struct.Webhook.token() ) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
Gets a webhook by id and token.
This method is exactly like get_webhook/1
but does not require
authentication.
Parameters
webhook_id
- Id of the webhook to get.webhook_token
- Token of the webhook to get.
leave_guild(guild_id) View Source
Leaves a guild.
Guild to leave is specified by guild_id
.
list_guild_emojis(guild_id)
View Source
list_guild_emojis(Nostrum.Struct.Guild.id()) ::
error() | {:ok, [Nostrum.Struct.Emoji.t()]}
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
.
list_guild_emojis!(guild_id)
View Source
list_guild_emojis!(Nostrum.Struct.Guild.id()) ::
no_return() | [Nostrum.Struct.Emoji.t()]
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.
list_guild_members(guild_id, options \\ %{})
View Source
list_guild_members(Nostrum.Struct.Guild.id(), options()) ::
error() | {:ok, [Nostrum.Struct.Guild.Member.t()]}
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)
list_guild_members!(guild_id, options \\ %{})
View Source
list_guild_members!(Nostrum.Struct.Guild.id(), options()) ::
no_return() | [Nostrum.Struct.Guild.Member.t()]
list_guild_members!(Nostrum.Struct.Guild.id(), options()) :: no_return() | [Nostrum.Struct.Guild.Member.t()]
Same as list_guild_members/2
, but raises Nostrum.Error.ApiError
in case of failure.
list_voice_regions()
View Source
list_voice_regions() :: error() | {:ok, [Nostrum.Struct.VoiceRegion.t()]}
list_voice_regions() :: error() | {:ok, [Nostrum.Struct.VoiceRegion.t()]}
Gets a list of voice regions.
modify_channel(channel_id, options, reason \\ nil)
View Source
modify_channel(
Nostrum.Struct.Channel.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Channel.t()}
modify_channel( Nostrum.Struct.Channel.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Channel.t()}
Modifies a channel's settings.
An optional reason
can be given for the guild audit log.
If a Nostrum.Struct.Channel.guild_channel/0
is being modified, this
endpoint requires the MANAGE_CHANNEL
permission. It fires a
Nostrum.Consumer.channel_update/0
event. If a
Nostrum.Struct.Channel.channel_category/0
is being modified, then this
endpoint fires multiple Nostrum.Consumer.channel_update/0
events.
If successful, returns {:ok, channel}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:name
(string) - 2-100 character channel name:position
(integer) - the position of the channel in the left-hand listing:topic
(string) (Nostrum.Struct.Channel.text_channel/0
only) - 0-1024 character channel topic:nsfw
(boolean) (Nostrum.Struct.Channel.text_channel/0
only) - if the channel is nsfw:bitrate
(integer) (Nostrum.Struct.Channel.voice_channel/0
only) - the bitrate (in bits) of the voice channel; 8000 to 96000 (128000 for VIP servers):user_limit
(integer) (Nostrum.Struct.Channel.voice_channel/0
only) - the user limit of the voice channel; 0 refers to no limit, 1 to 99 refers to a user limit:permission_overwrites
(list ofNostrum.Struct.Overwrite.t/0
or equivalent map) - channel or category-specific permissions:parent_id
(Nostrum.Struct.Channel.id/0
) (Nostrum.Struct.Channel.guild_channel/0
only) - id of the new parent category for a channel
Examples
Nostrum.Api.modify_channel(41771983423143933, name: "elixir-nostrum", topic: "nostrum discussion")
{:ok, %Nostrum.Struct.Channel{id: 41771983423143933, name: "elixir-nostrum", topic: "nostrum discussion"}}
Nostrum.Api.modify_channel(41771983423143933)
{:ok, %Nostrum.Struct.Channel{id: 41771983423143933}}
modify_channel!(channel_id, options, reason \\ nil)
View Source
modify_channel!(
Nostrum.Struct.Channel.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Channel.t()
modify_channel!( Nostrum.Struct.Channel.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | Nostrum.Struct.Channel.t()
Same as modify_channel/2
, but raises Nostrum.Error.ApiError
in case of failure.
modify_current_user(options)
View Source
modify_current_user(keyword() | map()) ::
error() | {:ok, Nostrum.Struct.User.t()}
modify_current_user(keyword() | map()) :: error() | {:ok, Nostrum.Struct.User.t()}
Changes the username or avatar of the current user.
Options
:username
(string) - new username:avatar
(string) - the user's avatar as avatar data
Examples
Nostrum.Api.modify_current_user(avatar: "data:image/jpeg;base64,YXl5IGJieSB1IGx1a2luIDQgc3VtIGZ1az8=")
modify_current_user!(options)
View Source
modify_current_user!(keyword() | map()) ::
no_return() | Nostrum.Struct.User.t()
modify_current_user!(keyword() | map()) :: no_return() | Nostrum.Struct.User.t()
Same as modify_current_user/1
, but raises Nostrum.Error.ApiError
in case of failure.
modify_guild(guild_id, options \\ [], reason \\ nil)
View Source
modify_guild(
Nostrum.Struct.Guild.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Guild.rest_guild()}
modify_guild( Nostrum.Struct.Guild.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Guild.rest_guild()}
Modifies a guild's settings.
This endpoint requires the MANAGE_GUILD
permission. It fires the
Nostrum.Consumer.guild_update/0
event.
An optional reason
can be provided for the audit log.
If successful, returns {:ok, guild}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:name
(string) - guild name:region
(string) - guild voice region id:verification_level
(integer) - verification level:default_message_notifications
(integer) - default message notification level:explicit_content_filter
(integer) - explicit content filter level:afk_channel_id
(Nostrum.Snowflake.t/0
) - id for afk channel:afk_timeout
(integer) - afk timeout in seconds:icon
(base64 data URI) - 128x128 jpeg image for the guild icon:owner_id
(Nostrum.Snowflake.t/0
) - user id to transfer guild ownership to (must be owner):splash
(base64 data URI) - 128x128 jpeg image for the guild splash (VIP only):system_channel_id
(Nostrum.Snowflake.t/0
) - the id of the channel to which system messages are sent
Examples
Nostrum.Api.modify_guild(451824027976073216, name: "Nose Drum")
{:ok, %Nostrum.Struct.Guild{id: 451824027976073216, name: "Nose Drum", ...}}
modify_guild!(guild_id, options \\ [])
View Source
modify_guild!(Nostrum.Struct.Guild.id(), options()) ::
no_return() | Nostrum.Struct.Guild.rest_guild()
modify_guild!(Nostrum.Struct.Guild.id(), options()) :: no_return() | Nostrum.Struct.Guild.rest_guild()
Same as modify_guild/2
, but raises Nostrum.Error.ApiError
in case of failure.
modify_guild_channel_positions(guild_id, positions)
View Source
modify_guild_channel_positions(Nostrum.Struct.Guild.id(), [
%{id: integer(), position: integer()}
]) :: error() | {:ok}
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}
modify_guild_channel_positions!(guild_id, positions)
View Source
modify_guild_channel_positions!(Nostrum.Struct.Guild.id(), [
%{id: integer(), position: integer()}
]) :: no_return() | {:ok}
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.
modify_guild_embed(guild_id, options) View Source
Modifies a guild imbed.
modify_guild_emoji(guild_id, emoji_id, options \\ %{}, reason \\ nil)
View Source
modify_guild_emoji(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Emoji.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Emoji.t()}
modify_guild_emoji( Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Emoji.t()}
Modify the given emoji.
This endpoint requires the MANAGE_EMOJIS
permission. It fires a
Nostrum.Consumer.guild_emojis_update/0
event.
An optional reason
can be provided for the audit log.
If successful, returns {:ok, emoji}
. Otherwise, returns Nostrum.Api.error/0
.
Options
:name
(string) - name of the emoji:roles
(list ofNostrum.Snowflake.t/0
) - roles to which this emoji will be whitelisted
Examples
Nostrum.Api.modify_guild_emoji(43189401384091, 4314301984301, name: "elixir", roles: [])
modify_guild_emoji!(guild_id, emoji_id, options, reason \\ nil)
View Source
modify_guild_emoji!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Emoji.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Emoji.t()
modify_guild_emoji!( Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | Nostrum.Struct.Emoji.t()
Same as modify_guild_emoji/3
, but raises Nostrum.Error.ApiError
in case of failure.
modify_guild_integrations(guild_id, integration_id, options) View Source
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.
modify_guild_member(guild_id, user_id, options \\ %{})
View Source
modify_guild_member(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.User.id(),
options()
) :: error() | {:ok}
modify_guild_member( Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), options() ) :: error() | {:ok}
Modifies a guild member's attributes.
This endpoint fires the Nostrum.Consumer.guild_member_update/0
event.
It situationally requires the MANAGE_NICKNAMES
, MANAGE_ROLES
,
MUTE_MEMBERS
, DEAFEN_MEMBERS
, and MOVE_MEMBERS
permissions.
If successful, returns {:ok}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:nick
(string) - value to set users nickname to:roles
(list ofNostrum.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)
Examples
Nostrum.Api.modify_guild_member(41771983423143937, 637162356451, nick: "Nostrum")
{:ok}
modify_guild_member!(guild_id, user_id, options \\ %{})
View Source
modify_guild_member!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.User.id(),
options()
) :: error() | {:ok}
modify_guild_member!( Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), options() ) :: error() | {:ok}
Same as modify_guild_member/3
, but raises Nostrum.Error.ApiError
in case of failure.
modify_guild_role(guild_id, role_id, options, reason \\ nil)
View Source
modify_guild_role(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Guild.Role.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Guild.Role.t()}
modify_guild_role( Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Guild.Role.t()}
Modifies a guild role.
This endpoint requires the MANAGE_ROLES
permission. It fires a
Nostrum.Consumer.guild_role_update/0
event.
An optional reason
can be specified for the audit log.
If successful, returns {:ok, role}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:name
(string) - name of the role:permissions
(integer) - bitwise of the enabled/disabled permissions:color
(integer) - RGB color value (default: 0):hoist
(boolean) - whether the role should be displayed separately in the sidebar:mentionable
(boolean) - whether the role should be mentionable
Examples
Nostrum.Api.modify_guild_role(41771983423143937, 392817238471936, hoist: false, name: "foo-bar")
modify_guild_role!(guild_id, role_id, options, reason \\ nil)
View Source
modify_guild_role!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Guild.Role.id(),
options(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | Nostrum.Struct.Guild.Role.t()
modify_guild_role!( Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id(), options(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | Nostrum.Struct.Guild.Role.t()
Same as modify_guild_role/3
, but raises Nostrum.Error.ApiError
in case of failure.
modify_guild_role_positions(guild_id, positions, reason \\ nil)
View Source
modify_guild_role_positions(
Nostrum.Struct.Guild.id(),
[%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}],
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}
modify_guild_role_positions( Nostrum.Struct.Guild.id(), [%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}], Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}
Reorders a guild's roles.
This endpoint requires the MANAGE_ROLES
permission. It fires multiple
Nostrum.Consumer.guild_role_update/0
events.
If successful, returns {:ok, roles}
. Otherwise, returns a Nostrum.Api.error/0
.
positions
is a list of maps that each map a role id with a position.
Examples
Nostrum.Api.modify_guild_role_positions(41771983423143937, [%{id: 41771983423143936, position: 2}])
modify_guild_role_positions!(guild_id, positions, reason \\ nil)
View Source
modify_guild_role_positions!(
Nostrum.Struct.Guild.id(),
[%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}],
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | [Nostrum.Struct.Guild.Role.t()]
modify_guild_role_positions!( Nostrum.Struct.Guild.id(), [%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}], Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | [Nostrum.Struct.Guild.Role.t()]
Same as modify_guild_role_positions/2
, but raises Nostrum.Error.ApiError
in case of failure.
modify_webhook(webhook_id, args, reason \\ nil)
View Source
modify_webhook(
Nostrum.Struct.Webhook.id(),
%{name: String.t(), avatar: String.t()},
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
modify_webhook( Nostrum.Struct.Webhook.id(), %{name: String.t(), avatar: String.t()}, Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
Modifies a webhook.
Parameters
webhook_id
- Id of the webhook to modify.args
- Map with the following optional keys:name
- Name of the webhook.avatar
- Base64 128x128 jpeg image for the default avatar.
reason
- An optional reason for the guild audit log.
modify_webhook_with_token(webhook_id, webhook_token, args, reason \\ nil)
View Source
modify_webhook_with_token(
Nostrum.Struct.Webhook.id(),
Nostrum.Struct.Webhook.token(),
%{name: String.t(), avatar: String.t()},
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
modify_webhook_with_token( Nostrum.Struct.Webhook.id(), Nostrum.Struct.Webhook.token(), %{name: String.t(), avatar: String.t()}, Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
Modifies a webhook with a token.
This method is exactly like modify_webhook/1
but does not require
authentication.
Parameters
webhook_id
- Id of the webhook to modify.webhook_token
- Token of the webhook to get.args
- Map with the following optional keys:name
- Name of the webhook.avatar
- Base64 128x128 jpeg image for the default avatar.
reason
- An optional reason for the guild audit log.
remove_guild_ban(guild_id, user_id, reason \\ nil)
View Source
remove_guild_ban(
integer(),
integer(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
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.
remove_guild_member(guild_id, user_id, reason \\ nil)
View Source
remove_guild_member(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.User.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
remove_guild_member( Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: error() | {:ok}
Removes a member from a guild.
This event requires the KICK_MEMBERS
permission. It fires a
Nostrum.Consumer.guild_member_remove/0
event.
An optional reason can be provided for the audit log with reason
.
If successful, returns {:ok}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.remove_guild_member(1453827904102291, 18739485766253)
{:ok}
remove_guild_member!(guild_id, user_id, reason \\ nil)
View Source
remove_guild_member!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.User.id(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: no_return() | {:ok}
remove_guild_member!( Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), Nostrum.Struct.Guild.AuditLogEntry.reason() ) :: no_return() | {:ok}
Same as remove_guild_member/2
, but raises Nostrum.Error.ApiError
in case of failure.
remove_guild_member_role(guild_id, user_id, role_id, reason \\ nil)
View Source
remove_guild_member_role(
integer(),
integer(),
integer(),
Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: error() | {:ok}
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.
request(request) View Source
request(method, route, body \\ "", options \\ []) View Source
request_multipart(method, route, body \\ "", options \\ []) View Source
start_typing(channel_id) View Source
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.
start_typing!(channel_id) View Source
Same as start_typing/1
, but raises Nostrum.Error.ApiError
in case of failure.
sync_guild_integrations(guild_id, integration_id) View Source
Syncs a guild integration.
Integration to sync is specified by guild_id
and integeration_id
.
update_shard_status(pid, status, game, type \\ 0, stream \\ nil) View Source
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
update_status(status, game, type \\ 0, stream \\ nil) View Source
Updates the status of the bot for all shards.
See update_shard_status/5
for usage.
update_voice_state(guild_id, channel_id, self_mute \\ false, self_deaf \\ false)
View Source
update_voice_state(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Channel.id(),
boolean(),
boolean()
) :: no_return() | :ok
update_voice_state( Nostrum.Struct.Guild.id(), Nostrum.Struct.Channel.id(), 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
.