Elixir v0.2.0 Nostrum.Api

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

Summary

Types

Represents a failed response from the API

Represents a limit used to retrieve messages

Represents a tuple used to locate messages

Represents different statuses the bot can have

Functions

Accepts an invite

Adds a member to a guild

Begins a guild prune

Deletes multiple messages from a channel

Deletes multiple messages from a channel

Creates an invite for a channel

Creates a new DM channel

Creates a new group DM channel

Creates a new guild integeration

Create a rection for a message

Deletes all reactions from a message

Delete a channel

Delete a channel

Delete a channel permission for a user or role

Deletes a guild

Deletes an invite

Deletes a rection made by the user

Deletes a webhook

Edit the permission overwrites for a user or role

Edit the permission overwrites for a user or role

Modify a guild’s settings

Get a channel

Get a channel

Gets a list of invites for a channel

Retrieves a message from a channel

Retrieves a message from a channel

Retrieve messages from a channel

Retrieve messages from a channel

Gets a list of webook for a channel

Gets a list of channels

Gets info on the current user

Gets a list of guilds the user is currently in

Gets a guild using the REST api

Gets a guild using the REST api

Gets a list of users banend from a guild

Gets a guild embed

Gets a list of guild integerations

Gets a list of invites for a guild

Gets a list of guild members

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

Gets a guild’s roles

Gets a list of webooks for a guild

Gets an invite

Gets a guild member

Gets all pinned messages

Gets all pinned messages

Gets all users who reacted with an emoji

Returns the token of the bot

Gets a user

Gets a list of user connections

Gets a list of user DM channels

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 voice regions

Reorders a guild’s channels

Changes the username or avatar of the current user

Modifies a guild imbed

Changes the settings and behaviours for a guild integeration

Removes a ban for a user

Removes a memeber from a guild

Triggers the typing indicator

Triggers the typing indicator

Updates the status of the bot for all shards

Updates the status of the bot for a certain shard

Types

error()
error() :: {:error, Nostrum.Error.ApiError.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()
limit() :: integer | :infinity

Represents a limit used to retrieve messages.

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

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

Represents a tuple used to locate messages.

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

status()
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.

Functions

accept_invite(invite_code)
accept_invite(integer) :: error | {:ok, Nostrum.Struct.Invite.t}

Accepts an invite.

Not available to bot accounts. Invite to accept is specified by invite_code.

add_guild_member_role(guild_id, user_id, role_id)
add_guild_member_role(integer, integer, integer) ::
  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.

add_member(guild_id, user_id, options)
add_member(integer, integer, %{nick: String.t, roles: [integer], mute: boolean, deaf: boolean, channel_id: integer}) ::
  error |
  {:ok, Nostrum.Struct.Guild.Member.t}

Adds a member to a guild.

Member to add is specified by guild_id and user_id

options is a map with the following option keys:

  • nick - Users nickname.
  • roles - Array of roles to give member.
  • mute - If the user should be muted.
  • deaf - If the user should be deafaned.
  • channel_id - Id of the channel to move the user to.
add_pinned_message(channel_id, message_id)
add_pinned_message(integer, integer) :: error | {:ok}

Pins a message.

Pins the message specified by message_id in the channel specified by channel_id.

Returns {:ok} if successful. error otherwise.

add_pinned_message!(channel_id, message_id)
add_pinned_message!(integer, integer) :: no_return | {:ok}

Pins a message.

Pins the message specified by message_id in the channel specified by channel_id.

Raises Nostrum.Error.ApiError if error occurs while making the rest call. Returns {:ok} if successful.

bangify(to_bang)
begin_guild_prune(guild_id, days)
begin_guild_prune(integer, integer) ::
  error |
  {:ok, %{pruned: integer}}

Begins a guild prune.

Guild to number is specified by guild_id. Days is that number of days to count prune for.

bulk_delete_messages(channel_id, messages, filter \\ true)
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.

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)
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(guild_id, options)
create_channel(integer, %{name: String.t, type: String.t, bitrate: integer, user_limit: integer, permission_overwrites: [Nostrum.Struct.Overwrite.t]}) ::
  error |
  {:ok, Nostrum.Struct.Channel.t}

Creates a channel.

Guild to create channel in is specifed by guild_id.

options is a map with the following optional keys (except for name):

  • name - Channel name.
  • type - Channel type.
  • bitrate - Bitrate if creating voice channel.
  • user_limit - User limit if creating voice channel.
  • permission_overwrites - Array of permission overwrites.
create_channel_invite(channel_id, options \\ %{})
create_channel_invite(integer, max_age: integer, max_uses: integer, temporary: boolean, unique: boolean) ::
  error |
  {:ok, Nostrum.Struct.Invite.t}

Creates an invite for a channel.

options is a kwl with the following optional keys:

  • max_age - Duration of invite in seconds before expiry, or 0 for never
  • max_uses - Max number of uses or 0 for unlimited.
  • temporary - Whether the invite should grant temporary membership.
  • unique - Used when creating unique one time use invites.
create_dm(user_id)
create_dm(integer) :: error | {:ok, Nostrum.Struct.DMChannel.t}

Creates a new DM channel.

Opens a DM channel with the user specified by user_id.

create_group_dm(access_tokens, nicks)
create_group_dm([String.t], map) ::
  error |
  {:ok, Nostrum.Struct.DMChannel.t}

Creates a new group DM channel.

create_guild_ban(guild_id, user_id, days_to_delete)
create_guild_ban(integer, integer, integer) :: error | {:ok}

Bans a user from a guild.

User to delete is specified by guild_id and user_id.

create_guild_integrations(guild_id, options)
create_guild_integrations(integer, %{type: String.t, id: integer}) ::
  error |
  {:ok}

Creates a new guild integeration.

Guild to create integration with is specified by guild_id.

options is a map with the following requires keys:

  • type - Integration type.
  • id - Integeration id.
create_guild_role(guild_id, options)
create_guild_role(integer, name: String.t, permissions: integer, color: integer, hoist: boolean, mentionable: boolean) ::
  error |
  {:ok, Nostrum.Struct.Guild.Role.t}

Creates a guild role.

Guild to create guild for is specified by guild_id.

options is a map with the following optional keys:

  • name - Name of the role.
  • permissions - Bitwise of the enabled/disabled permissions.
  • color - RGB color value.
  • hoist - Whether the role should be displayed seperately in the sidebar.
  • mentionable - Whether the role should be mentionable.
create_message(channel_id, content, tts \\ false)
create_message(Nostrum.Struct.Guild.TextChannel.id, String.t, boolean) ::
  error |
  {:ok, Nostrum.Struct.Message.t}
create_message(Nostrum.Struct.Guild.TextChannel.id, [content: String.t, embed: Nostrum.Struct.Embed.t], boolean) ::
  error |
  {:ok, Nostrum.Struct.Message.t}
create_message(Nostrum.Struct.Guild.TextChannel.id, [content: String.t, file: String.t], boolean) ::
  error |
  {:ok, Nostrum.Struct.Message.t}

Send a message to a channel.

Parameters

  • channel_id - Id of the channel to send the message to.
  • content - String, embed, or file to send to the channel.
  • tts - Whether the message should be read over text to speech.

Example

Nostrum.Api.create_message(1111111111111, [content: "my os rules", file: ~S"C:\i\use\windows"])
create_message!(channel_id, content, tts \\ false)
create_message!(integer, String.t, boolean) ::
  no_return |
  Nostrum.Struct.Message.t

Send a message to a channel.

Send content to the channel identified with channel_id. tts is an optional parameter that dictates whether the message should be played over text to speech.

Raises Nostrum.Error.ApiError if error occurs while making the rest call. Returns Nostrum.Struct.Message if successful.

create_reaction(channel_id, message_id, emoji)
create_reaction(integer, integer, String.t | Nostrum.Struct.Emoji.custom_emoji) ::
  error |
  {:ok}
create_reaction(integer, integer, String.t | Nostrum.Struct.Emoji.custom_emoji) ::
  error |
  {:ok}

Create a rection for a message.

Creates a reaction using an emoji for the message specified by message_id and channel_id. emoji can be a Nostrum.Struct.Emoji.custom_emoji.t, a base 16 unicode emoji string, or a uri encoded string.

Example

Nostrum.Api.create_reaction(123123123123, 321321321321, "\xF0\x9F\x98\x81")
Nostrum.Api.create_reaction(123123123123, 321321321321, URI.encode("\u2b50"))

Returns {:ok} if successful, {:error, reason} otherwise.

create_webhook(channel_id, args)

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)
delete_all_reactions(integer, integer) :: error | {:ok}

Deletes all reactions from a message.

Reaction to delete is specified by channel_id, message_id, and emoji.

Returns {:ok} if successful, {:error, reason} otherwise.

delete_channel(channel_id)
delete_channel(integer) ::
  error |
  {:ok, Nostrum.Struct.Channel.t}

Delete a channel.

Channel to delete is specified by channel_id.

delete_channel!(channel_id)
delete_channel!(integer) :: no_return | Nostrum.Struct.Channel.t

Delete a channel.

Raises Nostrum.Error.ApiError if error occurs while making the rest call.

delete_channel_permissions(channel_id, overwrite_id)
delete_channel_permissions(integer, integer) :: 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.

delete_guild(guild_id)
delete_guild(integer) :: error | {:ok}

Deletes a guild.

Guild to delete specified by guild_id.

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

Deletes a guild integeration.

Integration to delete is specified by guild_id and integeration_id.

delete_guild_role(guild_id, role_id)
delete_guild_role(integer, integer) :: error | {:ok}

Deletes a guild role.

Role to delte is specified by guild_id and role_id

delete_invite(invite_code)
delete_invite(integer) :: error | {:ok, Nostrum.Struct.Invite.t}

Deletes an invite.

Invite to delete is specified by invite_code.

delete_message(channel_id, message_id)
delete_message(integer, integer) :: error | {:ok}

Delete a message.

Delete a message specified by channel_id and message_id.

Returns {:ok} if successful. error otherwise.

delete_message!(channel_id, message_id)
delete_message!(String.t, integer) :: no_return | {:ok}

Delete a message.

Delete a message specified by channel_id and message_id.

Raises Nostrum.Error.ApiError if error occurs while making the rest call. Returns {:ok} if successful.

delete_own_reaction(channel_id, message_id, emoji)

Deletes a rection made by the user.

Reaction to delete is specified by channel_id, message_id, and emoji.

Returns {:ok} if successful, {:error, reason} otherwise.

delete_pinned_message(channel_id, message_id)
delete_pinned_message(integer, integer) :: error | {:ok}

Unpins a message.

Unpins the message specified by message_id in the channel specified by channel_id.

Returns {:ok} if successful. error otherwise.

delete_pinned_message!(channel_id, message_id)
delete_pinned_message!(integer, integer) :: no_return | {:ok}

Unpins a message.

Unpins the message specified by message_id in the channel specified by channel_id.

Raises Nostrum.Error.ApiError if error occurs while making the rest call. Returns {:ok} if successful.

delete_reaction(channel_id, message_id, emoji, user_id)
delete_reaction(integer, integer, String.t | Nostrum.Struct.Emoji.custom_emoji, integer) ::
  error |
  {:ok}

Deletes a rection from a message.

Reaction to delete is specified by channel_id, message_id, emoji, and user_id.

Returns {:ok} if successful, {:error, reason} otherwise.

delete_webhook(webhook_id)
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(channel_id, options)
edit_channel(integer, name: String.t, position: integer, topic: String.t, bitrate: String.t, user_limit: integer) ::
  error |
  {:ok, Nostrum.Struct.Channel.t}

Edit a channel.

Edits a channel with options

options is a kwl with the following optional keys:

  • name - New name of the channel.
  • position - Position of the channel.
  • topic - Topic of the channel. Text Channels only
  • bitrate - Bitrate of the voice channel. Voice Channels only
  • user_limit - User limit of the channel. 0 for no limit. Voice Channels only
edit_channel!(channel_id, options)
edit_channel!(integer, name: String.t, position: integer, topic: String.t, bitrate: String.t, user_limit: integer) ::
  error |
  {:ok, Nostrum.Struct.Channel.t}

Edit a channel.

See edit_channel/2 for parameters.

Raises Nostrum.Error.ApiError if error occurs while making the rest call.

edit_channel_permissions(channel_id, overwrite_id, permission_info)
edit_channel_permissions(integer, integer, allow: integer, deny: integer, type: String.t) ::
  error |
  {:ok}

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)
edit_channel_permissions!(integer, integer, allow: integer, deny: integer, type: String.t) ::
  no_return |
  {:ok}

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_guild(guild_id, options)
edit_guild(integer, %{name: String.t, region: String.t, verification_level: integer, default_message_notifications: boolean, afk_channel_id: integer, afk_timeout: integer, icon: String.t, owner_id: integer, splash: String.t}) ::
  error |
  {:ok, Nostrum.Struct.Guild.t}

Modify a guild’s settings.

options is a map with the following optional keys:

  • name - Guild name.
  • region - Guild voice region id.
  • verification_level - Guild verification level.
  • default_message_notifications - Notifications setting.
  • afk_channel_id - Id for afk channel.
  • afk_timeout - Afk timeout in seconds.
  • icon - Base64 encoded 128x128 jpeg image for guild icon.
  • owner_id - User id to transfer guild ownership to.
  • splash - Base64 encoded 128x128 jpeg image for guild splash.
edit_message(channel_id, message_id, content)
edit_message(integer, integer, String.t) ::
  error |
  {:ok, Nostrum.Struct.Message.t}

Edit a message.

Edit a message with the given content. Message to edit is specified by channel_id and message_id.

Returns the edited {:ok, Nostrum.Struct.Message} if successful. error otherwise.

edit_message!(channel_id, message_id, content)
edit_message!(integer, integer, String.t) ::
  no_return |
  {:ok, Nostrum.Struct.Message.t}

Edit a message.

Edit a message with the given content. Message to edit is specified by channel_id and message_id.

Raises Nostrum.Error.ApiError if error occurs while making the rest call. Returns the edited Nostrum.Struct.Message if successful.

execute_git_webhook(webhook_id, webhook_token, wait \\ false)
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)
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)
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 to false.

Only one of content, file or embed should be supplied in the args parameter.

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

Get a channel.

Gets a channel specified by id.

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

Get a channel.

Gets a channel specified by id.

Raises Nostrum.Error.ApiError if error occurs while making the rest call.

get_channel_invites(channel_id)
get_channel_invites(integer) ::
  error |
  {:ok, [Nostrum.Struct.Invite.t]}

Gets a list of invites for a channel.

Channel to get invites for is specified by channel_id

get_channel_message(channel_id, message_id)
get_channel_message(integer, integer) ::
  error |
  {:ok, Nostrum.Struct.Message.t}

Retrieves a message from a channel.

Message to retrieve is specified by message_id and channel_id.

get_channel_message!(channel_id, message_id)
get_channel_message!(integer, integer) ::
  no_return |
  Nostrum.Struct.Message.t

Retrieves a message from a channel.

Raises Nostrum.Error.ApiError if error occurs while making the rest call.

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

Retrieve messages from a channel.

Retrieves limit number of messages from the channel with id channel_id. locator is a tuple indicating what messages you want to retrieve.

Returns {:ok, [Nostrum.Struct.Message]} if successful. error otherwise.

get_channel_messages!(channel_id, limit, locator)
get_channel_messages!(integer, limit, locator) ::
  no_return |
  [Nostrum.Struct.Message.t]

Retrieve messages from a channel.

See get_channel_message/3 for usage.

Raises Nostrum.Error.ApiError if error occurs while making the rest call.

get_channel_messages_call(channel_id, limit, locator)
get_channel_webhooks(channel_id)

Gets a list of webook for a channel.

Parameters

  • channel_id - Channel to get webhooks for.
get_channels(guild_id)
get_channels(integer) :: error | {:ok, Nostrum.Struct.Channel.t}

Gets a list of channels.

Guild to get channels for is specified by guild_id.

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

Gets info on the current user.

get_current_users_guilds(options)
get_current_users_guilds(%{before: integer, after: integer, limit: integer}) ::
  error |
  {:ok, [Nostrum.Struct.Guild.t]}

Gets a list of guilds the user is currently in.

options is a map with the following optional keys:

  • before - Get guilds before this ID.
  • after - Get guilds after this ID.
  • limit - Max number of guilds to return.
get_guild(guild_id)
get_guild(integer) :: error | {:ok, Nostrum.Struct.Guild.t}

Gets a guild using the REST api

Retrieves a guild with specified guild_id.

Returns {:ok, Nostrum.Struct.Guild.t} if successful, error otherwise.

get_guild!(guild_id)
get_guild!(integer) :: no_return | Nostrum.Struct.Guild.t

Gets a guild using the REST api

Retrieves a guild with specified guild_id.

Raises Nostrum.Error.ApiError if error occurs while making the rest call. Returns Nostrum.Struct.Guild.t if successful.

get_guild_bans(guild_id)
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_embed(guild_id)
get_guild_embed(integer) :: error | {:ok, map}

Gets a guild embed.

get_guild_integrations(guild_id)
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)
get_guild_invites(integer) ::
  error |
  {:ok, [Nostrum.Struct.Invite.t]}

Gets a list of invites for a guild.

Guilds to get voice regions for is specified by guild_id.

get_guild_members(guild_id, options)
get_guild_members(integer, limit: 1..1000, after: integer) ::
  error |
  {:ok, [Nostrum.Struct.Guild.Member.t]}

Gets a list of guild members.

Guild to get members for is specified by guild_id.

options is a keyword list with the following optional keys:

  • limit - Max number of members to return (1-1000).
  • after - Highest user id of the previous page.
get_guild_prune(guild_id, options)
get_guild_prune(integer, integer) ::
  error |
  {:ok, %{pruned: integer}}

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

Guild to get prune number for is specified by guild_id. Days is that number of days to count prune for.

get_guild_roles(guild_id)
get_guild_roles(integer) ::
  error |
  {:ok, Nostrum.Struct.Guild.Role.t}

Gets a guild’s roles.

Guild to get roles for is specified by guild_id.

get_guild_webhooks(guild_id)
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)
get_invite(integer) :: error | {:ok, Nostrum.Struct.Invite.t}

Gets an invite.

Invite to get is specified by invite_code.

get_member(guild_id, user_id)
get_member(integer, integer) ::
  error |
  {:ok, Nostrum.Struct.Guild.Member.t}

Gets a guild member.

Member to get is specified by guild_id and user_id.

get_pinned_messages(channel_id)
get_pinned_messages(integer) ::
  error |
  {:ok, [Nostrum.Struct.Message.t]}

Gets all pinned messages.

Retrieves all pinned messages for the channel specified by channel_id.

Returns {:ok, [Nostrum.Struct.Message.t]} if successful. error otherwise.

get_pinned_messages!(channel_id)
get_pinned_messages!(integer) ::
  no_return |
  [Nostrum.Struct.Message.t]

Gets all pinned messages.

Retrieves all pinned messages for the channel specified by channel_id.

Returns [Nostrum.Struct.Message.t] if successful. error otherwise.

get_reactions(channel_id, message_id, emoji)
get_reactions(integer, integer, String.t | Nostrum.Struct.Emoji.custom_emoji) ::
  error |
  {:ok, [Nostrum.Struct.User]}

Gets all users who reacted with an emoji.

Retrieves a list of users who have reacted with an emoji.

Returns {:ok, [Nostrum.Struct.User]} if successful, {:error, reason} otherwise.

get_token()
get_token() :: String.t

Returns the token of the bot.

get_user(user_id)
get_user(integer) :: error | {:ok, Nostrum.Sturct.User.t}

Gets a user.

User to get is specified by user_id.

get_user_connections()
get_user_connections ::
  error |
  {:ok, Nostrum.Struct.User.Connection.t}

Gets a list of user connections.

get_user_dms()
get_user_dms() :: error | {:ok, [Nostrum.Struct.DMChannel.t]}

Gets a list of user DM channels.

get_voice_region(guild_id)
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)

Gets a webhook by id.

Parameters

  • webhook_id - Id of webhook to get.
get_webhook_with_token(webhook_id, webhook_token)

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)
leave_guild(integer) :: error | {:ok}

Leaves a guild.

Guild to leave is specified by guild_id.

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

Gets a list of voice regions.

modify_channel_position(guild_id, options)
modify_channel_position(integer, [%{id: integer, position: integer}]) ::
  error |
  {:ok, [Nostrum.Struct.Guild.Channel.t]}

Reorders a guild’s channels.

Guild to modify channels for is specified by guild_id.

options is a list of maps with the following keys:

  • id - Id of the channel.
  • position - Sorting position of the channel.
modify_current_user(options)

Changes the username or avatar of the current user.

Example

avatar = %{avatar: "data:image/jpeg;base64," <> "YXl5IGJieSB1IGx1a2luIDQgc3VtIGZ1az8="}
{:ok, user} = Nostrum.Api.modify_current_user(avatar)

options is a map with the following optional keys:

  • username - New username.
  • avatar - Base64 encoded image data, prepended with data:image/jpeg;base64,
modify_guild_embed(guild_id, options)
modify_guild_embed(integer, map) :: error | {:ok, map}

Modifies a guild imbed.

modify_guild_integrations(guild_id, integration_id, options)
modify_guild_integrations(integer, integer, %{expire_behaviour: integer, expire_grace_period: integer, enable_emoticons: boolean}) ::
  error |
  {:ok}

Changes the settings and behaviours for a guild integeration.

Integration to modify is specified by guild_id and integeration_id.

options is a map with the following keys:

  • expire_behavior - Expiry behavior.
  • expire_grace_period - Period where the integration will ignore elapsed subs.
  • enable_emoticons - Whether emoticons should be synced.
modify_guild_role(guild_id, role_id, options)
modify_guild_role(integer, integer, name: String.t, permissions: integer, color: integer, hoist: boolean, mentionable: boolean) ::
  error |
  {:ok, Nostrum.Struct.Guild.Role.t}

Modifies a guild role.

Role to modify specified by guild_id and role_id.

options is a keyword list with the following optional keys:

  • name - Name of the role.
  • permissions - Bitwise of the enabled/disabled permissions.
  • color - RGB color value.
  • hoist - Whether the role should be displayed seperately in the sidebar.
  • mentionable - Whether the role should be mentionable.
modify_guild_role_positions(guild_id, options)
modify_guild_role_positions(integer, [%{id: integer, position: integer}]) ::
  error |
  {:ok, [Nostrum.Struct.Guild.Role.t]}

Reorders a guild’s roles.

Guild to modify roles for is specified by guild_id.

options is a list of maps with the following keys:

  • id - Id of the role.
  • position - Sorting position of the role.
modify_member(guild_id, user_id, options)
modify_member(integer, integer, %{nick: String.t, roles: [integer], mute: boolean, deaf: boolean, channel_id: integer}) ::
  error |
  {:ok, Nostrum.Struct.Guild.Member.t}

Modifies a guild member.

Member to modify is specified by guild_id and user_id

options is a map with the following option keys:

  • nick - Users nickname.
  • roles - Array of roles to give member.
  • mute - If the user should be muted.
  • deaf - If the user should be deafaned.
  • channel_id - Id of the channel to move the user to.
modify_webhook(webhook_id, args)
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)
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)
remove_guild_ban(integer, integer) :: error | {:ok}

Removes a ban for a user.

User to unban is specified by guild_id and user_id.

remove_guild_member_role(guild_id, user_id, role_id)
remove_guild_member_role(integer, integer, integer) ::
  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.

remove_member(guild_id, user_id)
remove_member(integer, integer) :: error | {:ok}

Removes a memeber from a guild.

Member to remove is specified by guild_id and user_id.

request(method, route, body \\ "", options \\ [])
request_multipart(method, route, body \\ "", options \\ [])
start_typing(channel_id)
start_typing(integer) :: error | {:ok}

Triggers the typing indicator.

Triggers the typing indicator in the channel specified by channel_id. The typing indicator lasts for about 8 seconds and then automatically stops.

Returns {:ok} if successful. error otherwise.

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

Triggers the typing indicator.

Triggers the typing indicator in the channel specified by channel_id. The typing indicator lasts for about 8 seconds and then automatically stops.

Raises Nostrum.Error.ApiError if error occurs while making the rest call. Returns {:ok} if successful.

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

Syncs a guild integration.

Integration to sync is specified by guild_id and integeration_id.

update_status(status, game)
update_status(status, String.t) :: no_return

Updates the status of the bot for all shards.

For more information see Nostrum.Api.update_status/3

update_status(pid, status, game)
update_status(pid, status, String.t) :: no_return

Updates the status of the bot for a certain shard.

pid is the pid of the shard whose status you want to update. To update the status for all shards see Nostrum.Api.update_status/2 status is an atom that describes the status of the bot. See Nostrum.Api.status.t for available options. game is the text that will display ‘playing’ status of the game. This is the text below the bot’s name in the sidebar. Empty string will clear.