Debian Codegraph @

docs/services/chat/discord/index.md

raw
1 # Discord
2
3 ## URL Format
4
5 Your Discord Webhook-URL will look like this:
6
7 !!! info ""
8 <https://discord.com/api/webhooks/__`webhookid`__/__`token`>__
9
10 For more information about Discord webhooks, see the [official documentation](https://discord.com/developers/docs/resources/webhook).
11
12 The shoutrrr service URL should look like this:
13
14 !!! info ""
15 discord://__`token`__@__`webhookid`__[?thread_id=__`threadid`__]
16
17 ### Thread Support
18
19 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:
20
21 !!! info ""
22 discord://__`token`__@__`webhookid`__?thread_id=123456789
23
24 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](https://discord.com/developers/docs/resources/channel#thread-object). Learn how to enable Developer Mode in Discord's [support article](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-).
25
26 ## Webhook Customization
27
28 You can customize the webhook's appearance by overriding the default username and avatar that were set when creating the webhook.
29
30 !!! example "Custom Username and Avatar"
31 ```bash
32 shoutrrr send --url "discord://token@webhookid?username=MyBot&avatar=https://example.com/avatar.png" --message "Hello from custom bot!"
33 ```
34
35 ## Message Content
36
37 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.
38
39 !!! example "Simple Text Message"
40 ```bash
41 shoutrrr send --url "discord://token@webhookid" --message "Hello, World!"
42 ```
43
44 This sends a plain text message using the `content` field instead of an embed.
45
46 ## Message Chunking
47
48 ### Discord API Constraints
49
50 Discord limits individual messages to 2000 characters.
51 Messages exceeding this limit are sent as separate messages without automatic merging.
52
53 ### Shoutrrr Implementation
54
55 Shoutrrr provides additional message chunking as a feature to handle longer content.
56 This is implemented through Shoutrrr's PartitionMessage utility and is not a Discord requirement.
57
58 - __Chunk Size__: Maximum 2000 characters per message (matches Discord API limit)
59 - __Total Size__: Maximum 6000 characters total across all chunks (Shoutrrr-specific limit)
60 - __Max Chunks__: Up to 10 message chunks per send operation (Shoutrrr-specific limit)
61
62 !!! note ""
63 The 6000-character limit mentioned in Discord's documentation applies specifically to the total text content of embed objects, not to message chunking.
64
65 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.
66
67 !!! example "Long Message Chunking"
68 ```bash
69 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."
70 ```
71
72 !!! note ""
73 Message chunking only applies when `splitLines` is set to `false`. When `splitLines` is `true` (default), each line becomes a separate embed instead.
74
75 ## Enhanced Embeds
76
77 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](https://discord.com/developers/docs/resources/channel#embed-object).
78
79 !!! note ""
80 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.
81
82 ## File Attachments
83
84 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](https://discord.com/developers/docs/resources/webhook#execute-webhook) for details on file attachments.
85
86 !!! note ""
87 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.
88
89 --8<-- "docs/services/chat/discord/config.md"
90
91 ## Creating a webhook in Discord
92
93 1. Open your channel settings by first clicking on the gear icon next to the name of the channel.
94 ![Screenshot 1](sc-1.png)
95
96 2. In the menu on the left, click on *Integrations*.
97 ![Screenshot 2](sc-2.png)
98
99 3. In the menu on the right, click on *Create Webhook*.
100 ![Screenshot 3](sc-3.png)
101
102 4. Set the name, channel, and icon to your liking and click the *Copy Webhook URL* button.
103 ![Screenshot 4](sc-4.png)
104
105 5. Press the *Save Changes* button.
106 ![Screenshot 5](sc-5.png)
107
108 6. Format the service URL:
109
110 ```url
111 https://discord.com/api/webhooks/693853386302554172/W3dE2OZz4C13_4z_uHfDOoC7BqTW288s-z1ykqI0iJnY_HjRqMGO8Sc7YDqvf_KVKjhJ
112 └────────────────┘ └──────────────────────────────────────────────────────────────────┘
113 webhook id token
114
115 discord://W3dE2OZz4C13_4z_uHfDOoC7BqTW288s-z1ykqI0iJnY_HjRqMGO8Sc7YDqvf_KVKjhJ@693853386302554172?thread_id=123456789
116 └──────────────────────────────────────────────────────────────────┘ └────────────────┘ └─────────────────┘
117 token webhook id thread id
118 ```