Debian Codegraph @

docs/usage/go-package/index.md

raw
1 # Using the Shoutrrr Package
2
3 ## Overview
4
5 The Shoutrrr Go package (`github.com/nicholas-fedor/shoutrrr`) enables sending notifications to various services (e.g., `discord`, `slack`, `telegram`, `smtp`, etc.) using service URLs. It provides two primary methods: a direct `Send` function for simple use cases and a `Sender` struct for advanced scenarios with multiple URLs, message queuing, and parameter customization.
6
7 ## Usage
8
9 ```go title="Go Import Statement"
10 import "github.com/nicholas-fedor/shoutrrr"
11 ```
12
13 ### Direct Send
14
15 Sends a notification to a single service URL with an optional parameters map.
16
17 - **Function**: `shoutrrr.Send(url string, message string, params ...map[string]string) []error`
18 - **Behavior**: Initializes a service from the provided URL, sends the message, and returns any errors. If a `params` map is provided, it customizes the notification (e.g., setting a title).
19
20 !!! Example
21 ```go title="Send to a Single Slack URL"
22 url := "slack://token-a/token-b/token-c"
23 errs := shoutrrr.Send(url, "Hello, Slack!")
24 if len(errs) > 0 {
25 // Handle errors
26 for _, err := range errs {
27 fmt.Println("Error:", err)
28 }
29 }
30 ```
31
32 ### Sender
33
34 Creates a `Sender` (`*ServiceRouter`) to manage multiple service URLs, support message queuing, and allow parameter customization.
35
36 - **Function**: `shoutrrr.CreateSender(urls ...string) (*ServiceRouter, error)`
37 - **Methods**:
38 - `Send(message string, params map[string]string) []error`: Sends a message to all configured services.
39 - `Enqueue(message string, a ...interface{})`: Queues a formatted message for later sending.
40 - `Flush(params map[string]string) []error`: Sends all queued messages and resets the queue.
41 - **Behavior**: Deduplicates URLs, initializes services, and supports asynchronous sending with a 10-second timeout per service.
42
43 !!! Example
44 ```go title="Create Sender with Multiple URLs"
45 urls := []string{
46 "slack://token-a/token-b/token-c",
47 "telegram://110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw@telegram?channels=@mychannel",
48 }
49 sender, err := shoutrrr.CreateSender(urls...)
50 if err != nil {
51 log.Fatal(err)
52 }
53 params := map[string]string{"title": "Test Notification"}
54 errs := sender.Send("Hello, world!", params)
55 if len(errs) > 0 {
56 for _, err := range errs {
57 fmt.Println("Error:", err)
58 }
59 }
60 ```
61
62 ### Message Queuing
63
64 Allows queuing messages for deferred sending, useful for aggregating notifications during a process.
65
66 - Queues messages with `Enqueue` and sends them with `Flush`. Queued messages use the `params` provided during `Flush`.
67
68 <!-- markdownlint-disable -->
69 !!! Example
70 ```go title="Queue and Flush Notifications"
71 url := "discord://abc123@123456789"
72 sender, err := shoutrrr.CreateSender(url)
73 if err != nil {
74 log.Fatal(err)
75 }
76 defer sender.Flush(map[string]string{"title": "Work Result"})
77
78 sender.Enqueue("Started doing work")
79 if err := doWork(); err != nil {
80 sender.Enqueue("Error: %v", err)
81 return
82 }
83 sender.Enqueue("Work completed successfully!")
84 ```
85 <!-- markdownlint-restore -->
86
87 ## Examples
88
89 <!-- markdownlint-disable -->
90 ### Send with Parameters and Error Handling
91
92 !!! Example
93 ```go title="Send with Title and Error Handling"
94 url := "discord://abc123@123456789"
95 params := map[string]string{"title": "Alert"}
96 errs := shoutrrr.Send(url, "System alert!", params)
97 if len(errs) > 0 {
98 for _, err := range errs {
99 fmt.Println("Error:", err)
100 }
101 }
102 ```
103
104 ```text title="Expected Output (Success)"
105 (No output on success)
106 ```
107
108 ```text title="Expected Output (Error)"
109 Error: failed to send message: unexpected response status code
110 ```
111
112 ### Send to Multiple Services with Queuing
113
114 !!! Example
115 ```go title="Queue Messages for Multiple Services"
116 urls := []string{
117 "slack://token-a/token-b/token-c",
118 "discord://abc123@123456789",
119 }
120 sender, err := shoutrrr.CreateSender(urls...)
121 if err != nil {
122 log.Fatal(err)
123 }
124 start := time.Now()
125 defer sender.Flush(map[string]string{"title": "Task Summary"})
126 sender.Enqueue("Task started")
127 time.Sleep(time.Second)
128 sender.Enqueue("Task finished in %v", time.Now().Sub(start))
129 ```
130
131 ```text title="Expected Output (Success)"
132 (No output on success)
133 ```
134
135 ```text title="Expected Output (Error)"
136 Error: failed to initialize service: invalid URL format
137 ```
138 <!-- markdownlint-restore -->
139
140 ## Notes
141
142 - **Error Handling**: Both `Send` and `Sender.Send` return a slice of errors, one per service. Check `len(errs) > 0` to handle failures.
143 - **Parameters**: The `params` map supports service-specific options (e.g., `title` for Discord, Slack). Use `shoutrrr docs` to view supported parameters for each service.
144 - **Timeouts**: Each service send operation has a 10-second timeout.
145 - **Deduplication**: Duplicate URLs are automatically removed when creating a `Sender`.