Holler

URL-based notification library for Elixir — send notifications to 18 services with a single URL string. An Elixir port of shoutrrr.

Installation

Add holler to your dependencies in mix.exs:

def deps do
  [
    {:holler, "~> 0.2"}
  ]
end

Usage

Send to a single service

Holler.send("gotify://example.com/AqEtoken123456", "Hello from Holler!")
# => :ok

Send to multiple services concurrently

urls = [
  "gotify://example.com/AqEtoken123456",
  "slack://hook:TXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX",
  "telegram://123456789:AABBccdd@telegram?chats=-100123456789"
]

{:ok, sender} = Holler.create_sender(urls)
Holler.Sender.send(sender, "Deploy complete!")
# => [:ok, :ok, :ok]

Override per-send params

Holler.send(
  "ntfy://ntfy.sh/my-topic",
  "Disk usage at 95%",
  %{title: "Warning", priority: "high"}
)

Supported services

Service	URL scheme	Example URL
Bark	`bark`	`bark://:devicekey@api.day.app`
Discord	`discord`	`discord://token@webhook_id`
Generic	`generic`	`generic://example.com/webhook`
Google Chat	`googlechat`	`googlechat://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz`
Gotify	`gotify`	`gotify://example.com/AqEtoken123456`
IFTTT	`ifttt`	`ifttt://webhookkey/?events=myevent`
Join	`join`	`join://shoutrrr:apikey@join/?devices=device1`
Matrix	`matrix`	`matrix://:accesstoken@matrix.example.com/`
Mattermost	`mattermost`	`mattermost://example.com/webhooktoken`
Ntfy	`ntfy`	`ntfy://ntfy.sh/my-topic`
OpsGenie	`opsgenie`	`opsgenie://api.opsgenie.com/myapikey`
Pushbullet	`pushbullet`	`pushbullet://myapitoken`
Pushover	`pushover`	`pushover://shoutrrr:token@userkey/`
Rocket.Chat	`rocketchat`	`rocketchat://example.com/tokenA/tokenB/general`
Slack	`slack`	`slack://hook:TXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX`
Teams	`teams`	`teams://group@tenant/altId/groupOwner?host=org.webhook.office.com`
Telegram	`telegram`	`telegram://botid:token@telegram?chats=@mychannel`
Zulip	`zulip`	`zulip://bot%40example.com:apikey@org.zulipchat.com/?stream=general`
Mercure	`mercure`	`mercure://:jwt@example.com?topic=https://example.com/books/1`

API

`Holler.send/3`

@spec send(url :: String.t(), message :: String.t(), params :: map()) ::
  :ok | {:error, term()}

Parses url, initialises the matching service, and sends message in one step. params is merged into the config and can override per-call options like title or priority.

`Holler.create_sender/1`

@spec create_sender([String.t()]) :: {:ok, Holler.Sender.t()} | {:error, term()}

Parses and initialises all URLs upfront. Returns a Holler.Sender struct that can be reused to send to all configured services concurrently.

`Holler.Sender.send/2`

@spec send(Holler.Sender.t(), message :: String.t(), params :: map()) ::
  [:ok | {:error, term()}]

Sends message to all services in the sender concurrently using Task.async_stream. Returns a list of results in the same order as the URLs passed to create_sender/1.

License

MIT — see LICENSE.