| 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. |