shoutrrr

README

Shoutrrr

A notification library for gophers and their furry friends.
Heavily inspired by caronc/apprise.

Table of Contents

• Full Documentation
• Installation
  • From Source
  • Binaries
  • Container Images
  • Go Package
  • GitHub Action
• Usage
  • CLI
  • Go Package Usage
  • Docker
  • GitHub Action Usage
• Supported Services
• Contributors
• Related Projects

Full Documentation

Visit the project's GitHub Page for full documentation.

Installation

From Source

go install github.com/nicholas-fedor/shoutrrr/shoutrrr@latest

Binaries

Install the latest release binary to $HOME/go/bin (ensure it's in your PATH).

• Windows (amd64):

  New-Item -ItemType Directory -Path $HOME\go\bin -Force | Out-Null; iwr (iwr https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | ConvertFrom-Json).assets.where({$_.name -like "*windows_amd64*.zip"}).browser_download_url -OutFile shoutrrr.zip; Add-Type -AssemblyName System.IO.Compression.FileSystem; ($z=[System.IO.Compression.ZipFile]::OpenRead("$PWD\shoutrrr.zip")).Entries | ? {$_.Name -eq 'shoutrrr.exe'} | % {[System.IO.Compression.ZipFileExtensions]::ExtractToFile($_, "$HOME\go\bin\$($_.Name)", $true)}; $z.Dispose(); rm shoutrrr.zip; if (Test-Path "$HOME\go\bin\shoutrrr.exe") { Write-Host "Successfully installed shoutrrr.exe to $HOME\go\bin" } else { Write-Host "Failed to install shoutrrr.exe" }
  

• Linux (amd64):

  mkdir -p $HOME/go/bin && curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | grep -o 'https://[^"]*linux_amd64[^"]*\.tar\.gz') | tar -xz --strip-components=1 -C $HOME/go/bin shoutrrr
  

• macOS (amd64):

  mkdir -p $HOME/go/bin && curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | grep -o 'https://[^"]*darwin_amd64[^"]*\.tar\.gz') | tar -xz --strip-components=1 -C $HOME/go/bin shoutrrr
  

[!Note] Visit the releases page for other architectures (e.g., arm, arm64, i386, riscv64).

Container Images

• Docker Hub:

  docker pull nickfedor/shoutrrr:latest
  

• GHCR:

  docker pull ghcr.io/nicholas-fedor/shoutrrr:latest
  

[!Note] Tags: latest (stable), vX.Y.Z (specific version), latest-dev (development), platform-specific (e.g., amd64-latest).

Go Package

go get github.com/nicholas-fedor/shoutrrr@latest

GitHub Action

- name: Shoutrrr
  uses: nicholas-fedor/shoutrrr-action@v1
  with:
    url: ${{ secrets.SHOUTRRR_URL }}
    title: Deployed ${{ github.sha }}
    message: See changes at ${{ github.event.compare }}.

Usage

CLI

shoutrrr send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"

Go Package Usage

import "github.com/nicholas-fedor/shoutrrr"

errs := shoutrrr.Send("slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook", "Hello, Slack!")
if len(errs) > 0 {
    // Handle errors
}

Docker

docker run --rm nickfedor/shoutrrr:latest send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"

GitHub Action Usage

See installation example above.

Use as a Package

Option 1 - Using the direct send command

url := "slack://token-a/token-b/token-c"
err := shoutrrr.Send(url, "Hello world (or slack channel) !")

Option 2 - Using a sender

Single URL

url := "slack://token-a/token-b/token-c"
sender, err := shoutrrr.CreateSender(url)
sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ })

Multiple URLs

urls := []string {
  "slack://token-a/token-b/token-c"
  "discord://token@channel"
}
sender, err := shoutrrr.CreateSender(urls...)
sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ })

Use Through the CLI

shoutrrr send [OPTIONS] <URL> <Message [...]>

Use as a GitHub Action

You can also use Shoutrrr in a GitHub Actions workflow.

name: Deploy
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - [Your other workflow steps]

      - name: Shoutrrr
        uses: nicholas-fedor/shoutrrr-action@v0.0.11
        with:
          url: ${{ secrets.SHOUTRRR_URL }}
          title: Deployed ${{ github.sha }}
          message: See changes at ${{ github.event.compare }}.

Supported Services

Service	Description
Bark	iOS push notifications
Discord	Discord webhooks
Generic	Custom HTTP webhooks
Google Chat	Google Chat webhooks
Gotify	Gotify push notifications
IFTTT	IFTTT webhooks
Join	Join push notifications
Lark	Lark (Feishu) webhooks
Logger	Local logging (for testing)
Matrix	Matrix rooms
Mattermost	Mattermost webhooks
Ntfy	Ntfy push notifications
Opsgenie	Opsgenie alerts
Pushbullet	Pushbullet push notifications
Pushover	Pushover push notifications
Rocket.Chat	Rocket.Chat webhooks
Slack	Slack webhooks or Bot API
SMTP	Email notifications
Teams	Microsoft Teams webhooks
Telegram	Telegram bots
Zulip	Zulip chat
XMPP	XMPP messages (if enabled)

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Nicholas Fedor 💻 📖 🚧 👀	Amir Schnell 💻	nils måsén 💻 📖 🚧	Luka Peschke 💻 📖	MrLuje 💻 📖	Simon Aronsson 💻 📖 🚧	Arne Jørgensen 📖 💻
Alexei Tighineanu 💻	Alexandru Bonini 💻	Senan Kelly 💻	JonasPf 💻	claycooper 📖	Derzsi Dániel 💻	Joseph Kavanagh 💻 🐛
Justin Steven 🐛	Carlos Savcic 💻 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

Related Project(s)

• Watchtower - Automate Docker container image updates
• Shoutrrr GitHub Action - Notifications using Shoutrrr in GitHub Actions

Documentation

Index

• func CreateSender(rawURLs ...string) (*router.ServiceRouter, error)
• func NewSender(logger types.StdLogger, serviceURLs ...string) (*router.ServiceRouter, error)
• func Send(rawURL string, message string) error
• func SetLogger(logger types.StdLogger)
• func Version() string

Functions

func CreateSender

func CreateSender(rawURLs ...string) (*router.ServiceRouter, error)

CreateSender constructs a new service router for the given URLs without a logger.

func NewSender

func NewSender(logger types.StdLogger, serviceURLs ...string) (*router.ServiceRouter, error)

NewSender constructs a new service router with a logger for the given URLs.

func Send

func Send(rawURL string, message string) error

Send delivers a notification message using the specified URL.

func SetLogger

func SetLogger(logger types.StdLogger)

SetLogger configures the logger for all services in the default router.

func Version

func Version() string

Version returns the current Shoutrrr version.