Skip to content
This repository was archived by the owner on Aug 14, 2025. It is now read-only.

Commit e2847a6

Browse files
mbasadimbasadi
authored
Merge pull request #179 from notificationapi-com/hZ8hHKYZ/3212-slack
docs(slack): add comprehensive Slack integration documentation
2 parents 1193cb6 + f3e5526 commit e2847a6

File tree

3 files changed

+222
-0
lines changed

3 files changed

+222
-0
lines changed

‎docs/channels/slack.md

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
sidebar_position: 7
3+
sidebar_label: 🗨️ Slack
4+
---
5+
6+
import { FaSlack } from 'react-icons/fa';
7+
8+
# <div><FaSlack /> Slack</div>
9+
10+
## Requirements
11+
12+
- A Slack workspace where you have permissions to install apps
13+
- Create a Slack app in your workspace
14+
- Install the app to your workspace
15+
16+
Please refer to `Dashboard -> Settings -> Slack Integration` for the step-by-step instructions.
17+
18+
:::tip
19+
You can use different Slack apps for different environments (development, staging, production) to keep your notifications organized.
20+
:::
21+
22+
## Important Features
23+
24+
- Direct messages to users
25+
- Channel messages
26+
- Rich message formatting with blocks and attachments
27+
- Interactive components (buttons, dropdowns)
28+
- Thread replies
29+
- Message updates and deletions
30+
- User mention support
31+
- Custom message formatting using Slack's Block Kit
32+
33+
## Slack App Setup
34+
35+
To send notifications through Slack, you'll need to:
36+
37+
1. Create a Slack app in your workspace
38+
2. Add the following OAuth scopes to your app:
39+
- `chat:write`
40+
- `im:write`
41+
- `users:read`
42+
- `users:read.email`
43+
3. Install the app to your workspace
44+
4. Copy the Bot User OAuth Token from your Slack app settings
45+
5. Configure the token in NotificationAPI dashboard
46+
47+
## Detailed Setup Instructions
48+
49+
### 1. Create a Slack App
50+
51+
1. Go to [Slack API](https://api.slack.com/apps) and sign in with your Slack account
52+
2. Click "Create New App"
53+
3. You'll be prompted to select a workspace.
54+
4. After selecting a workspace, you'll see the app manifest editor. Use this basic manifest:
55+
```json
56+
{
57+
"display_information": {
58+
"name": "NotificationAPI"
59+
},
60+
"settings": {
61+
"org_deploy_enabled": false,
62+
"socket_mode_enabled": false,
63+
"is_hosted": false,
64+
"token_rotation_enabled": false
65+
}
66+
}
67+
```
68+
5. Review the app summary and click "Create" to finalize your app creation
69+
70+
### 2. Configure OAuth Scopes
71+
72+
1. In your app settings, navigate to "OAuth & Permissions" in the sidebar
73+
2. Scroll to "Scopes" section
74+
3. Under "Bot Token Scopes", add the following scopes:
75+
- `chat:write` - Send messages as your app
76+
- `im:write` - Send direct messages to users
77+
- `users:read` - View basic user information
78+
- `users:read.email` - Look up users by email
79+
80+
### 3. Install the App
81+
82+
1. After adding scopes, scroll to the top of "OAuth & Permissions" page
83+
2. Click "Install to Workspace"
84+
3. Review the permissions and click "Allow"
85+
4. After installation, you'll see a "Bot User OAuth Token" - save this token securely
86+
87+
### 4. Configure in NotificationAPI Dashboard
88+
89+
1. Log in to your NotificationAPI dashboard
90+
2. Go to "Settings" → "Slack Integration"
91+
3. Enter the Bot User OAuth Token you saved earlier
92+
4. Click "Save"
93+
94+
### 5. Testing the Integration
95+
96+
1. Create a test notification template in NotificationAPI dashboard
97+
2. Configure it to use the Slack channel
98+
3. Send a test notification to verify the setup
99+
100+
### Common Issues and Solutions
101+
102+
- **App Not in Channel**: If sending to channels, use `/invite @YourAppName` in the channel
103+
- **Invalid Token**: Double-check the Bot User OAuth Token in dashboard settings
104+
- **Missing Permissions**: Verify all required scopes are added in Slack app settings
105+
- **User Not Found**: Ensure user email in NotificationAPI matches their Slack email
106+
107+
### Security Best Practices
108+
109+
1. **Token Security**:
110+
111+
- Never share your Bot User OAuth Token
112+
- Rotate tokens if compromised
113+
- Use different apps/tokens for different environments
114+
115+
2. **Access Control**:
116+
- Regularly audit app installations
117+
- Remove unused installations
118+
- Review channel memberships periodically
119+
120+
## Message Formatting
121+
122+
NotificationAPI supports Slack's Block Kit for rich message formatting. You can use:
123+
124+
- Text blocks with markdown
125+
- Sections with fields
126+
- Buttons and interactive elements
127+
- Images and other media
128+
- Dividers and context blocks
129+
130+
Example template:
131+
132+
```json
133+
{
134+
"blocks": [
135+
{
136+
"type": "section",
137+
"text": {
138+
"type": "mrkdwn",
139+
"text": "Hello {{userName}}! You have a new notification"
140+
}
141+
},
142+
{
143+
"type": "divider"
144+
},
145+
{
146+
"type": "section",
147+
"fields": [
148+
{
149+
"type": "mrkdwn",
150+
"text": "*Type:*\n{{notificationType}}"
151+
},
152+
{
153+
"type": "mrkdwn",
154+
"text": "*When:*\n{{timestamp}}"
155+
}
156+
]
157+
}
158+
]
159+
}
160+
```
161+
162+
## User Identification
163+
164+
To send direct messages to users, you need to identify them using one of these methods:
165+
166+
1. Slack User ID
167+
2. Email address (must match the user's Slack email)
168+
169+
When using email addresses, NotificationAPI automatically resolves them to Slack User IDs.
170+
171+
## Channel Messages
172+
173+
To send messages to channels:
174+
175+
1. Invite your Slack app to the target channel using `/invite @YourAppName`
176+
2. Use the channel ID or channel name in your notification settings
177+
178+
:::caution
179+
Make sure your Slack app is invited to channels before attempting to send messages.
180+
:::
181+
182+
## Tracking Options
183+
184+
The following events are tracked and reported in our logs and insights features:
185+
186+
- Message delivery
187+
- Message failures
188+
- User resolution status
189+
- Channel availability
190+
191+
## Best Practices
192+
193+
1. **Rate Limiting**: Slack has rate limits for sending messages. NotificationAPI handles these automatically with smart retries.
194+
195+
2. **User Experience**:
196+
197+
- Use clear and concise messages
198+
- Leverage formatting for better readability
199+
- Include relevant links and context
200+
- Use interactive elements when appropriate
201+
202+
3. **Error Handling**:
203+
- NotificationAPI automatically handles common errors
204+
- Failed deliveries are retried with exponential backoff
205+
- Invalid user/channel errors are reported in logs

‎package-lock.json

Lines changed: 16 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
"prism-react-renderer": "^2.3.0",
3939
"react": "^18.0.0",
4040
"react-dom": "^18.0.0",
41+
"react-icons": "^5.5.0",
4142
"url-loader": "^4.1.1"
4243
},
4344
"devDependencies": {

0 commit comments

Comments
 (0)