Discord¶

URL Format¶

Your Discord Webhook-URL will look like this:

https://discord.com/api/webhooks/__webhookid/token__

For more information about Discord webhooks, see the official documentation.

The shoutrrr service URL should look like this:

discord://token@webhookid[?thread_id=threadid]

Thread Support¶

To send messages to a specific thread in a Discord channel, include the thread_id query parameter in the service URL with the ID of the target thread. For example:

discord://token@webhookid?thread_id=123456789

You can obtain the thread_id by right-clicking a thread in Discord and selecting "Copy ID" (requires Developer Mode to be enabled in Discord settings). For more details on threads, see Discord's thread documentation. Learn how to enable Developer Mode in Discord's support article.

Webhook Customization¶

You can customize the webhook's appearance by overriding the default username and avatar that were set when creating the webhook.

Custom Username and Avatar

shoutrrr send --url "discord://token@webhookid?username=MyBot&avatar=https://example.com/avatar.png" --message "Hello from custom bot!"

Message Content¶

For simple text messages without embeds, Shoutrrr now uses Discord's content field directly, providing cleaner message formatting and better compatibility with Discord's features.

Simple Text Message

shoutrrr send --url "discord://token@webhookid" --message "Hello, World!"

This sends a plain text message using the content field instead of an embed.

Message Chunking¶

Discord API Constraints¶

Discord limits individual messages to 2000 characters. Messages exceeding this limit are sent as separate messages without automatic merging.

Shoutrrr Implementation¶

Shoutrrr provides additional message chunking as a feature to handle longer content. This is implemented through Shoutrrr's PartitionMessage utility and is not a Discord requirement.

Chunk Size: Maximum 2000 characters per message (matches Discord API limit)
Total Size: Maximum 6000 characters total across all chunks (Shoutrrr-specific limit)
Max Chunks: Up to 10 message chunks per send operation (Shoutrrr-specific limit)

The 6000-character limit mentioned in Discord's documentation applies specifically to the total text content of embed objects, not to message chunking.

When splitLines is enabled (default), each line of the input becomes a separate embedded item. When disabled, long messages are automatically chunked to fit within Discord's limits.

Long Message Chunking

shoutrrr send --url "discord://token@webhookid?splitLines=false" --message "This is a very long message that will be automatically split into multiple chunks if it exceeds Discord's 2000 character limit per message."

Message chunking only applies when splitLines is set to false. When splitLines is true (default), each line becomes a separate embed instead.

Enhanced Embeds¶

Shoutrrr supports rich embed formatting with authors, images, thumbnails, and custom fields when using the Go library API. Embeds are automatically created when using structured message items with metadata. For detailed information about embed objects, refer to Discord's embed documentation.

Enhanced embed features are only available through the Go library API using SendItems with MessageItem structs containing metadata. The CLI does not support embed parameters.

File Attachments¶

Shoutrrr supports attaching files to your Discord messages when using the Go library. Files are sent as multipart/form-data along with the message payload. See Discord's webhook execution documentation for details on file attachments.

File attachments require the webhook to have appropriate permissions, and files must be accessible from the system running Shoutrrr. File attachments are not supported in the CLI.

URL Fields¶

Token (Required)
URL part: discord://token@webhookid/
WebhookID (Required)
URL part: discord://token@webhookid/

Query/Param Props¶

Props can be either supplied using the params argument, or through the URL using
?key=value&key=value etc.

Avatar - Override the webhook default avatar with specified URL
Default: empty
Aliases: avatarurl
Color - The color of the left border for plain messages
Default: 0x50D9ff
ColorDebug - The color of the left border for debug messages
Default: 0x7b00ab
ColorError - The color of the left border for error messages
Default: 0xd60510
ColorInfo - The color of the left border for info messages
Default: 0x2488ff
ColorWarn - The color of the left border for warning messages
Default: 0xffc441
JSON - Whether to send the whole message as the JSON payload instead of using it as the 'content' field
Default: ❌ No
SplitLines - Whether to send each line as a separate embedded item
Default: ✔ Yes
ThreadID - The thread ID to send the message to
Default: empty
Title
Default: empty
Username - Override the webhook default username
Default: empty

Creating a webhook in Discord¶

Open your channel settings by first clicking on the gear icon next to the name of the channel.
In the menu on the left, click on Integrations.
In the menu on the right, click on Create Webhook.
Set the name, channel, and icon to your liking and click the Copy Webhook URL button.
Press the Save Changes button.
Format the service URL:

https://discord.com/api/webhooks/693853386302554172/W3dE2OZz4C13_4z_uHfDOoC7BqTW288s-z1ykqI0iJnY_HjRqMGO8Sc7YDqvf_KVKjhJ
                                 └────────────────┘ └──────────────────────────────────────────────────────────────────┘
                                     webhook id                                    token

discord://W3dE2OZz4C13_4z_uHfDOoC7BqTW288s-z1ykqI0iJnY_HjRqMGO8Sc7YDqvf_KVKjhJ@693853386302554172?thread_id=123456789
          └──────────────────────────────────────────────────────────────────┘ └────────────────┘ └─────────────────┘
                                          token                                    webhook id           thread id