From f05747de923e0a3d2ee87bbbedeead21f53177cf Mon Sep 17 00:00:00 2001 From: mbasadi Date: Thu, 22 May 2025 11:09:36 -0400 Subject: [PATCH 1/3] Enhance Slack integration documentation - Updated the Slack integration guide to provide a clearer overview and detailed requirements for connecting NotificationAPI with Slack. - Added a frontend integration example for various frameworks, including React, Next.js, Remix, Angular, and Vue, to facilitate user account connections. - Improved organization of content and clarified setup instructions, ensuring users can easily follow the integration process. These changes aim to streamline the integration experience and enhance user understanding of Slack notifications with NotificationAPI. --- docs/channels/slack.md | 380 ++++++++++++++++++++++------------------- 1 file changed, 208 insertions(+), 172 deletions(-) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 343d038..3863f2b 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -3,203 +3,239 @@ sidebar_position: 7 sidebar_label: 🗨️ Slack --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; 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. +## Overview -:::tip -You can use different Slack apps for different environments (development, staging, production) to keep your notifications organized. -::: +Integrate Slack with NotificationAPI to send notifications directly to your users' Slack channels. This guide will help you connect your Slack workspace and provide a ready-to-use frontend integration example for various frameworks. -## Important Features +## Requirements -- 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 +- A Slack workspace +- Access to NotificationAPI ## 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}}" - } - ] +To enable Slack notifications, simply install the NotificationAPI Slack app in your workspace. You can also allow your users to connect their Slack accounts using the integration component below. + +## Frontend Integration Example + +Use the following component to let your users connect their Slack accounts. The example supports React, Next.js, Remix, Nuxt3, Angular, Vue, and Vanilla JS. Make sure to set the `environment` prop to your NotificationAPI environment (e.g., `production`, `staging`). + + + +```jsx +import React, { useState } from 'react'; + +const SlackIntegration = ({ userId }) => { + const [channel, setChannel] = useState(''); + const handleSlackAuth = () => { + if (!channel) { + alert('Enter a channel name'); + return; } - ] -} + const url = + 'https://slack.com/oauth/v2/authorize?' + + 'client_id=1146598856352.8825220259395' + + '&scope=chat:write,channels:read' + + `&redirect_uri=https://app.notificationapi.com/slack/oauth/callback/${CLIENT_ID}/userId/${userId}`; + window.open(url, 'slack_auth', 'width=500,height=600'); + }; + return ( +
+ setChannel(e.target.value)} + placeholder="Channel (e.g. #general)" + /> + +
+ ); +}; ``` -## 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) +```jsx +'use client'; -When using email addresses, NotificationAPI automatically resolves them to Slack User IDs. +import React, { useState } from 'react'; -## Channel Messages +const SlackIntegration = ({ userId }) => { + const [channel, setChannel] = useState(''); + const handleSlackAuth = () => { + if (!channel) { + alert('Enter a channel name'); + return; + } + const url = + 'https://slack.com/oauth/v2/authorize?' + + 'client_id=1146598856352.8825220259395' + + '&scope=chat:write,channels:read' + + `&redirect_uri=https://app.notificationapi.com/slack/oauth/callback/${CLIENT_ID}/userId/${userId}`; + window.open(url, 'slack_auth', 'width=500,height=600'); + }; + return ( +
+ setChannel(e.target.value)} + placeholder="Channel (e.g. #general)" + /> + +
+ ); +}; + +export default SlackIntegration; +``` -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. -::: +```jsx +import { useState } from 'react'; -## Tracking Options +const SlackIntegration = ({ userId }) => { + const [channel, setChannel] = useState(''); -The following events are tracked and reported in our logs and insights features: + const handleSlackAuth = () => { + if (!channel) { + alert('Enter a channel name'); + return; + } + const url = + 'https://slack.com/oauth/v2/authorize?' + + 'client_id=1146598856352.8825220259395' + + '&scope=chat:write,channels:read' + + `&redirect_uri=https://app.notificationapi.com/slack/oauth/callback/${CLIENT_ID}/userId/${userId}`; + window.open(url, 'slack_auth', 'width=500,height=600'); + }; + + return ( +
+ setChannel(e.target.value)} + placeholder="Channel (e.g. #general)" + /> + +
+ ); +}; + +export default SlackIntegration; +``` -- Message delivery -- Message failures -- User resolution status -- Channel availability + + + +```jsx + + + -## Best Practices +``` -1. **Rate Limiting**: Slack has rate limits for sending messages. NotificationAPI handles these automatically with smart retries. + + + +```jsx +import { Component } from '@angular/core'; + +@Component({ + selector: 'app-slack-integration', + template: ` +
+ + +
+ ` +}) +export class SlackIntegrationComponent { + channel: string = ''; + + @Input() userId!: string; + + handleSlackAuth() { + if (!this.channel) { + alert('Enter a channel name'); + return; + } + const url = + "https://slack.com/oauth/v2/authorize?" + + "client_id=1146598856352.8825220259395" + + "&scope=chat:write,channels:read" + + `&redirect_uri=https://app.notificationapi.com/slack/oauth/callback/${CLIENT_ID}/userId/${this.userId}`; + window.open(url, "slack_auth", "width=500,height=600"); + } +} -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 +> **Note:** +> +> - Replace `userId` with your application's user identifier. +> - `CLIENT_ID`is your NotificationAPI account clientId. You can get it from [here](https://app.notificationapi.com/environments). +> - The `redirect_uri` should match your NotificationAPI environment and user ID. +> - For more details, see the [NotificationAPI documentation](https://docs.notificationapi.com/). From 094f614a19c300b846e816fca9c068c62d4833dc Mon Sep 17 00:00:00 2001 From: mbasadi Date: Thu, 22 May 2025 11:10:33 -0400 Subject: [PATCH 2/3] Update Slack integration documentation to reflect environment changes - Modified the frontend integration example to specify 'testing' as a valid environment option alongside 'production'. - This update ensures users have accurate information for configuring their NotificationAPI Slack integration. --- docs/channels/slack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 3863f2b..9c03ae9 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -24,7 +24,7 @@ To enable Slack notifications, simply install the NotificationAPI Slack app in y ## Frontend Integration Example -Use the following component to let your users connect their Slack accounts. The example supports React, Next.js, Remix, Nuxt3, Angular, Vue, and Vanilla JS. Make sure to set the `environment` prop to your NotificationAPI environment (e.g., `production`, `staging`). +Use the following component to let your users connect their Slack accounts. The example supports React, Next.js, Remix, Nuxt3, Angular, Vue, and Vanilla JS. Make sure to set the `environment` prop to your NotificationAPI environment (e.g., `production`, `testing`). Date: Thu, 22 May 2025 11:12:12 -0400 Subject: [PATCH 3/3] Update Slack integration documentation to specify CLIENT_ID prop - Revised the frontend integration example to clarify the use of the `CLIENT_ID` prop for connecting Slack accounts. - This change ensures users have accurate and up-to-date information for configuring their NotificationAPI Slack integration. --- docs/channels/slack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 9c03ae9..0d9f4da 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -24,7 +24,7 @@ To enable Slack notifications, simply install the NotificationAPI Slack app in y ## Frontend Integration Example -Use the following component to let your users connect their Slack accounts. The example supports React, Next.js, Remix, Nuxt3, Angular, Vue, and Vanilla JS. Make sure to set the `environment` prop to your NotificationAPI environment (e.g., `production`, `testing`). +Use the following component to let your users connect their Slack accounts. The example supports React, Next.js, Remix, Nuxt3, Angular, Vue, and Vanilla JS. Make sure to set the `CLIENT_ID` prop to your NotificationAPI environment (e.g., `production`, `testing`).