DiscordHook - Easy to use library for sending Discord messages from CC

Started by HydroNitrogen, Feb 05, 2019, 07:03 PM

Previous topic - Next topic

HydroNitrogen

About

DiscordHook is an easy-to-use lua library for connecting ComputerCraft to Discord. You can connect a webhook and send easy simple messages, beautiful custom emneds and advanced raw json.



Downloading

DiscordHook is available on GitHub here. You can check out its repo, or download the library file directly by executing the following in your terminal:

wget https://raw.githubusercontent.com/Wendelstein7/DiscordHook-CC/master/DiscordHook.lua DiscordHook.lua


Documentation

DiscordHook has a few functions you can use. To harness DiscordHook's power, we must first load it into our environment by doing the following:

local DiscordHook = require("DiscordHook")
Now we can access DiscordHook's Functions:

local success, hook = DiscordHook.createWebhook("https://discordapp.com/api/webhooks/... (THE URL YOU GOT FROM DISCORD)")
 if not success then
  error("Webhook connection failed! Reason: " .. hook)
 end

 -- If the code execution continues here, that means we have the webhook available as it didn't error.

Getting a Discord webhook URL:

To get a webhook URL, you will need to 'create' such URL from inside the Discord (web)application.

First, make sure you're a moderator or administrator in a Discord server or create a new Discord server. Then, go to the server settings and tap 'Webhooks' on your left bar. Now, click 'Create Webhook' on the top-right. A Webhook is now created for you. It's bound to a specific channel. Copy (use the button) and paste down the webhook url, as you'll need this later in your CC program!

Using your webhook:

There are three functions you can call from your webhook object in lua:

-- Sending normal plain good ol' messages:
 hook.send(<string message>, [string username], [string avatarurl])
 
 -- If you want to compose the message json yourself:
 hook.sendJSON(<string json>)
 
 -- If you want to create a fancy embed:
 hook.sendEmbed(<string message>, [string title], [string description], [string hyperlink-url], [number colour], [string image-url], [string thumbnail-url], [string username], [string avatar])

Notes:

All functions return a boolean - true if the webhook executed without problems or false if the webhook failed (for example, when Discord rejected an invalid embed.)

By Discord's rules, an embed must atleast either have a title or description, but not neccecarily both.

Fill arguments you don't want with nil, for example: hook.sendEmbed( "", nil, "Hello!", nil, 0xFF00FF ) and hook.send( "Hello sir!", nil, "https://example.com/avatar.jpg" ) will work just fine!

A string for message is always required, but is allowed to be empty ("") when having a valid embed.


Example

DiscordHook's simpleness can be demonstrated using the following brief example to show the concept of sending a basic message, sending a raw json message and sending a beautiful customized embed:

local DiscordHook = require("DiscordHook")

local success, hook = DiscordHook.createWebhook("https://discordapp.com/api/webhooks/--removed--")
if not success then
    error("Webhook connection failed! Reason: " .. hook)
end

hook.send("This is just a normal message.", "Your fancy webhook", "https://media.energetic.pw/pm5rod-3pp.jpg")

hook.sendJSON("{ \"content\": \"We're going to have dinner! :pizza:\", \"username\": \"Your beloved mom\", \"avatar_url\": \"https://media.energetic.pw/pm5rsm-cJT.jpg\" }")

hook.sendEmbed("@everyone", "Base Defense System", "An intruder has been detected! User **'HydroNitrogen'** has entered private airspace at `123, 100, 321`! Please send defensive units out now!", nil, 0xFF0000, nil, "https://media.energetic.pw/pm5s32-c9z.png", "Base Defence System", "https://media.energetic.pw/pm5sfo-82l.jpg")

print("So far we've send " .. hook.sentMessages .. " messages succesfully!")

Executing the example will result in the following:

Output in CC:


Output in Discord:




Licence

DiscordHook is licenced under the MIT licence, Copyright (c) 2019 Wendelstein7 (a.k.a. HydroNitrogen)

You can definetely use this in your programs, I really recommend everyone doing so! You should make your programs that require it download the library from the raw GitHub link.
You are allowed to distribute this library yourself along with your other software that requires it (giving proper credit), but I strongly recommend downloading it from GitHub dynamically.
Please do collaborate on the ComputerCraft Wiki! Thanks!
Also like my post if you found it informative or helpful. This gets me to know what I should do more of. Thanks again!

EveryOS

Looks cool (and useful). I might try it out some day.
~Google

Paspagon

This is great! How did I not see this before?
Can't get it to work though.
local DiscordHook = require("DiscordHook")
local success, hook = DiscordHook.createWebhook("https://discordapp.com/api/webhooks/<buncha numbers>/<buncha letters&numbers>")
if not success then
  error("Webhook connection failed! Reason: " .. hook)
end

while true do
if not redstone.getInput('bottom') then
print('Door open!')
print(tostring(hook.send('Door open!', 'ComputerCraft', nil)))
end
sleep(0.5)
end

Output:
Door open!
fasle

EDIT:
All good. My dumbass wasnt using CC tweaked.