@spec clear_reactions(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  Nostrum.Api.error() | {:ok}

Deletes all reactions from a message.

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

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

@spec create(
  Nostrum.Struct.Channel.id() | Nostrum.Struct.Message.t(),
  Nostrum.Api.options() | String.t()
) :: Nostrum.Api.error() | {:ok, Nostrum.Struct.Message.t()}

Posts a message to a guild text or DM channel.

This endpoint requires the VIEW_CHANNEL and SEND_MESSAGES permissions. It may situationally need the SEND_MESSAGES_TTS permission. It fires the Nostrum.Consumer.message_create/0 event.

If options is a string, options will be used as the message's content.

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

Options

• :content (string) - the message contents (up to 2000 characters)
• :nonce (Nostrum.Snowflake.t/0) - a nonce that can be used for optimistic message sending
• :tts (boolean) - true if this is a TTS message

• :file (Path.t/0 | map) - the path of the file being sent, or a map with the following keys if sending a binary from memory

  • :name (string) - the name of the file
  • :body (string) - binary you wish to send
• :files - a list of files where each element is the same format as the :file option. If both :file and :files are specified, :file will be prepended to the :files list.
• :embeds (Nostrum.Struct.Embed.t/0) - a list of embedded rich content
• :allowed_mentions (t:allowed_mentions/0) - see the allowed mentions type documentation
• :message_reference (map) - See "Message references" below
• :poll (Nostrum.Struct.Message.Poll.t/0) - A poll object to send with the message

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

Message reference

You can create a reply to another message on guilds using this option, given that you have the VIEW_MESSAGE_HISTORY permission. To do so, include the message_reference field in your call. The complete structure documentation can be found on the Discord Developer Portal, but simply passing message_id will suffice:

def my_command(msg) do
  # Reply to the author - ``msg`` is a ``Nostrum.Struct.Message``
  Nostrum.Api.Message.create(
    msg.channel_id,
    content: "Hello",
    message_reference: %{message_id: msg.id}
  )
end

Passing a list will merge the settings provided

Examples

Nostrum.Api.Message.create(43189401384091, content: "hello world!")

Nostrum.Api.Message.create(43189401384091, "hello world!")

import Nostrum.Struct.Embed
embed =
  %Nostrum.Struct.Embed{}
  |> put_title("embed")
  |> put_description("new desc")
Nostrum.Api.Message.create(43189401384091, embeds: [embed])

Nostrum.Api.Message.Message.create(43189401384091, file: "/path/to/file.txt")

Nostrum.Api.Message.create(43189401384091, content: "hello world!", embeds: [embed], file: "/path/to/file.txt")

Nostrum.Api.Message.create(43189401384091, content: "Hello @everyone", allowed_mentions: :none)

@spec delete(Nostrum.Struct.Message.t()) :: Nostrum.Api.error() | {:ok}

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

@spec delete(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  Nostrum.Api.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.Message.delete(43189401384091, 43189401384091)

@spec delete_emoji_reactions(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  Nostrum.Api.emoji()
) :: Nostrum.Api.error() | {:ok}

Deletes all reactions of a given emoji from a message.

This endpoint requires the MANAGE_MESSAGES permissions. It fires a Nostrum.Consumer.message_reaction_remove_emoji/0 event.

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

See react/3 for similar examples.

@spec delete_user_reaction(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  Nostrum.Api.emoji(),
  Nostrum.Struct.User.id()
) :: Nostrum.Api.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 react/3 for similar examples.

@spec edit(Nostrum.Struct.Message.t(), Nostrum.Api.options()) ::
  Nostrum.Api.error() | {:ok, Nostrum.Struct.Message.t()}

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

@spec edit(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  Nostrum.Api.options() | String.t()
) ::
  Nostrum.Api.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)
• :embeds (Nostrum.Struct.Embed.t/0) - a list of embedded rich content
• :files - a list of files where each element is the same format as the :file option. If both :file and :files are specified, :file will be prepended to the :files list. See create_message/2 for more information.

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

Examples

Nostrum.Api.Message.edit(43189401384091, 1894013840914098, content: "hello world!")

Nostrum.Api.Message.edit(43189401384091, 1894013840914098, "hello world!")

import Nostrum.Struct.Embed
embed =
  %Nostrum.Struct.Embed{}
  |> put_title("embed")
  |> put_description("new desc")
Nostrum.Api.Message.edit(43189401384091, 1894013840914098, embeds: [embed])

Nostrum.Api.Message.edit(43189401384091, 1894013840914098, content: "hello world!", embeds: [embed])

@spec get(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) ::
  Nostrum.Api.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.Message.get(43189401384091, 198238475613443)

@spec react(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  Nostrum.Api.emoji()
) ::
  Nostrum.Api.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.Message.react(123123123123, 321321321321, emoji)

# Using a base 16 emoji string.
Nostrum.Api.Message.react(123123123123, 321321321321, "\xF0\x9F\x98\x81")

For other emoji string examples, see Nostrum.Struct.Emoji.api_name/0.

@spec reactions(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  Nostrum.Api.emoji(),
  keyword()
) :: Nostrum.Api.error() | {:ok, [Nostrum.Struct.User.t()]}

Gets all users who reacted with an emoji.

This endpoint requires the VIEW_CHANNEL and READ_MESSAGE_HISTORY permissions.

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

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

See react/3 for similar examples.

@spec unreact(
  Nostrum.Struct.Channel.id(),
  Nostrum.Struct.Message.id(),
  Nostrum.Api.emoji()
) ::
  Nostrum.Api.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 react/3 for similar examples.