Debian Codegraph @

docs/guides/slack/index.md

raw
1 # Slack Guides
2
3 ## Overview
4
5 Guides for setting up the [Slack](../../services/chat/slack/index.md) service, including obtaining tokens (Bot API or Webhook) and channel IDs. The Slack service supports customization options like bot name, icon, color, title, and threading.
6
7 ## Getting a Token
8
9 To send messages, use either a Bot API token (preferred for full features) or a Webhook token. Only Webhook tokens allow customizing the bot name or icon without the Bot API.
10
11 ### Bot API (Preferred)
12 <!-- markdownlint-disable -->
13 1. Create a new App for your bot using the [Basic app setup guide](https://api.slack.com/authentication/basics).
14 2. Install the App into your workspace ([Slack installation guide](https://api.slack.com/authentication/basics#installing)).
15 3. From [Apps](https://api.slack.com/apps), select your new App and go to **OAuth & Permissions**.
16 <figure><img alt="Slack app management menu screenshot" src="app-api-oauth-menu.png" height="248" /></figure>
17 4. Copy the Bot User OAuth Token.
18 <figure><img alt="Copy OAuth token screenshot" src="app-api-copy-oauth-token.png" height="209" /></figure>
19 <!-- markdownlint-restore -->
20 !!! example
21 Given the API token `xoxb-123456789012-1234567890123-4mt0t4l1YL3g1T5L4cK70k3N` and channel ID `C001CH4NN3L` (obtained via the [Slack service docs](../../services/chat/slack/index.md#getting_the_channel_id)), the Shoutrrr URL should look like:
22 ```url
23 slack://xoxb:123456789012-1234567890123-4mt0t4l1YL3g1T5L4cK70k3N@C001CH4NN3L
24 ```
25
26 ### Webhook Tokens
27
28 Get a Webhook URL using the legacy [WebHooks Integration](https://slack.com/apps/new/A0F7XDUAZ-incoming-webhooks) or the [Getting started with Incoming Webhooks](https://api.slack.com/messaging/webhooks#getting_started) guide. Replace the initial `https://hooks.slack.com/services/` part with `slack://hook:` to form the Shoutrrr URL.
29
30 !!! info "Slack Webhook URL"
31 ```url
32 https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
33 ```
34
35 !!! info "Shoutrrr URL"
36 ```url
37 slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook
38 ```
39
40 ## Getting the Channel ID
41
42 !!! note
43 Only needed for Bot API tokens. Use `webhook` as the channel for Webhook tokens.
44 <!-- markdownlint-disable -->
45 1. In the channel you wish to post to, open **Channel Details** by clicking on the channel title.
46 <figure><img alt="Opening channel details screenshot" src="app-api-select-channel.png" height="270" /></figure>
47
48 2. Copy the Channel ID from the bottom of the popup and append it to your Shoutrrr URL.
49 <figure><img alt="Copy channel ID screenshot" src="app-api-channel-details-id.png" height="99" /></figure>
50 <!-- markdownlint-restore -->
51 ## Additional Configuration
52
53 Customize notifications using query parameters in the URL:
54
55 | Parameter | Description | Example Value |
56 |--------------|-----------------------------------------------------------------------------|-------------------|
57 | `botname` | Bot display name (overrides default). | `ShoutrrrBot` |
58 | `icon` | Emoji (e.g., `:robot_face:`) or URL for the bot icon. | `:robot_face:` |
59 | `color` | Message border color (e.g., `good`, `warning`, `danger`, or hex like `%23ff8000`). | `good` |
60 | `title` | Message title (prepended above the message). | `Alert` |
61 | `thread_ts` | Timestamp of the parent message for threading (replies). | `1234567890.123456` |
62
63 !!! example "Full URL with Customizations"
64 ```url
65 slack://xoxb:123456789012-1234567890123-4mt0t4l1YL3g1T5L4cK70k3N@C001CH4NN3L?botname=ShoutrrrBot&color=good&title=Great+News& icon=%3Arobot_face%3A&thread_ts=1234567890.123456
66 ```
67
68 !!! Note
69 For colors, escape `#` as `%23` in URLs (e.g., `#ff8000` becomes `%23ff8000`). Use `thread_ts` to reply in threads.