Debian Codegraph @

pkg/services/chat/discord/doc.go

raw
1 // Package discord provides a service for sending notifications to Discord channels via webhooks.
2 //
3 // The Discord service supports comprehensive webhook integration with features including:
4 //
5 // - Plain text messages using Discord's content field for clean formatting
6 // - Rich embeds with customizable colors, authors, images, thumbnails, and fields
7 // - Message levels with color-coded embeds (error, warning, info, debug)
8 // - Thread support for sending messages to existing threads
9 // - File attachments with multipart/form-data uploads
10 // - Custom username and avatar overrides
11 // - JSON mode for raw payload control
12 // - Message chunking for long content
13 // - Line splitting for multi-line messages
14 // - Multiple embeds per message
15 // - Timestamp support in embeds
16 // - Rate limiting with exponential backoff and Retry-After header handling
17 //
18 // # URL Format
19 //
20 // The service URL follows the format:
21 //
22 // discord://token@webhookid[?param=value&...]
23 //
24 // Where:
25 // - token: The webhook token from Discord
26 // - webhookid: The webhook ID from Discord
27 // - Optional parameters: thread_id, username, avatar, etc.
28 //
29 // # Basic Usage
30 //
31 // import "github.com/nicholas-fedor/shoutrrr/pkg/services/chat/discord"
32 //
33 // service := &discord.Service{}
34 // err := service.Initialize(url, logger)
35 // if err != nil {
36 // // handle error
37 // }
38 // err = service.Send("Hello, Discord!", nil)
39 //
40 // # Configuration Options
41 //
42 // The service supports various configuration options via URL parameters or Send parameters:
43 //
44 // - avatar: Override webhook avatar URL
45 // - username: Override webhook username
46 // - thread_id: Send to specific thread
47 // - color: Border color for plain messages (hex)
48 // - color_error: Border color for error messages (hex)
49 // - color_warn: Border color for warning messages (hex)
50 // - color_info: Border color for info messages (hex)
51 // - color_debug: Border color for debug messages (hex)
52 // - json: Send raw JSON payload (true/false)
53 // - split_lines: Send each line as separate embed (true/false)
54 // - title: Message title
55 //
56 // # Embed Features
57 //
58 // Embeds can include:
59 // - Author information (name, URL, icon)
60 // - Images and thumbnails
61 // - Custom fields as key-value pairs
62 // - Color-coded borders based on message level
63 // - Timestamps for event timing
64 // - Multiple embeds per message
65 //
66 // Embed fields can be set using MessageItem.Fields with special keys:
67 // - embed_author_name: Author name
68 // - embed_author_url: Author URL
69 // - embed_author_icon_url: Author icon URL
70 // - embed_image_url: Main image URL
71 // - embed_thumbnail_url: Thumbnail image URL
72 // - Any other key becomes a custom embed field
73 //
74 // # File Attachments
75 //
76 // Files can be attached using MessageItem.File or via CLI --file option.
77 // Multiple files are supported per message.
78 //
79 // # Important Notes
80 //
81 // - Webhook permissions are required for file uploads and thread posting
82 // - Files must be accessible from the running system
83 // - Thread IDs can be obtained via Discord's Developer Mode
84 // - Message content is limited by Discord's API constraints (2000 chars per message)
85 // - Rate limiting applies as per Discord's webhook limits with automatic retry handling
86 // - The service implements exponential backoff and respects Retry-After headers
87 package discord