| 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 |