Need help with discord.sh?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

ChaoticWeg
170 Stars 33 Forks GNU General Public License v3.0 164 Commits 2 Opened issues

Description

Write-only command-line Discord webhook integration written in 100% Bash script

Services available

!
?

Need anything else?

Contributors list


discord.sh

Travis CI (master branch) GitHub stars

Write-only command-line integration for Discord webhooks, written in 100% Bash script. Influenced heavily by slack-cli.

Table of Contents

Features

  • Create and send very customizable and beautiful Discord messages 🎉 ✨
  • Less than 400 lines of pure Bash 😎
  • Extremely lightweight ⚡ 🚀
  • Only requires curl and jq to run 🔥

Dependencies

  • curl (http requests)
  • bats (tests)
  • jq (JSON parsing)

Usage

1. Setting up a Discord webhook.

  1. Setup a webhook in the desired Discord text channel
  2. Download (or clone) a copy of
    discord.sh
  3. Point
    discord.sh
    at a webhook endpoint (see below)
  4. Go nuts.

2. Specifying a Webhook URL within
discord.sh

There are three ways to point

discord.sh
at a webhook endpoint, in order of priority that
discord.sh
takes:
  1. Pass the webhook URL as an argument to
    discord.sh
    using
    --webhook-url
  2. Set an environment variable called
    $DISCORD_WEBHOOK
  3. Create a file called
    .webhook
    in the same directory as
    discord.sh
    , containing only the webhook URL

3. Using the script

Simple chat example

$ ./discord.sh --webhook-url="$WEBHOOK" --text "Hello, world!"

Simple chat example with custom username and avatar

$ ./discord.sh \
  --webhook-url="$WEBHOOK" \
  --username "NotificationBot" \
  --avatar "https://i.imgur.com/12jyR5Q.png" \
  --text "Hello, world!"

Advanced chat example using an embed (using all possible options)

$ ./discord.sh \
  --webhook-url="$WEBHOOK" \
  --username "NotificationBot" \
  --avatar "https://i.imgur.com/12jyR5Q.png" \
  --text "Check out this embed!" \
  --title "New Notification!" \
  --description "This is a description\nPretty cool huh?" \
  --color "0xFFFFFF" \
  --url "https://github.com/ChaoticWeg/discord.sh" \
  --author "discord.sh" \
  --author-url "https://github.com/ChaoticWeg/discord.sh" \
  --author-icon "https://i.imgur.com/12jyR5Q.png" \
  --image "https://i.imgur.com/12jyR5Q.png" \
  --thumbnail "https://i.imgur.com/12jyR5Q.png" \
  --footer "discord.sh" \
  --footer-icon "https://i.imgur.com/12jyR5Q.png" \
  --timestamp

Sending a file (up to 8MB, per Discord limitations)

Note: per the Discord webhook API, posts cannot contain embeds and file attachments. Therefore,

discord.sh
will bail out when trying to build a message with embeds and files. The best practice is to send the message with embeds before sending a file.

$ ./discord.sh \
  --webhook-url="$WEBHOOK" \
  --file README.md \
  --username "Notification Bot" \
  --text "Check out this README.md file!"

Options

--webhook-url 

This should be set to your Discord webhook URL. You may alternatively set the environment variable

DISCORD_WEBHOOK
to your Discord webhook URL and that way you don't have to pass in the webhook URL inline.

--text 

This is basic text like shown below.

--username 

You can override the username of the webhook "bot" with this flag.

--avatar 

You can override the avatar of the webhook "bot" with this flag.

Advanced Options

Now we're going to look at how to setup a custom embed message.

--title 

This option allows you to set the title of the embed.

--description 

This option allows you to set the description of the embed.

--color 

This option allows you to set color on the left of the embed.

Input Syntax 1:
0x
+
COLOR HEX

Input Syntax 2:
COLOR DEC

Input Example 1:
--color 0xFFFFFF

Input Example 2:
--color 16777215

--url 

This option allows you to set the URL of the

--title
flag within the embed.

--author 

This option allows you to set the author name of the embed.

--author-url 

This option allows you to set the author URL of the

--author
flag within the embed.

--author-icon 

This option allows you to set the author icon that sits to the left of the

--author
flag within the embed.

--image 

This option allows you to set the image that sits within the embed.

--thumbnail 

This option allows you to set the thumbnail that sits to the right within the embed.

--footer 

This option allows you to set the thumbnail that sits to the right within the embed.

--footer-icon 

This option allows you to set the footer icon that sites to the right of the

--footer
flag within the embed.

--timestamp

This option allows you to define whether the timestamp is displayed on the embed message or not.

Input Type: None

Tips

Proper character escaping

If you want to show the output of a file or

stdin
via discord.sh, and your file includes special characters such as
backticks (`)
and
"
, then you can't simply
cat filename
. You will need to properly escape special characters.

One of the easiest methods to output properly escaped text from a file is to use

jq
,
cut
, and
rev

Prerequisites

  • jq - Character escaping
  • cut - Cut characters from string (part of coreutils, included by default on most systems)
  • rev - Reversing of characters (part of util-linux, included by default on most systems)

Usage (contents of file)

  1. Simply pass
    filename
    to the following command to escape the file contents to
    stdout
    :
    bash
    jq -Rs . 
    ---
    #### Usage (contents of 
    stdin
    )
  2. Simply pipe
    stdin
    to the beginning of the following command to escape the contents to
    stdout
    :
    bash
    cat `filename` | jq -Rs . | cut -c 2- | rev | cut -c 2- | rev
    
    ---
  3. Assuming

    filename
    or
    stdin
    contains the following contents when viewed in an editor such as
    vim
    or
    nano
    :
    php
    <?php echo "Hello, world!" ?>
    ```
    
    

    :smile:

    Bobs your uncle. [email protected]#$%^&*()_}{":?><,./;'[]-= ```

  4. If you ran the command, the output would be:

    php\n<?php echo \"Hello, world!\" ?>\n
    \n\n:smile:\n\nBobs your uncle. [email protected]#$%^&*()_}{\":?>

4. In order to use it in discord.sh, all we have to do is pass that command within a subshell.

  1. Usage (contents of file)
    bash
    ./discord.sh --webhook-url "$WEBHOOK_URL" --text "$(jq -Rs . 
    ---
  2. Usage (contents of
    stdin
    )
    bash
    ./discord.sh --webhook-url "$WEBHOOK_URL" --text "$(cat filename | jq -Rs . | cut -c 2- | rev | cut -c 2- | rev)"
    
  3. Result:

Screenshot

Usage (contents of stdin)

Simply pass

filename
to the following command to escape the file to
stdout
:
bash
jq -Rs . 

Explanation

jq
takes the file in as
stdin
then escapes it. We then pipe it to cut to remove the first 2 "indexes" meaning the first character which is a
"
that
jq
adds. We then pip that into
rev
to reverse the text as a whole, then pipe that into
cut
to remove the first 2 "indexes" or first (last) character which is once again a
"
that
jq
adds. Finally we re-reverse the text back to the standard order. The command will output to
stdout

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

GPL-3.0

Made with 💖 by ChaoticWeg || Documentation and design by fieu and Matt

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.