Getting started¶

As a package¶

Using shoutrrr is easy! There is currently two ways of using it as a package.

Using the direct send command¶

Easiest to use, but very limited.

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

Using a sender¶

Using a sender gives you the ability to preconfigure multiple notification services and send to all of them with the same Send(message, params) method.

urlA := "slack://token-a/token-b/token-c"
urlB := "telegram://110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw@telegram?channels=@mychannel"
sender, err := shoutrrr.CreateSender(urlA, urlB)

// Send notifications instantly to all services
sender.Send("Hello world (or slack/telegram channel)!", map[string]string { "title": "He-hey~!"  })

// ...or bundle notifications... 
func doWork() error {
    // ...and send them when leaving the scope
    defer sender.Flush(map[string]string { "title": "Work Result" })

    sender.Enqueue("Started doing %v", stuff)

    // Maybe get creative...?
    defer func(start time.Time) { 
        sender.Enqueue("Elapsed: %v", time.Now().Sub(start)) 
    }(time.Now())

    if err := doMoreWork(); err != nil {
        sender.Enqueue("Oh no! %v", err)

        // This will send the currently queued up messages...
        return
    }   

    sender.Enqueue("Everything went very well!")

    // ...or this:
}

Through the CLI¶

Start by running the build.sh script. You may then run the shoutrrr executable:

$ ./shoutrrr

Usage:
./shoutrrr <ActionVerb> [...]
Possible actions: send, verify, generate

On a system with Go installed you can install the latest Shoutrrr CLI command with:

go install github.com/containrrr/shoutrrr/shoutrrr@latest

Commands¶

Send¶

Send a notification using the supplied notification service url.

$ shoutrrr send \
    --url "<SERVICE_URL>" \
    --message "<MESSAGE BODY>"

Verify¶

Verify the validity of a notification service url.

$ shoutrrr verify \
    --url "<SERVICE_URL>"

Generate¶

Generate and display the configuration for a notification service url.

$ shoutrrr generate [OPTIONS] <SERVICE>

Flags	Description
`-g, --generator string`	The generator to use (default "basic")
`-p, --property stringArray`	Configuration property in key=value format
`-s, --service string`	The notification service to generate a URL for

Note: Service can either be supplied as the first argument or using the -s flag.

For more information on generators, see Generators.

Options¶

Debug¶

Enables debug output from the CLI.

Flags	Env.	Default	Required
`--debug`, `-d`	`SHOUTRRR_DEBUG`	`false`

URL¶

The target url for the notifications generated, see overview.

Flags	Env.	Default	Required
`--url`, `-u`	`SHOUTRRR_URL`	N/A	✅

From a GitHub Actions workflow¶

You can also use Shoutrrr from a GitHub Actions workflow.

See this example and the action on GitHub Marketplace:

name: Deploy
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Some other steps needed for deploying
        run: ...
      - name: Shoutrrr
        uses: containrrr/shoutrrr-action@v1
        with:
          url: ${{ secrets.SHOUTRRR_URL }}
          title: Deployed ${{ github.sha }}
          message: See changes at ${{ github.event.compare }}.