Using the Shoutrrr Package

Overview

The Shoutrrr Go package (github.com/circa10a/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.

Usage

Go Import Statement

import "github.com/circa10a/shoutrrr"

Direct Send

Sends a notification to a single service URL with an optional parameters map.

• Function: shoutrrr.Send(url string, message string, params ...map[string]string) []error
• 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).

Example

Send to a Single Slack URL

url := "slack://token-a/token-b/token-c"
errs := shoutrrr.Send(url, "Hello, Slack!")
if len(errs) > 0 {
    // Handle errors
    for _, err := range errs {
        fmt.Println("Error:", err)
    }
}

Sender

Creates a Sender (*ServiceRouter) to manage multiple service URLs, support message queuing, and allow parameter customization.

• Function: shoutrrr.CreateSender(urls ...string) (*ServiceRouter, error)
• Methods:
• Send(message string, params map[string]string) []error: Sends a message to all configured services.
• Enqueue(message string, a ...interface{}): Queues a formatted message for later sending.
• Flush(params map[string]string) []error: Sends all queued messages and resets the queue.
• Behavior: Deduplicates URLs, initializes services, and supports asynchronous sending with a 10-second timeout per service.

Example

Create Sender with Multiple URLs

urls := []string{
    "slack://token-a/token-b/token-c",
    "telegram://110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw@telegram?channels=@mychannel",
}
sender, err := shoutrrr.CreateSender(urls...)
if err != nil {
    log.Fatal(err)
}
params := map[string]string{"title": "Test Notification"}
errs := sender.Send("Hello, world!", params)
if len(errs) > 0 {
    for _, err := range errs {
        fmt.Println("Error:", err)
    }
}

Message Queuing

Allows queuing messages for deferred sending, useful for aggregating notifications during a process.

• Queues messages with Enqueue and sends them with Flush. Queued messages use the params provided during Flush.

Example

Queue and Flush Notifications

url := "discord://abc123@123456789"
sender, err := shoutrrr.CreateSender(url)
if err != nil {
    log.Fatal(err)
}
defer sender.Flush(map[string]string{"title": "Work Result"})

sender.Enqueue("Started doing work")
if err := doWork(); err != nil {
    sender.Enqueue("Error: %v", err)
    return
}
sender.Enqueue("Work completed successfully!")

Examples

Send with Parameters and Error Handling

Example

Send with Title and Error Handling

url := "discord://abc123@123456789"
params := map[string]string{"title": "Alert"}
errs := shoutrrr.Send(url, "System alert!", params)
if len(errs) > 0 {
    for _, err := range errs {
        fmt.Println("Error:", err)
    }
}

Expected Output (Success)

(No output on success)

Expected Output (Error)

Error: failed to send message: unexpected response status code

Send to Multiple Services with Queuing

Example

Queue Messages for Multiple Services

urls := []string{
    "slack://token-a/token-b/token-c",
    "discord://abc123@123456789",
}
sender, err := shoutrrr.CreateSender(urls...)
if err != nil {
    log.Fatal(err)
}
start := time.Now()
defer sender.Flush(map[string]string{"title": "Task Summary"})
sender.Enqueue("Task started")
time.Sleep(time.Second)
sender.Enqueue("Task finished in %v", time.Now().Sub(start))

Expected Output (Success)

(No output on success)

Expected Output (Error)

Error: failed to initialize service: invalid URL format

Notes

• Error Handling: Both Send and Sender.Send return a slice of errors, one per service. Check len(errs) > 0 to handle failures.
• Parameters: The params map supports service-specific options (e.g., title for Discord, Slack). Use shoutrrr docs to view supported parameters for each service.
• Timeouts: Each service send operation has a 10-second timeout.
• Deduplication: Duplicate URLs are automatically removed when creating a Sender.