Voyager | A Roblox API wrapper for Discord webhooks

Voyager_Banner




What is Voyager?

Voyager is a Roblox API wrapper for Discord webhooks.




Why should I use Voyager?

Voyager makes interacting with Discord webhooks much easier, as you not only write less code but the code you do write is much more readable too, this results in a much better developer experience. Voyager also has very good API coverage over Discord’s webhook API, so no matter how niche your use case is, Voyager can most likely help you out!




How can I start using Voyager?

  1. First you need a webhook to send requests to. You can follow this short tutorial by Discord on how to set up a webhook.

  2. Get the module script.

  3. Make sure http requests in Game Settings > Security is enabled.

  4. Drag the module into your project and place it in ServerScriptService or ServerStorage.




Code examples

Example 1: Sending a message

local Voyager = path_here.Voyager
local webhook = require(Voyager.Webhook).new("webhookId", "webhookToken")

webhook:execute("Hello, World!")

Example 1 Expected Output




Example 2: Sending a message with embedded content

local Voyager = path_here.Voyager
local webhook = require(Voyager.Webhook).new("webhookId", "webhookToken")
local embed = require(Voyager.Embed).new("Voyager is really useful!")

webhook:execute(nil, {embed})

Example 2 Expected Output




Example 3: Sending a message to a thread

local Voyager = path_here.Voyager
local webhook = require(Voyager.Webhook).new("webhookId", "webhookToken")
local optionalExecuteInfo = require(Voyager.OptionalExecuteInfo).new("threadId")

webhook:execute("Nice thread 👌", nil, nil, nil, optionalExecuteInfo)

Example 3 Expected Output




Example 4: Sending a TTS message

local Voyager = path_here.Voyager
local webhook = require(Voyager.Webhook).new("webhookId", "webhookToken")
local optionalExecuteInfo = require(Voyager.OptionalExecuteInfo).new(nil, true)

webhook:execute("This is a tts message!", nil, nil, nil, optionalExecuteInfo)

Note: Do keep in mind that you have to be in the channel before the message is sent, otherwise it will not play for you.




Example 5: Obtaining a Message object

local Voyager = path_here.Voyager
local webhook = require(Voyager.Webhook).new("webhookId", "webhookToken")
local message, requestInfo = webhook:execute("Hello, World!", nil, false, true)

if requestInfo.success then
    print(message.id)
end

Example 5 Expected Output
Example 5 Expected Output




Can Voyager do more than just send messeges?

Yes! Voyager can also edit and delete messeges sent by the webhook.

How can I edit a message with Voyager?

local Voyager = path_here.Voyager
local webhook = require(Voyager.Webhook).new("webhookId", "webhookToken")

webhook:editMessage("messageId", "Hello, there!")

Before:

Message Before

After:

Image After

How can I delete a message with Voyager?

local Voyager = path_here.Voyager
local webhook = require(Voyager.Webhook).new("webhookId", "webhookToken")

webhook:deleteMessage("messageId")



With Voyager vs without Voyager

See an example here.




Credit

Huge thanks to @lewisakura for creating and hosting the proxy used in this module. Without them this module wouldn’t have been possible.




Documentation

The full documentation can be found here.




Github

The github can be found here.




31 Likes

Very cool! I will use this in my game to make it easier for moderators to view flagged content :slight_smile:

4 Likes

Hmmm yes seems very cool will use later vouch vouch

3 Likes

Change the name. There’s already a resource for Discord Webhooks (Not for Roblox) called Discohook. You should look up the names you’re going to use before you actually use them…

3 Likes

There’s already a resource for Discord Webhooks

Personally I don’t see the issue with the name, both utilities can exist with the same name, there is a huge difference between utilities as one is a Roblox API wrapper and the other is a website, while yes both do similar things like sending messages through Discord webhooks, it does not justify a rename.

But if enough people want a rename then I’ll happily rename it, but at the current moment I don’t see any benefit and I’d much rather spend my time improving the module rather than waste time renaming it.

1 Like

I was only telling you to rename the resource because people looking for this could find the other resource & get confused searching for the Roblox stuff and not finding anything, and vice versa, but I doubt they’ll do anything about it so if you want to, I guess you could keep the name.

1 Like

Your module is amazingly made and super useful. I love to see work such as yours that developers spend lots of time and love on. I will most likely use your module for an advanced feedback system.

1 Like

would be cool if you found a way to implement features like these

That’s a completely different Discord field.

This resource is for webhooks, not Discord Bots.

1 Like

:tada: v2.2.0 is here! :tada:


New stuff


  • Voyager now supports self hosted WebhookProxys.

  • thread_name support for forum channels.

  • Reworked the way Voyager handles flags to be easier to use.

  • Improved request validation.

  • Bug fixes.

  • Better code quality.



Breaking changes


  • Removed User:hasFlag

  • Removed User:getFlags


  • Embed:setImage(url, height, width) → Embed:setImage(url)

  • Embed:setThumbnail(url, height, width) → Embed:setThumbnail(url)


  • User.publicFlags: number → User.publicFlags: PublicUserFlags

  • Message.flags: number → Message.flags: MessageFlags


  • Webhook.Enum.AvatarImageFormats.jpeg → Webhook.Enum.AvatarImageFormats.JPEG

  • Webhook.Enum.AvatarImageFormats.png → Webhook.Enum.AvatarImageFormats.PNG

  • Webhook.Enum.AvatarImageFormats.webp → Webhook.Enum.AvatarImageFormats.WebP

  • Webhook.Enum.AvatarImageFormats.gif → Webhook.Enum.AvatarImageFormats.GIF



Full change log


  • Added BaseFlags object

  • Added PublicUserFlags object

  • Added MessageFlags object


  • Webhook constructor has a new parameter: customProxyUrl

  • Webhook:_validateExecuteRequest’s third parameter now takes an OptionalExecuteInfo object and has been renamed to optionalExecuteInfo


  • Embed:setImage now only takes the url parameter

  • Embed:setThumbnail now only takes the url parameter


  • OptionalExecuteInfo constructor has 2 new parameters messageFlags and threadName

  • OptionalExecuteInfo now has 2 new properties OptionalExecuteInfo.messageFlags and OptionalExecuteInfo.threadName


  • User.publicFlags now returns a PublicUserFlags object instead of a bitfield

  • Removed User:hasFlag

  • Removed User:getFlags


  • Message.flags now returns a MessageFlags object instead of a bitfield

  • Webhook.Enum.AvatarImageFormats.jpeg → Webhook.Enum.AvatarImageFormats.JPEG

  • Webhook.Enum.AvatarImageFormats.png → Webhook.Enum.AvatarImageFormats.PNG

  • Webhook.Enum.AvatarImageFormats.webp → Webhook.Enum.AvatarImageFormats.WebP

  • Webhook.Enum.AvatarImageFormats.gif → Webhook.Enum.AvatarImageFormats.GIF



TL;DR


This new version of Voyager mainly consists of internal code changes to improve code quality and maintainability. However, there are a few new features such as better flag handling, thread_name support for forum channels, support for self-hosted WebhookProxys and even better request validation. Unfortunately, there are some breaking changes. Be sure to check the list of breaking changes before switching version, moving forward deprecation will be used instead.



Thank you


I would like to thank all of you for your support. Your kind words are what motivates me to keep working on this project. Even if you didn’t leave a comment, simply giving this project the time of day to check out on the devforum means everything to me.


:tada: v2.3.0 is here! :tada:


New stuff


  • Discohook has been renamed to Voyager

  • The structure of the lib has changed, now all the module scripts are kept inside a folder.

  • Enum has moved from the Webhook module script into Voyager/utilities

  • Documentation has been moved to a mkdocs site

  • Documentation site now has a tutorial section

  • Added use case examples to github repo

  • Added Webhook:_request

  • Added Webhook:_validateEditMessageRequest

  • Webhook:execute’s queue and waitForMessage params are now optional

  • Webhook object got a new property ratelimitInfo

  • Webhook methods like :_request, :execute, :editMessage, :deleteMessage now return a table containing information about the request’s status.

  • Added User.globalName

  • Removed Embed:toDictionary

  • Bug fixes

  • Improvements to internal code



Deprecations


  • Author.discriminator

  • User.discriminator

  • User.displayName



TL;DR


Discohook has been renamed to Voyager. New documintation site is here! Stop using Author.discriminator, User.discriminator, User.displayName as they have been deprecated. Version 2.3.1 will most likely remove all deprecated properties. The structure of the lib has changed, now all the module scripts are kept inside a folder.



What’s next?


Unfortunately, for the foreseeable future no new features will be coming to Voyager. In addition to this, I as the main maintainer will not be searching the codebase for bugs anymore. The reason I’ve decided to do this is because Voyager has become robust enough to not warrent this anymore. I will still maintain Voyager with bug fixes, if bugs are reported to the github. also Voyager already covers a good amount of Discord’s webhook API, the things that have been left out of Voyager are things that I see as having no use case.


1 Like

:tada: v2.4.0 is here! :tada:


New stuff


  • Added Webhook.fromUrl()

  • Added Message.jumpUrl

  • Added Message.createdAt

  • Added EditedMessage.editedAt

  • Added EditedThreadMessage.editedAt

  • Revamped manual ratelimiting (now actually useable!)

  • Added RatelimitInformation type

  • Added RatelimitedInformation type

  • Webhook methods _request, execute, editMessage and deleteMessage now also return a dictionary of either type RatelimitInformation or RatelimitedInformation

  • Added RequestStatus.message

  • Added RequestStatus.reason

  • Bug fixes

  • Improvements to internal code



Deprecations


  • Message.timestamp

  • EditedMessage.editedTimestamp

  • EditedThreadMessage.editedTimestamp

  • Webhook.ratelimitInfo

  • RatelimitInfo Type



What’s next?


  • Publishing Voyager to a Roblox package manager like Wally.

  • Moving Voyager to a new OOP idiom, one in particular that caught my attention was the idiom discovered by @darmantinjr, the pros of moving to this idiom are in the devform post, but to put it in short I feel like it would improve internal code quality and developer experience in general. Since this change is quite big I would love to hear what you all think about it in a poll below, the results will help me finalise the decision on whether or not to implement this change.

  • Refactoring the Webhook class’s methods. The first change I’d make to them is renaming the execute method to sendMessage or something similar, then I’d split up the methods into two different methods to reflecting this format → editMessage, editMessageInThread for example, this would serve to make code more readable.

  • Small refactor to the Embed class as I feel like it does not abstract enough from the API, examples of this being the color and timestamp properties being the raw values sent to the API.

  • Change from camel case to pascal case to match roblox’s official styling. example: Webhook:editMessage()Webhook:EditMessage()

That’s all I currently have in mind for Voyager at the moment, please do note that all the above are subject to change! Any breaking changes mentioned will not be added in v2 of Voyager. If you have any thoughts you would like to share with me on the changes mentioned here please do let me know. Thanks for reading!



Idiom Change
  • I am in support of this change.
  • I am not in support of this change.

0 voters

1 Like

:tada: v2.5.0 is here! :tada:


New stuff


  • Added utility MentionFormatter

  • Added utility EmojiFormatter

  • Added utility DateFormatter

  • Added property Author.mention

  • Added enum AvatarImageFormats.WEBP

  • Added enum MessageFlags.SUPPRESS_NOTIFICATIONS

  • Added method MessageFlags:getFlags()

  • Typing improvements

  • Improvements to internal code



Deprecations


  • Class Emoji

  • Class Reaction

  • Property Message.reactions



What’s next?


Hopefully the release of v3! I’ve begun planning what changes should take place in v3, unfortunately it’s still a little early to say what I have in mind, but in the coming weeks I should be able to finish up planning. I know that some of you may have some questions, so I will leave a short Q&A below.

Q: Will new features be added to v2 while v3 is being developed?
A: No, I will only supply v2 with bugfixes until v3 is released.

Q: How long will v3 take to develop?
A: While I’m unsure how long the development process will be, I can say for sure that it wont be here anytime soon.

Q: How will I know how to migrate my v2 code to v3?
A: I will create a code migration guide which will be found in the documentation.


2 Likes

sorry everyone, I accidentally posted the v3 release notes while writing them.

1 Like