Webhooks

A webhook is a channel's own posting slot. Anything sent through it arrives under whatever name and avatar the sender asks for, so an announcement can come from "Server News" instead of from Righteous. ,webhooks creates one, remembers it for you, and sends embed codes through it. Every subcommand needs Manage Server and Manage Webhooks from you and Manage Webhooks from the bot, and none of it is premium.

Create the webhook in the channel it will post in

,webhooks create makes a webhook in the channel you run it in, and every message sent through it lands there. Righteous records that channel once, at creation, and never looks again: if someone moves the webhook elsewhere from Discord's Integrations settings, sends follow it and ,webhooks list keeps printing the old channel. Run it where the messages belong.

,webhooks create <name>

,webhooks create Server News

The name may contain spaces, and only its first 25 characters are kept. Discord refuses a name containing the word "discord", and refuses a sixteenth webhook in a single channel; when it refuses for either reason the bot says so and creates nothing. The new webhook starts with your server's icon as its avatar.

The reply hands back the webhook's identifier. Copy it somewhere: it is the whole rest of this page.

If the webhook is made but cannot be stored, the bot deletes it again rather than leaving one behind: a webhook in your channel that no command can reach is worse than no webhook at all.

A webhook belongs to one channel, so create it where you want to be heard.

Get the identifier back when you have lost it

The identifier is the webhook's own Discord ID, a long run of digits. It is not the name you gave it and not the channel. send, edit and delete each take it as their first argument; create does not: its first argument is the name your members will read, so an ID typed there becomes a webhook called after a snowflake, and list takes no arguments at all. ,webhooks list is how you get a lost one back.

,webhooks list

The list shows every webhook this command has made in your server: identifier, the channel it posts in, and who created it, ten to a page. A webhook you made in Discord's own Integrations settings, or one another bot created, is not in it and cannot be driven from here.

One number reaches the webhook; the name is only what your members see.

Send a message through it

,webhooks send takes the identifier and then an embed code. Plain text works as itself: the whole embed-code language is available, and loose text becomes the message body.

,webhooks send <identifier> <code>

,webhooks send 1234567890123456789 Doors open in ten minutes.

++delete is an action rather than a tag, so it goes at the very end of the code and nowhere else: written mid-code it is left alone and renders as ordinary text. Ten minutes is the ceiling, and a number above it is dropped along with the flag: the message goes out and simply never leaves.

The message posts in the webhook's channel, which is not necessarily the channel you are typing in. Your own command stays where you ran it; the bot reacts to it with a checkmark instead of replying, so the reaction is your confirmation that the message went out.

Say it once, in the right channel, and let the reaction tell you it landed.

Start from a code that already works

An announcement with a colour, a heading and a button, posted under whatever name the webhook is wearing:

,webhooks send <identifier> <code>

,webhooks send 1234567890123456789 {color: #fb4868}$p{title: Maintenance tonight}$p{description: The server goes quiet at 22:00 and comes back within the hour.}$p{footer: {guild.name} && {guild.icon}}$p{button: Status page && https://example.com/status}

A short notice that clears itself up ten minutes later:

,webhooks send <identifier> <code>

,webhooks send 1234567890123456789 {content: Voice chat is open — come say hello.} ++delete 600

Both are ordinary embed codes. Three things are worth copying out of them:

• Variables fill in from where you are standing. The code is rendered against the message you typed, so {user} is you, the person running the command, and {channel.name} is the channel you ran it in, even when the webhook posts somewhere else. A webhook message has no audience member to greet, so write it as an announcement rather than as a greeting.
• {guild.name} and {guild.icon} are the safe pair here. They mean the same thing wherever the message lands, which is what you want on a post that is meant to look like the server talking.
• Spell the tokens exactly. A token the parser does not know keeps its own text: {usr} posts as the literal word usr, not as a blank space. Read the message the webhook actually sent before you send it to a busy channel.

Choose the name and avatar it posts under

,webhooks edit changes what your members see. The webhook already posts under the name you gave create, so reach for this when you want a different one, or an avatar that is not the server icon. Either setting can also be cleared, and a cleared setting is not blank: the message falls back to your server's own name and icon.

,webhooks edit <identifier> <name|pfp> <set|reset> [value]

,webhooks edit 1234567890123456789 name set Server News

pfp also answers to profile and icon, and name to username.

The avatar arrives either way: attach the image to the same message as the command, or paste a direct https link as the value. A link has to be the whole value: one https address, with nothing typed after it. On the slash form the link is the only route, because /webhooks edit takes its value as text and has nowhere to receive a file; other commands do accept uploads, so this is a quirk of this one rather than a rule about slash commands. Both settings are read fresh on every send, so a change applies to the next message and not to any already posted.

Name and avatar are costume, not identity: the identifier underneath never changes.

Delete a webhook

,webhooks delete removes it at both ends: the webhook is deleted on Discord, so nothing can post through it again, and the stored entry is dropped, so it leaves ,webhooks list. Messages it already sent stay in the channel.

,webhooks delete <identifier>

,webhooks delete 1234567890123456789

Deleting the channel deletes its webhooks with it, and so does removing one from Discord's Integrations settings: neither tells Righteous, so the entry sits in the list until you clear it. Run delete on it anyway: it drops the stored entry whether or not the webhook is still there, and the reply tells you which of the two it found. Retiring a webhook is one command wherever it died.

Common issues

,webhooks on its own did nothing. It is a set of subcommands and has no behaviour by itself. Run create, list, send, edit or delete.

It says the webhook is invalid. The identifier is wrong, or it belongs to a webhook this command did not make. Run ,webhooks list and copy the number from there: it is the long run of digits, not the name.

It says the embed is invalid. Your code rendered nothing Discord would accept, usually because every tag in it is misspelled and nothing was left over as text. Send a bare {description: test} first and build back up from that.

It reports an error sending. Usually the webhook no longer exists on Discord's side: someone removed it from Integrations, or its channel was deleted. Create a new one and use the new identifier.

If a fresh webhook gives the same error, the code is the problem rather than the webhook. Discord rejects the whole message for its own limits (a {description:} over 4096 characters, or an {image:} pointing at something it cannot fetch), and both land on this same wording. Cut the code back to {description: test}, confirm that sends, then add pieces until it stops.

The message posted in the wrong channel. It posted in the webhook's channel, the one it was created in, unless somebody has since moved it from Discord's Integrations settings. ,webhooks cannot move it either way, so check there, or make a second webhook where you want to be heard.

My buttons never showed up. Only link buttons can be sent through a webhook. Give the button a URL, or post the message with ,customembed instead.

Setting the avatar keeps asking for an image. pfp set takes one of two things: an image attached to the same message as the command, or an https link on its own. A bare filename, an http link, or a link with words typed after it is neither.

It posts under the server's name instead of mine. No name is set on that webhook, or it was reset. Set one with ,webhooks edit.

Every one of these commands also has a slash form (/webhooks create, /webhooks list and the rest), and /webhooks send collects the code in a pop-up box instead of on the command line.