diff --git a/docs/channels/slack.md b/docs/channels/slack.md new file mode 100644 index 00000000..343d0383 --- /dev/null +++ b/docs/channels/slack.md @@ -0,0 +1,205 @@ +--- +sidebar_position: 7 +sidebar_label: 🗨️ Slack +--- + +import { FaSlack } from 'react-icons/fa'; + +#
Slack
+ +## Requirements + +- A Slack workspace where you have permissions to install apps +- Create a Slack app in your workspace +- Install the app to your workspace + +Please refer to `Dashboard -> Settings -> Slack Integration` for the step-by-step instructions. + +:::tip +You can use different Slack apps for different environments (development, staging, production) to keep your notifications organized. +::: + +## Important Features + +- Direct messages to users +- Channel messages +- Rich message formatting with blocks and attachments +- Interactive components (buttons, dropdowns) +- Thread replies +- Message updates and deletions +- User mention support +- Custom message formatting using Slack's Block Kit + +## Slack App Setup + +To send notifications through Slack, you'll need to: + +1. Create a Slack app in your workspace +2. Add the following OAuth scopes to your app: + - `chat:write` + - `im:write` + - `users:read` + - `users:read.email` +3. Install the app to your workspace +4. Copy the Bot User OAuth Token from your Slack app settings +5. Configure the token in NotificationAPI dashboard + +## Detailed Setup Instructions + +### 1. Create a Slack App + +1. Go to [Slack API](https://api.slack.com/apps) and sign in with your Slack account +2. Click "Create New App" +3. You'll be prompted to select a workspace. +4. After selecting a workspace, you'll see the app manifest editor. Use this basic manifest: + ```json + { + "display_information": { + "name": "NotificationAPI" + }, + "settings": { + "org_deploy_enabled": false, + "socket_mode_enabled": false, + "is_hosted": false, + "token_rotation_enabled": false + } + } + ``` +5. Review the app summary and click "Create" to finalize your app creation + +### 2. Configure OAuth Scopes + +1. In your app settings, navigate to "OAuth & Permissions" in the sidebar +2. Scroll to "Scopes" section +3. Under "Bot Token Scopes", add the following scopes: + - `chat:write` - Send messages as your app + - `im:write` - Send direct messages to users + - `users:read` - View basic user information + - `users:read.email` - Look up users by email + +### 3. Install the App + +1. After adding scopes, scroll to the top of "OAuth & Permissions" page +2. Click "Install to Workspace" +3. Review the permissions and click "Allow" +4. After installation, you'll see a "Bot User OAuth Token" - save this token securely + +### 4. Configure in NotificationAPI Dashboard + +1. Log in to your NotificationAPI dashboard +2. Go to "Settings" → "Slack Integration" +3. Enter the Bot User OAuth Token you saved earlier +4. Click "Save" + +### 5. Testing the Integration + +1. Create a test notification template in NotificationAPI dashboard +2. Configure it to use the Slack channel +3. Send a test notification to verify the setup + +### Common Issues and Solutions + +- **App Not in Channel**: If sending to channels, use `/invite @YourAppName` in the channel +- **Invalid Token**: Double-check the Bot User OAuth Token in dashboard settings +- **Missing Permissions**: Verify all required scopes are added in Slack app settings +- **User Not Found**: Ensure user email in NotificationAPI matches their Slack email + +### Security Best Practices + +1. **Token Security**: + + - Never share your Bot User OAuth Token + - Rotate tokens if compromised + - Use different apps/tokens for different environments + +2. **Access Control**: + - Regularly audit app installations + - Remove unused installations + - Review channel memberships periodically + +## Message Formatting + +NotificationAPI supports Slack's Block Kit for rich message formatting. You can use: + +- Text blocks with markdown +- Sections with fields +- Buttons and interactive elements +- Images and other media +- Dividers and context blocks + +Example template: + +```json +{ + "blocks": [ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "Hello {{userName}}! You have a new notification" + } + }, + { + "type": "divider" + }, + { + "type": "section", + "fields": [ + { + "type": "mrkdwn", + "text": "*Type:*\n{{notificationType}}" + }, + { + "type": "mrkdwn", + "text": "*When:*\n{{timestamp}}" + } + ] + } + ] +} +``` + +## User Identification + +To send direct messages to users, you need to identify them using one of these methods: + +1. Slack User ID +2. Email address (must match the user's Slack email) + +When using email addresses, NotificationAPI automatically resolves them to Slack User IDs. + +## Channel Messages + +To send messages to channels: + +1. Invite your Slack app to the target channel using `/invite @YourAppName` +2. Use the channel ID or channel name in your notification settings + +:::caution +Make sure your Slack app is invited to channels before attempting to send messages. +::: + +## Tracking Options + +The following events are tracked and reported in our logs and insights features: + +- Message delivery +- Message failures +- User resolution status +- Channel availability + +## Best Practices + +1. **Rate Limiting**: Slack has rate limits for sending messages. NotificationAPI handles these automatically with smart retries. + +2. **User Experience**: + + - Use clear and concise messages + - Leverage formatting for better readability + - Include relevant links and context + - Use interactive elements when appropriate + +3. **Error Handling**: + - NotificationAPI automatically handles common errors + - Failed deliveries are retried with exponential backoff + - Invalid user/channel errors are reported in logs diff --git a/package-lock.json b/package-lock.json index c06e4c72..9b5b5d02 100644 --- a/package-lock.json +++ b/package-lock.json @@ -26,6 +26,7 @@ "prism-react-renderer": "^2.3.0", "react": "^18.0.0", "react-dom": "^18.0.0", + "react-icons": "^5.5.0", "url-loader": "^4.1.1" }, "devDependencies": { @@ -15051,6 +15052,15 @@ "react-dom": "^16.6.0 || ^17.0.0 || ^18.0.0" } }, + "node_modules/react-icons": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/react-icons/-/react-icons-5.5.0.tgz", + "integrity": "sha512-MEFcXdkP3dLo8uumGI5xN3lDFNsRtrjbOEKDLD7yv76v4wpnEq2Lt2qeHaQOr34I/wPN3s3+N08WkQ+CW37Xiw==", + "license": "MIT", + "peerDependencies": { + "react": "*" + } + }, "node_modules/react-is": { "version": "16.13.1", "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz", @@ -28114,6 +28124,12 @@ "shallowequal": "^1.1.0" } }, + "react-icons": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/react-icons/-/react-icons-5.5.0.tgz", + "integrity": "sha512-MEFcXdkP3dLo8uumGI5xN3lDFNsRtrjbOEKDLD7yv76v4wpnEq2Lt2qeHaQOr34I/wPN3s3+N08WkQ+CW37Xiw==", + "requires": {} + }, "react-is": { "version": "16.13.1", "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz", diff --git a/package.json b/package.json index 25f40a7f..909207b2 100644 --- a/package.json +++ b/package.json @@ -38,6 +38,7 @@ "prism-react-renderer": "^2.3.0", "react": "^18.0.0", "react-dom": "^18.0.0", + "react-icons": "^5.5.0", "url-loader": "^4.1.1" }, "devDependencies": {