Managing messages - SinisterRectus/Discordia GitHub Wiki

Messages are a huge part of the Discord API. Being able to interact with and construct them is essential to proper bot creation. For general information regarding properties and methods, see the Message page.

Events

Discordia has 9 events that correspond to messages:

  • messageCreate
  • messageUpdate
  • messageDelete
  • messageUpdateUncached
  • messageDeleteUncached
  • reactionAdd
  • reactionRemove
  • reactionAddUncached
  • reactionRemoveUncached

Visit the events page for more information.

Caching and Querying Messages

Discordia stores messages with weak references. This means that if a message is not strongly referenced somewhere, it will be cleaned up during the next garbage collection cycle. This is done so that messages can be retained while they are referenced from other locations, but volatile when memory limitations prevent messages from accumulating infinitely.

Every TextChannel has a messages cache property associated with it. If you want to access cached messages, use the standard methods for Iterable classes.

A variety of TextChannel methods may also be used to access channel messages. See TextChannel.

Sending Messsages

Messages can be sent to different destinations by two different methods. The destination can be either a PrivateChannel, GuildTextChannel, GroupChannel, User, Member, or Relationship instance.

Simple message formatting

channel:send("Hello!")

This is used when you just want to send a simple string to a channel. Remember that send returns a Message object when successful, or nil, err when it is not.

Advanced message formatting

You can also use a table to format your outgoing message. Acceptable fields are explained below.

content

must be a Lua string. Due to limitations in unicode handling, characters outside of the printable range of ASCII characters may prevent a message from being sent.

channel:send {
  content = "Hello!"
}

tts

a boolean indicating whether the content is interpreted as text-to-speech. You must have appropriate permissions to send these messages and other users must have them enabled to hear them.

channel:send {
  content = "Hello!",
  tts = true
}

nonce

a custom value used to identify a message. Use of this property is not recommended.

channel:send {
  content = "Hello!",
  nonce = 1234
}

embed

a Lua table that produces a rich-formatted message. It must match the object outlined by the official Discord docs, including snake_case formatting. A content field is not required if embed is sent.

message.channel:send {
  embed = {
    title = "This is an embed!",
    fields = {
      {name = "Field 1", value = "Some information", inline = true},
      {name = "Field 2", value = "More information", inline = true},
    },
    color = discordia.Color.fromRGB(114, 137, 218).value,
    timestamp = discordia.Date():toISO('T', 'Z')
  }
}

Note that color must be a number and timestamp must be an ISO8601 string.

file

a relative or full path to a file to upload with the message, or, a table with a filename and raw file content as a string.

channel:send {
  file = "lolcat.jpg",
}

channel:send {
  file = {"document.txt", "This is a text document."}
}

files

an array of files as defined above. This can be used simultaneously with the file field.

channel:send {
  files = {
    "lolcat.jpg",
    "other.txt",
    {"document.txt", "This is a multi-file upload."}
  }
}

mention

a mentionable object whose mentionString property will be prepended to the message content.

channel:send {
  content = "Hello!",
  mention = message.author,
}

mentions

an array of mentionable objects as defined above. This can be used simultaneously with the mention field.

channel:send {
  content = "Hello!",
  mentions = {message.author, client.owner},
}

code

indicates whether to wrap the content in a markdown-formatted codeblock. If a string is passed, it is used to define the formatting style; otherwise, if true is passed, neutral formatting is used.

channel:send {
  content = "local foo = 'bar'",
  code = "lua"
}

reference

a Lua table that indicates a reply, where the message field is a Message-ID-Resolvable representing the message being replied to, and the mention field is a boolean indicating whether to mention the user being replied to.

channel:send {
  content = "Hello!",
  reference = {
    message = message,
    mention = false,
  }
}

Editing Messages

Discordia applications can edit the content and embeds of their own messages with a mutator method:

message:setContent("Goodbye!")
message:setEmbed {
  description = "edited",
  color = discordia.Color.fromHex("#FFFFFF").value
}

Reactions

You can use Discordia to add and remove reactions to and from messages (assuming that your account has permissions to do so). For custom emojis, you must use an emoji object. For standard unicode emojis, you can use either a unicode character or unicode string:

local emoji = guild.emojis:find(function(e) return e.name == 'Lua' end)
message:addReaction(emoji)
message:addReaction("👍")
message:addReaction("\240\159\145\140")
message:removeReaction("👍")