From f3e55269b8c7c2a25bd9d04ed75f1a5debc1e4b8 Mon Sep 17 00:00:00 2001 From: mbasadi Date: Wed, 23 Apr 2025 10:52:40 -0400 Subject: [PATCH] Add react-icons dependency and create Slack integration documentation - Added `react-icons` version 5.5.0 to both `package.json` and `package-lock.json`. - Created a new documentation file for Slack integration, detailing setup requirements, features, and best practices for using Slack with NotificationAPI. These changes enhance the project's capabilities and provide clear guidance for users integrating with Slack. --- docs/channels/slack.md | 205 +++++++++++++++++++++++++++++++++++++++++ package-lock.json | 16 ++++ package.json | 1 + 3 files changed, 222 insertions(+) create mode 100644 docs/channels/slack.md 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": {