feat(slack): add bot API support

docs/guides/slack/index.md

@@ -0,0 +1,47 @@
+# Slack Guides
+
+Guides for setting up the [Slack](../../services/slack.md) service
+
+## Getting a token
+
+To enable all features, either the Legacy Webhook- (deprecated and might stop working) or the bot API tokens needs to
+be used. Only use the non-legacy Webhook if you don't need to customize the bot name or icon.
+
+### Bot API (preferred)
+
+1. Create a new App for your bot using the [Basic app setup guide](https://api.slack.com/authentication/basics)
+2. Install the App into your workspace ([slack docs](https://api.slack.com/authentication/basics#installing)).
+3. From [Apps](https://api.slack.com/apps), select your new App and go to **Oauth & Permissions**
+   <figure><img alt="Slack app management menu screenshot" src="app-api-oauth-menu.png" height="248" /></figure>
+4. Copy the Bot User OAuth Token
+   <figure><img alt="Copy OAuth token screenshot" src="app-api-copy-oauth-token.png" height="209" /></figure>
+
+!!! example
+    Given the API token
+    <pre><code><b>xoxb</b>-<b>123456789012</b>-<b>1234567890123</b>-<b>4mt0t4l1YL3g1T5L4cK70k3N</b></code></pre>
+    and the channel ID `C001CH4NN3L` (obtained by using the [guide below](#getting_the_channel_id)), the Shoutrrr URL
+    should look like this:
+    <pre><code>slack://<b>xoxb</b>:<b>123456789012</b>-<b>1234567890123</b>-<b>4mt0t4l1YL3g1T5L4cK70k3N</b>@<b>C001CH4NN3L</b></code></pre>
+
+### Webhook tokens
+
+Get a Webhook URL using the legacy [WebHooks Integration](https://slack.com/apps/new/A0F7XDUAZ-incoming-webhooks), 
+or by using the [Getting started with Incoming Webhooks](https://api.slack.com/messaging/webhooks#getting_started) guide and
+replace the initial `https://hooks.slack.com/services/` part of the webhook URL with `slack://hook:` to get your Shoutrrr URL.
+
+!!! info "Slack Webhook URL"
+    <code>https://hooks.slack.com/services/<b>T00000000</b>/<b>B00000000</b>/<b>XXXXXXXXXXXXXXXXXXXXXXXX</b></code>
+
+!!! info "Shoutrrr URL"
+    <code>slack://hook:<b>T00000000</b>-<b>B00000000</b>-<b>XXXXXXXXXXXXXXXXXXXXXXXX</b>@webhook</code>
+
+## Getting the Channel ID
+
+!!! note ""
+    Only needed for API token. Use `webhook` as the channel for webhook tokens.
+
+1. In the channel you wish to post to, open **Channel Details** by clicking on the channel title.
+   <figure><img alt="Opening channel details screenshot" src="app-api-select-channel.png" height="270" /></figure>
+
+2. Copy the Channel ID from the bottom of the popup and append it to your Shoutrrr URL
+   <figure><img alt="Copy channel ID screenshot" src="app-api-channel-details-id.png" height="99" /></figure>

docs/index.md

@@ -9,27 +9,27 @@ Notification library for gophers and their furry friends.<br />
 Heavily inspired by <a href="https://github.com/caronc/apprise">caronc/apprise</a>.
 </p>
 
-<p align="center">
+<p align="center" class="badges">
     <a target="_blank" rel="noopener noreferrer" href="https://github.com/containrrr/shoutrrr/workflows/Main%20Workflow/badge.svg">
-        <img src="https://github.com/containrrr/shoutrrr/workflows/Main%20Workflow/badge.svg" alt="github actions workflow status" style="max-width:100%;">
+        <img src="https://github.com/containrrr/shoutrrr/workflows/Main%20Workflow/badge.svg" alt="github actions workflow status">
     </a>
     <a href="https://codecov.io/gh/containrrr/shoutrrr" rel="nofollow">
-        <img alt="codecov" src="https://codecov.io/gh/containrrr/shoutrrr/branch/master/graph/badge.svg" style="max-width:100%;">
+        <img alt="codecov" src="https://codecov.io/gh/containrrr/shoutrrr/branch/master/graph/badge.svg">
     </a>
     <a href="https://www.codacy.com/gh/containrrr/shoutrrr/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=containrrr/shoutrrr&amp;utm_campaign=Badge_Grade" rel="nofollow">
-        <img alt="Codacy Badge" src="https://app.codacy.com/project/badge/Grade/47eed72de79448e2a6e297d770355544" style="max-width:100%;">
+        <img alt="Codacy Badge" src="https://app.codacy.com/project/badge/Grade/47eed72de79448e2a6e297d770355544">
     </a>
     <a href="https://goreportcard.com/badge/github.com/containrrr/shoutrrr" rel="nofollow">
-        <img alt="report card" src="https://goreportcard.com/badge/github.com/containrrr/shoutrrr" style="max-width:100%;">
+        <img alt="report card" src="https://goreportcard.com/badge/github.com/containrrr/shoutrrr">
     </a>
     <a href="https://pkg.go.dev/github.com/containrrr/shoutrrr" rel="nofollow">
-        <img alt="go.dev reference" src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&amp;logoColor=white&amp;style=flat-square" style="max-width:100%;">
+        <img alt="go.dev reference" src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&amp;logoColor=white&amp;style=flat-square">
     </a>
     <a href="https://github.com/containrrr/shoutrrr">
-        <img alt="github code size in bytes" src="https://img.shields.io/github/languages/code-size/containrrr/shoutrrr.svg?style=flat-square" style="max-width:100%;">
+        <img alt="github code size in bytes" src="https://img.shields.io/github/languages/code-size/containrrr/shoutrrr.svg?style=flat-square">
     </a>
     <a href="https://github.com/containrrr/shoutrrr/blob/master/LICENSE">
-        <img alt="license" src="https://img.shields.io/github/license/containrrr/shoutrrr.svg?style=flat-square" style="max-width:100%;">
+        <img alt="license" src="https://img.shields.io/github/license/containrrr/shoutrrr.svg?style=flat-square">
     </a>
 </p>
 

docs/services/slack.md

@@ -1,22 +1,21 @@
 # Slack
 
-The slack notification service uses [Slack Webhook](https://api.slack.com/messaging/webhooks)s to send messages.  
-Follow the [Getting started with Incoming Webhooks](https://api.slack.com/messaging/webhooks#getting_started) guide and
-replace the initial `https://hooks.slack.com/services/` part of the webhook URL with `slack://` to get your Shoutrrr URL.
+!!! attention "New URL format"
+    The URL format for Slack has been changed to allow for API- as well as webhook tokens.  
+    Using the old format (`slack://xxxx/yyyy/zzzz`) will still work as before and will automatically be upgraded to
+    the new format when used.
 
-*Slack Webhook URL:*
+The Slack notification service uses either [Slack Webhooks](https://api.slack.com/messaging/webhooks) or the 
+[Bot API](https://api.slack.com/methods/chat.postMessage) to send messages.  
 
-!!! info ""
-    https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
+See the [guides](../guides/slack/index.md) for information on how to get your *token* and *channel*.
 
-Shoutrrr URL:
 
-!!! info ""
-    slack://T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
+## URL Format
 
+!!! note ""
+    Note that the token uses a prefix to determine the type, usually either `hook` (for webhooks) or `xoxb` (for bot API).
 
-## URL Format
-
 --8<-- "docs/services/slack/config.md"
 
 !!! info "Color format"
@@ -26,8 +25,12 @@ Shoutrrr URL:
 
 ## Examples
 
-!!! example
-    All fields set:
+!!! example "Bot API"
+    ```uri
+    slack://xoxb:123456789012-1234567890123-4mt0t4l1YL3g1T5L4cK70k3N@C001CH4NN3L?color=good&title=Great+News&icon=man-scientist&botname=Shoutrrrbot
+    ```
+
+!!! example "Webhook"
     ```uri
-    slack://ShoutrrrBot@T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX?color=good&title=Great+News
+    slack://hook:WNA3PBYV6-F20DUQND3RQ-Webc4MAvoacrpPakR8phF0zi@webhook?color=good&title=Great+News&icon=man-scientist&botname=Shoutrrrbot
     ```

docs/stylesheets/extra.css

@@ -0,0 +1,30 @@
+
+.md-typeset li img {
+    display: inline-block;
+}
+
+.md-typeset figure {
+    background: var(--md-code-bg-color);
+    display: block;
+    width: 100%;
+}
+
+.md-typeset figure img {
+    box-shadow: 2px 2px 4px #00000080;
+    padding: 3px;
+    background: var(--md-code-bg-color);
+}
+
+
+.md-typeset li img:last-child {
+    margin: 10px 0;
+}
+
+.badges img {
+    height: 20px;
+    max-width: 100%;
+    display: inline-block;
+    padding: 0;
+    background: transparent;
+    border-radius: 3px;
+}

go.mod

@@ -7,6 +7,7 @@ require (
 	github.com/google/uuid v1.1.5 // indirect
 	github.com/jarcoal/httpmock v1.0.4
 	github.com/klauspost/compress v1.11.7 // indirect
+	github.com/mattn/go-colorable v0.1.8
 	github.com/mitchellh/mapstructure v1.2.2 // indirect
 	github.com/nxadm/tail v1.4.6 // indirect
 	github.com/onsi/ginkgo v1.14.2