Nostrum v0.3.1 Nostrum.Api View Source
Interface for Discord's rest API.
By default all methods in this module are ran synchronously. If you wish to have async rest operations I recommend you execute these functions inside of a task.
Examples
# Async Task
t = Task.async fn ->
Nostrum.Api.get_channel_messages(12345678912345, :infinity, {})
end
messages = Task.await t
# A lot of times we don't care about the return value of the function
Task.start fn ->
messages = ["in", "the", "end", "it", "doesn't", "even", "matter"]
Enum.each messages, &Nostrum.Api.create_message!(12345678912345, &1)
end
A note about Strings and Ints
Currently, responses from the REST api will have id
fields as string
.
Everything received from the WS connection will have id
fields as int
.
If you're processing a response from the API and trying to access something in the cache
based off of an id
in the response, you will need to conver it to an int
using
String.to_integer/1
. I'm open to suggestions for how this should be handled going forward.
Example
messages = Nostrum.Api.get_pinned_messages!(12345678912345)
authors =
Enum.map messages, fn msg ->
author_id = String.to_integer(msg.author.id)
Nostrum.Cache.User.get!(id: author_id)
end
Link to this section Summary
Types
Represents an emoji for interacting with reaction endpoints
Represents a failed response from the API
Represents a limit used to retrieve messages
Represents a tuple used to locate messages
Represents optional parameters for Api functions
Represents different statuses the bot can have
Functions
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
Deletes multiple messages from a channel
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
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
Edit the permission overwrites for a user or role
Same as edit_message/3
, but takes a Nostrum.Struct.Message
instead of a
channel_id
and message_id
Edits a previously sent message in a channel
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 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
Retrives 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
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/3
, 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
Triggers the typing indicator
Syncs a guild integration
Updates the status of the bot for a certain shard
Updates the status of the bot for all shards
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()}
add_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), options()) :: error() | {:ok, Nostrum.Struct.Guild.Member.t()}
Puts a user in a guild.
This endpoint fires the Nostrum.Consumer.guild_member_add/0
event.
It requires the CREATE_INSTANT_INVITE
permission. Additionally, it
situationally requires the MANAGE_NICKNAMES
, MANAGE_ROLES
,
MUTE_MEMBERS
, and DEAFEN_MEMBERS
permissions.
If successful, returns {:ok, member}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:access_token
(string) - the user's oauth2 access token:nick
(string) - value to set users nickname to:roles
(list 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()
add_guild_member!( Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), options() ) :: no_return() | Nostrum.Struct.Guild.Member.t()
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) View Source
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
.
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)
View Source
begin_guild_prune(Nostrum.Struct.Guild.id(), 1..30) ::
error() | {:ok, %{pruned: integer()}}
begin_guild_prune(Nostrum.Struct.Guild.id(), 1..30) :: error() | {:ok, %{pruned: integer()}}
Begins a guild prune to prune members within days
.
This endpoint requires the KICK_MEMBERS
permission. It fires multiple
Nostrum.Consumer.guild_member_remove/0
events.
If successful, returns {:ok, %{pruned: pruned}}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.begin_guild_prune(81384788765712384, 1)
{:ok, %{pruned: 0}}
begin_guild_prune!(guild_id, days)
View Source
begin_guild_prune!(Nostrum.Struct.Guild.id(), 1..30) ::
no_return() | %{pruned: integer()}
begin_guild_prune!(Nostrum.Struct.Guild.id(), 1..30) :: no_return() | %{pruned: integer()}
Same as begin_guild_prune/2
, but raises Nostrum.Error.ApiError
in case of failure.
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}
Deletes multiple messages from a channel.
See bulk_delete_messages/2
for more info.
Raises Nostrum.Error.ApiError
if error occurs while making the rest call.
create_channel_invite(channel_id, options \\ [])
View Source
create_channel_invite(Nostrum.Struct.Channel.id(), options()) ::
error() | {:ok, Nostrum.Struct.Invite.detailed_invite()}
create_channel_invite(Nostrum.Struct.Channel.id(), options()) :: error() | {:ok, Nostrum.Struct.Invite.detailed_invite()}
Creates an invite for a guild channel.
This endpoint requires the CREATE_INSTANT_INVITE
permission.
If successful, returns {:ok, invite}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:max_age
(integer) - duration of invite in seconds before expiry, or 0 for never. (default:86400
):max_uses
(integer) - max number of uses or 0 for unlimited. (default:0
):temporary
(boolean) - Whether the invite should grant temporary membership. (default:false
):unique
(boolean) - used when creating unique one time use invites. (default:false
)
Examples
Nostrum.Api.create_channel_invite(41771983423143933)
{:ok, Nostrum.Struct.Invite{}}
Nostrum.Api.create_channel_invite(41771983423143933, max_uses: 20)
{:ok, %Nostrum.Struct.Invite{}}
create_channel_invite!(channel_id, options \\ [])
View Source
create_channel_invite!(Nostrum.Struct.Channel.id(), options()) ::
no_return() | Nostrum.Struct.Invite.detailed_invite()
create_channel_invite!(Nostrum.Struct.Channel.id(), options()) :: 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) View Source
Bans a user from a guild.
User to delete is specified by guild_id
and user_id
.
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)
View Source
create_guild_emoji(Nostrum.Struct.Guild.id(), options()) ::
error() | {:ok, Nostrum.Struct.Emoji.t()}
create_guild_emoji(Nostrum.Struct.Guild.id(), options()) :: error() | {:ok, Nostrum.Struct.Emoji.t()}
Creates a new emoji for the given guild.
This endpoint requires the MANAGE_EMOJIS
permission. It fires a
Nostrum.Consumer.guild_emojis_update/0
event.
If successful, returns {:ok, emoji}
. Otherwise, returns Nostrum.Api.error/0
.
Options
:name
(string) - name of the emoji:image
(base64 data URI) - the 128x128 emoji image. Maximum size of 256kb:roles
(list ofNostrum.Struct.Snowflake.t/0
) - roles for which this emoji will be whitelisted (default: [])
:name
and :image
are always required.
Examples
image = "data:image/png;base64,YXl5IGJieSB1IGx1a2luIDQgc3VtIGZ1az8="
Nostrum.Api.create_guild_emoji(43189401384091, name: "nostrum", image: image, roles: [])
create_guild_emoji!(guild_id, params)
View Source
create_guild_emoji!(Nostrum.Struct.Guild.id(), options()) ::
no_return() | Nostrum.Struct.Emoji.t()
create_guild_emoji!(Nostrum.Struct.Guild.id(), options()) :: 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)
View Source
create_guild_role(Nostrum.Struct.Guild.id(), options()) ::
error() | {:ok, Nostrum.Struct.Guild.Role.t()}
create_guild_role(Nostrum.Struct.Guild.id(), options()) :: error() | {:ok, Nostrum.Struct.Guild.Role.t()}
Creates a guild role.
This endpoint requires the MANAGE_ROLES
permission. It fires a
Nostrum.Consumer.guild_role_create/0
event.
If successful, returns {:ok, role}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:name
(string) - name of the role (default: "new role"):permissions
(integer) - bitwise of the enabled/disabled permissions (default: @everyone perms):color
(integer) - RGB color value (default: 0):hoist
(boolean) - whether the role should be displayed separately in the sidebar (default: false):mentionable
(boolean) - whether the role should be mentionable (default: false)
Examples
Nostrum.Api.create_guild_role(41771983423143937, name: "nostrum-club", hoist: true)
create_guild_role!(guild_id, options)
View Source
create_guild_role!(Nostrum.Struct.Guild.id(), options()) ::
no_return() | Nostrum.Struct.Guild.Role.t()
create_guild_role!(Nostrum.Struct.Guild.id(), options()) :: 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.Struct.Snowflake.t/0
) - a nonce that can be used for optimistic message sending:tts
(boolean) - true if this is a TTS message:file
(Path.t/0
| map) - the path of the file being sent, or a map with the following keys if sending a binary from memory:name
(string) - the name of the file:body
(string) - binary you wish to send
:embed
(Nostrum.Struct.Embed.t/0
) - embedded rich 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)
View Source
create_webhook(Nostrum.Struct.Channel.id(), %{
name: String.t(),
avatar: String.t()
}) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
create_webhook(Nostrum.Struct.Channel.id(), %{ name: String.t(), avatar: String.t() }) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
Creates a webhook.
Parameters
channel_id
- Id of the channel to send the message to.args
- Map with the following required keys:name
- Name of the webhook.avatar
- Base64 128x128 jpeg image for the default avatar.
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)
View Source
delete_channel(Nostrum.Struct.Channel.id()) ::
error() | {:ok, Nostrum.Struct.Channel.t()}
delete_channel(Nostrum.Struct.Channel.id()) :: error() | {:ok, Nostrum.Struct.Channel.t()}
Deletes a channel.
If deleting a Nostrum.Struct.Channel.guild_channel/0
, this endpoint requires
the MANAGE_CHANNELS
permission. It fires a
Nostrum.Consumer.channel_delete/0
. If a Nostrum.Struct.Channel.channel_category/0
is deleted, then a Nostrum.Consumer.channel_update/0
event will fire
for each channel under the category.
If successful, returns {:ok, channel}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.delete_channel(421533712753360896)
{:ok, %Nostrum.Struct.Channel{id: 421533712753360896}}
delete_channel!(channel_id)
View Source
delete_channel!(Nostrum.Struct.Channel.id()) ::
no_return() | Nostrum.Struct.Channel.t()
delete_channel!(Nostrum.Struct.Channel.id()) :: 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) View Source
Delete a channel permission for a user or role.
Role or user overwrite to delete is specified by channel_id
and overwrite_id
.
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)
View Source
delete_guild_emoji(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
error() | {:ok}
delete_guild_emoji(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) :: error() | {:ok}
Deletes the given emoji.
This endpoint requires the MANAGE_EMOJIS
permission. It fires a
Nostrum.Consumer.guild_emojis_update/0
event.
If successful, returns {:ok}
. Otherwise, returns Nostrum.Api.error/0
.
delete_guild_emoji!(guild_id, emoji_id)
View Source
delete_guild_emoji!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
no_return() | {:ok}
delete_guild_emoji!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) :: no_return() | {:ok}
Same as delete_guild_emoji/2
, but raises Nostrum.Error.ApiError
in case of failure.
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)
View Source
delete_guild_role(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id()) ::
error() | {:ok}
delete_guild_role(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id()) :: error() | {:ok}
Deletes a role from a guild.
This endpoint requires the MANAGE_ROLES
permission. It fires a
Nostrum.Consumer.guild_role_delete/0
event.
If successful, returns {:ok}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.delete_guild_role(41771983423143937, 392817238471936)
delete_guild_role!(guild_id, role_id)
View Source
delete_guild_role!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id()) ::
no_return() | {:ok}
delete_guild_role!(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id()) :: no_return() | {:ok}
Same as delete_guild_role/2
, but raises Nostrum.Error.ApiError
in case of failure.
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
.
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)
View Source
delete_webhook(Nostrum.Struct.Webhook.id()) :: error() | {:ok}
delete_webhook(Nostrum.Struct.Webhook.id()) :: error() | {:ok}
Deletes a webhook.
Parameters
webhook_id
- Id of webhook to delete.webhook_token
- Token of the webhook to delete.
edit_channel_permissions(channel_id, overwrite_id, permission_info) View Source
Edit the permission overwrites for a user or role.
Role or user to overwrite is specified by channel_id
and overwrite_id
.
permission_info
is a kwl with the following required keys:
allow
- Bitwise value of allowed permissions.deny
- Bitwise value of denied permissions.type
-member
if editing a user,role
if editing a role.
edit_channel_permissions!(channel_id, overwrite_id, permission_info) View Source
Edit the permission overwrites for a user or role.
See edit_channel_permissions/2
for more info.
Raises Nostrum.Error.ApiError
if error occurs while making the rest call.
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 webhook to delete.webhook_token
- Token of the webhook to delete.
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 webhook to delete.webhook_token
- Token of the webhook to delete.
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 webhook to delete.webhook_token
- Token of the webhook to delete.args
- Map with the following required keys:content
- Message content.file
- File to send.embeds
- Embed to send.username
- Overrides the default name of the webhook.avatar_url
- Overrides the default avatar of the webhook.tts
- Whether the message should be read over text to speech.
wait
- Whether to return an error or not. Defaults tofalse
.
Only one of content
, file
or embed
should be supplied in the args
parameter.
get_application_information() View Source
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()]}
Retrives a channel's messages around a locator
up to a limit
.
This endpoint requires the 'VIEW_CHANNEL' permission. If the current user is missing the 'READ_MESSAGE_HISTORY' permission, then this function will return no messages.
If successful, returns {:ok, messages}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.get_channel_messages(43189401384091, 5, {:before 130230401384})
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.Struct.Snowflake.t/0
) - get guilds before this guild ID:after
(Nostrum.Struct.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_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 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 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)
View Source
modify_channel(Nostrum.Struct.Channel.id(), options()) ::
error() | {:ok, Nostrum.Struct.Channel.t()}
modify_channel(Nostrum.Struct.Channel.id(), options()) :: error() | {:ok, Nostrum.Struct.Channel.t()}
Modifies a channel's settings.
If a Nostrum.Struct.Channel.guild_channel/0
is being modified, this
endpoint requires the MANAGE_CHANNEL
permission. It fires a
Nostrum.Consumer.channel_update/0
event. If a
Nostrum.Struct.Channel.channel_category/0
is being modified, then this
endpoint fires multiple Nostrum.Consumer.channel_update/0
events.
If successful, returns {:ok, channel}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
: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)
View Source
modify_channel!(Nostrum.Struct.Channel.id(), options()) ::
no_return() | Nostrum.Struct.Channel.t()
modify_channel!(Nostrum.Struct.Channel.id(), options()) :: 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/3
, but raises Nostrum.Error.ApiError
in case of failure.
modify_guild(guild_id, options \\ [])
View Source
modify_guild(Nostrum.Struct.Guild.id(), options()) ::
error() | {:ok, Nostrum.Struct.Guild.rest_guild()}
modify_guild(Nostrum.Struct.Guild.id(), options()) :: 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.
If successful, returns {:ok, guild}
. Otherwise, returns a Nostrum.Api.error/0
.
Options
:name
(string) - guild name:region
(string) - guild voice region id:verification_level
(integer) - verification level:default_message_notifications
(integer) - default message notification level:explicit_content_filter
(integer) - explicit content filter level:afk_channel_id
(Nostrum.Struct.Snowflake.t/0
) - id for afk channel:afk_timeout
(integer) - afk timeout in seconds:icon
(base64 data URI) - 128x128 jpeg image for the guild icon:owner_id
(Nostrum.Struct.Snowflake.t/0
) - user id to transfer guild ownership to (must be owner):splash
(base64 data URI) - 128x128 jpeg image for the guild splash (VIP only):system_channel_id
(Nostrum.Struct.Snowflake.t/0
) - the id of the channel to which system messages are sent
Examples
Nostrum.Api.modify_guild(81384788765712384, name: "Elixir Guild")
{:ok, %Nostrum.Struct.Channel{id: 81384788765712384, name: "Elixir Guild"}}
Nostrum.Api.modify_channel(81384788765712384)
{:ok, %Nostrum.Struct.Channel{id: 81384788765712384}}
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 \\ %{})
View Source
modify_guild_emoji(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Emoji.id(),
options()
) :: error() | {:ok, Nostrum.Struct.Emoji.t()}
modify_guild_emoji( Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id(), options() ) :: 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.
If successful, returns {:ok, emoji}
. Otherwise, returns Nostrum.Api.error/0
.
Options
:name
(string) - name of the emoji:roles
(list ofNostrum.Struct.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)
View Source
modify_guild_emoji!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Emoji.id(),
options()
) :: no_return() | Nostrum.Struct.Emoji.t()
modify_guild_emoji!( Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id(), options() ) :: 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.Struct.Snowflake.t/0
) - array of role ids the member is assigned:mute
(boolean) - if the user is muted:deaf
(boolean) - if the user is deafened:channel_id
(Nostrum.Struct.Snowflake.t/0
) - id of channel to move user to (if they are connected to voice)
Examples
Nostrum.Api.modify_guild_member(41771983423143937, 637162356451, nick: "Nostrum")
{:ok}
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)
View Source
modify_guild_role(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Guild.Role.id(),
options()
) :: error() | {:ok, Nostrum.Struct.Guild.Role.t()}
modify_guild_role( Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id(), options() ) :: 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.
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)
View Source
modify_guild_role!(
Nostrum.Struct.Guild.id(),
Nostrum.Struct.Guild.Role.id(),
options()
) :: no_return() | Nostrum.Struct.Guild.Role.t()
modify_guild_role!( Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id(), options() ) :: 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)
View Source
modify_guild_role_positions(Nostrum.Struct.Guild.id(), [
%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}
]) :: error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}
modify_guild_role_positions(Nostrum.Struct.Guild.id(), [ %{id: Nostrum.Struct.Guild.Role.id(), position: integer()} ]) :: error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}
Reorders a guild's roles.
This endpoint requires the MANAGE_ROLES
permission. It fires multiple
Nostrum.Consumer.guild_role_update/0
events.
If successful, returns {:ok, roles}
. Otherwise, returns a Nostrum.Api.error/0
.
positions
is a list of maps that each map a role id with a position.
Examples
Nostrum.Api.modify_guild_role_positions(41771983423143937, [%{id: 41771983423143936, position: 2}])
modify_guild_role_positions!(guild_id, positions)
View Source
modify_guild_role_positions!(Nostrum.Struct.Guild.id(), [
%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}
]) :: no_return() | [Nostrum.Struct.Guild.Role.t()]
modify_guild_role_positions!(Nostrum.Struct.Guild.id(), [ %{id: Nostrum.Struct.Guild.Role.id(), position: integer()} ]) :: no_return() | [Nostrum.Struct.Guild.Role.t()]
Same as modify_guild_role_positions/2
, but raises Nostrum.Error.ApiError
in case of failure.
modify_webhook(webhook_id, args)
View Source
modify_webhook(Nostrum.Struct.Webhook.id(), %{
name: String.t(),
avatar: String.t()
}) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
modify_webhook(Nostrum.Struct.Webhook.id(), %{ name: String.t(), avatar: String.t() }) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
Modifies a webhook.
Parameters
webhook_id
- Id of the webhook to modify.args
- Map with the following optional keys:name
- Name of the webhook.avatar
- Base64 128x128 jpeg image for the default avatar.
modify_webhook_with_token(webhook_id, webhook_token, args)
View Source
modify_webhook_with_token(
Nostrum.Struct.Webhook.id(),
Nostrum.Struct.Webhook.token(),
%{name: String.t(), avatar: String.t()}
) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
modify_webhook_with_token( Nostrum.Struct.Webhook.id(), Nostrum.Struct.Webhook.token(), %{name: String.t(), avatar: String.t()} ) :: error() | {:ok, Nostrum.Struct.Webhook.t()}
Modifies a webhook with a token.
This method is exactly like modify_webhook/1
but does not require
authentication.
Parameters
webhook_id
- Id of the webhook to modify.webhook_token
- Token of the webhook to get.args
- Map with the following optional keys:name
- Name of the webhook.avatar
- Base64 128x128 jpeg image for the default avatar.
remove_guild_ban(guild_id, user_id) View Source
Removes a ban for a user.
User to unban is specified by guild_id
and user_id
.
remove_guild_member(guild_id, user_id)
View Source
remove_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
error() | {:ok}
remove_guild_member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) :: error() | {:ok}
Removes a member from a guild.
This event requires the KICK_MEMBERS
permission. It fires a
Nostrum.Consumer.guild_member_remove/0
event.
If successful, returns {:ok}
. Otherwise, returns a Nostrum.Api.error/0
.
Examples
Nostrum.Api.remove_guild_member(1453827904102291, 18739485766253)
{:ok}
remove_guild_member!(guild_id, user_id)
View Source
remove_guild_member!(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
no_return() | {:ok}
remove_guild_member!(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) :: no_return() | {:ok}
Same as remove_guild_member/2
, but raises Nostrum.Error.ApiError
in case of failure.
remove_guild_member_role(guild_id, user_id, role_id) View Source
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
.
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
Triggers the typing indicator.
Triggers the typing indicator in the channel specified by channel_id
.
The typing indicator lasts for about 8 seconds and then automatically stops.
Raises Nostrum.Error.ApiError
if error occurs while making the rest call.
Returns {:ok} if successful.
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/4
for usage.