Viewing entries tagged
Invoke-RestMethod

Using Discord Webhooks and Embeds With PowerShell (Part 2)

Using Discord Webhooks and Embeds With PowerShell (Part 2)

embed_resized.png

Welcome to part 2 of my series of using PowerShell to send Discord webhooks. In this post I will be going over how to send embeds. If you’re just getting started with the process, I recommend reading Part 1 first.

Table of Contents

PSDsHook Module

I’ve created a module that makes it easy to work with embeds, store configurations that contain your webhook urls, and make the whole experience seamless by using PowerShell classes. It will get its own post, and if you’re interested check out the Github repo here.

Example of using the module:

Embeds!

If we take a look at the Discord developer documentation for webhook properties, this is what it looks like:

webhookresource.PNG

You can see there’s a field for embeds that accepts and array of embed objects. Embeds in Discord are a way to make your message look a little spiffier. 

Here is the documentation for embeds:

Here is an example of what one looks like from the teaser at the end of part one:

part2_discord.png

There are a lot of different features of embeds, and we’ll be covering a few of them. You can use this link to see how many different fields there are in an embed available to you.

In this post I will be focusing on sending an embed that contains a color (on the left side), a thumbnail image, title, and a description (essentially the content of the embed).

Creating and Sending the Embed

To get started making embeds, be sure to keep that webhook url handy from part 1.

  1. First let’s store that webhook url in a variable and create an empty array to add the embed(s) to.

$webHookUrl = "yourhookurlhere"
[System.Collections.ArrayList]$embedArray = @()

2. Now let’s store values for the title, description, and color.

  • Title and description are strings so those are easy. Color is also a string, but a string that represents a decimal value for the color. For now it is important to understand the value for green is 4289797.

$color = '4289797'
$title = 'Greetings from PowerShell!'
$description = 'This is an embed. It looks much nicer than just sending text over!'

3. Now it’s time to create a PSCustomObject that contains those items to add to the array we created earlier.

$embedObject = [PSCustomObject]@{
    color = $color
    title = $title
    description = $description
}

4. Let’s add that to our array.

$embedArray.Add($embedObject)

5. Taking a peek at the array, we can see the contents of our embed in it.

arraypeek.PNG

6. Now let’s test it by constructing the payload and sending it over to the webhook url via Invoke-RestMethod.

$payload = [PSCustomObject]@{
    embeds = $embedArray
}

Invoke-RestMethod -Uri $webHookUrl -Body ($payload | ConvertTo-Json -Depth 4) -Method Post -ContentType 'application/json'

7. Looking in the channel it should send to, it looks like the send was successful!

firstsend.PNG

Adding a Thumbnail

Now that we’ve constructed and sent an embed successfully, let’s send one with a thumbnail in it. To do this we’ll start from scratch, and apply much of what we did above to a new embed object.

First we’ll need to construct a thumbnail object. From the Discord developer documentation, we can see a thumbnail contains the following:

thumb.PNG

We’ll be using the url property to store a url to an image.

1. Create the thumbnail object.

$thumbnailObject = [PSCustomObject]@{
    url = "https://static1.squarespace.com/static/5644323de4b07810c0b6db7b/t/5aa44874e4966bde3633b69c/1520715914043/webhook_resized.png"
}

2. Create our embed object with the thumbnail in it.

$title       = 'Greetings with a picture!'
$description = 'This embed should now contain an image'
$color       = '9442302'

$embedObject = [PSCustomObject]@{
    title = $title
    description = $description
    color = $color
    thumbnail = $thumbnailObject
}

3. Now we’ll create an array, add the embed object, create the payload, and send that over to the webhook url.

[System.Collections.ArrayList]$embedArray = @()
$embedArray.Add($embedObject)

$payload = [PSCustomObject]@{
    embeds = $embedArray
}
Invoke-RestMethod -Uri $webHookUrl -Body ($payload | ConvertTo-Json -Depth 4) -Method Post -ContentType 'application/json'

Looking in the channel, we can see that it worked!

embedwiththumb.PNG

Github Repo With Example Code

I’m going to start putting examples together in Github so I can better keep them updated. Use this url for updated examples: https://github.com/gngrninja/blog/blob/master/DiscordWebhook/embeds.ps1

Summary

Embeds are a little more complicated, but not too hard to work in with these webhooks and PowerShell. There is even more you can do, including adding fields to embeds and sending files. In part 3 I will be go over just how to do that!

fields.PNG

Let me know if you have any ideas, questions, or feedback in the comments below!

Using Discord Webhooks With PowerShell (Part 1)

Using Discord Webhooks With PowerShell (Part 1)

webhook_resized.png

What's a Discord Webhook?

A Discord Webhook allows you to send a message to a text channel auto-magically. It essentially provides a URL that is associated with a channel. You can customize the name of the sender, the avatar picture, and of course send over the contents of the mesage. More info on Discord Webhooks here.

Getting Started

The first step will be to create the Webhook in Discord.

1. Navigate to Server Settings on the server you want to create the hook on.

server_settings.png

2. Click Webhooks from the options on the left, and then Create Webhook on the right.

webhook.png
create_hook.png

3. Fill out the name of the hook, the channel you want it to hook into, and optionally associate an image.

hook_settings.png

4. Save the Webhook, and get the Webhook Url, as we'll need that later.

Using the Webhook in PowerShell

To utilize the Webhook in PowerShell, we'll make use of the Invoke-RestMethod command, and build a custom object as our payload.

1. Store the hook url we created earlier in a variable.

$hookUrl = "your hook url goes here"

2. Store the content in a variable (this is the message you'll be sending to the hook).

$content = @"
You can enter your message content here.

With a here-string, new lines are included as well!

Enjoy.
"@

3. Create the payload as a PowerShell custom object, in order to get the properties converted to JSON later.

$payload = [PSCustomObject]@{

    content = $content

}

4. Finally, use Invoke-RestMethod to utlize the Webhook, and post the message.

Invoke-RestMethod -Uri $hookUrl -Method Post -Body ($payload | ConvertTo-Json)

We are using the Post method with Invoke-RestMethod to send over the $payload

The payload is a PSCustomObject, which is great when working in PowerShell, but not-so-great when working with Web APIs, which almost always want something to be formatted as JSON (JavaScript Object Notation). 

That's why we use ($payload | ConvertTo-Json) with this Invoke-RestMethod call.

Here is what the object looks like:

payload_psobject.png

Here is what it looks like converted to JSON:

payload_asjson.png

The Code

Altogether, our code should now look like this:

$hookUrl = 'https://enterYourUrlHere'

$content = @"
You can enter your message content here.

With a here-string, new lines are included as well!

Enjoy.
"@

$payload = [PSCustomObject]@{

    content = $content

}

Invoke-RestMethod -Uri $hookUrl -Method Post -Body ($payload | ConvertTo-Json)

Let's run that, and see what happens in the Discord channel the hook is associated with.

hook_message.png

Success!

But wait... there's more!

Keep an eye out for part 2, where I'll expand upon what we can add to the payload. This includes a different user name, avatar icon, and even embeds!

part2_ps.png
part2_discord.png

Let me know if you have any trouble or ideas in the comment section, below!

I am also interested in hearing how you plan to use your PowerShell -> Discord Webhooks.

Happy Scripting!