Connecting Slack Workspaces

Connecting Slack workspaces establishes the authorization required for Magentrix to send automated notifications to Slack channels and users. Each workspace connection creates the credentials that Slack Message automation tasks use to deliver record cards to your team's collaboration environment. At least one active workspace connection must exist before any Slack messaging functionality can operate.

This page covers the authorization process using the Magentrix Slack App, the recommended approach for most organizations. For organizations requiring custom branding or full control over their Slack application, see Creating a Custom Slack App.

Prerequisites

Before connecting a Slack workspace, ensure the following requirements are met:

• Slack Integration Enabled: Slack Integration must be enabled in Setup > Extend > Slack. The Enable toggle must be switched ON and the status indicator must show "Connected."
• Slack Feature License: Your portal must have the Slack feature licensed. If Slack settings are not available, contact your Customer Success Manager.
• Magentrix Administrator Access: You must have Administrator System Role permissions with access to Setup > Extend > Slack.
• Slack Workspace Permissions: You must have administrator privileges or app installation permissions in the target Slack workspace. The person completing the OAuth authorization must be able to approve app installations in Slack.

Authorization Overview

The workspace authorization process uses OAuth, an industry-standard protocol for secure authorization between applications. When you authorize a workspace, you grant Magentrix specific permissions to interact with that Slack workspace on behalf of your organization.

The authorization flow involves these steps:

1. Initiate authorization from Magentrix by clicking Connect Workspace
2. Select the app type (Magentrix Slack App or Custom Slack App)
3. Redirect to Slack to identify your workspace
4. Sign in to Slack if not already authenticated
5. Review and approve the requested permissions on Slack's consent screen
6. Redirect back to Magentrix upon successful authorization
7. Workspace connections appear in the Connected Workspaces table

Upon successful authorization, Magentrix automatically creates both a bot token and a user token connection for the workspace, providing flexibility for different messaging scenarios.

Initiating Workspace Authorization

To begin connecting a Slack workspace:

1. Navigate to Setup > Extend > Slack
2. Verify that Slack Integration is enabled (status shows "Connected")
3. Click the Connect Workspace button in the Connected Workspaces section
4. The authorization dialog appears with app type options

Selecting an App Type

The authorization dialog presents two options:

Magentrix Slack App: The pre-configured, multi-tenant application managed by Magentrix. This option is recommended for most organizations because it requires no custom configuration and provides immediate connectivity. Select this option and click Authorize to proceed.

Custom Slack App: Your organization's own Slack application. This option requires prior configuration of a Custom Slack App in Slack's developer portal and registration as a Connected App in Magentrix. Select this option only if you have already completed the Custom Slack App setup process. See Creating a Custom Slack App for configuration instructions.

Slack Workspace Identification

After clicking Authorize with the Magentrix Slack App selected, you are redirected to Slack's sign-in workflow. The first step asks you to identify which Slack workspace should be connected.

Entering Your Workspace URL

The Slack page displays a field labeled "Enter your workspace's Slack URL" where you enter the URL of your target Slack workspace:

• Enter your workspace URL in the format: your-workspace.slack.com
• This determines which Slack workspace will receive the authorization request
• Click Continue to proceed to authentication

Finding Your Workspace URL

If you are unsure of your workspace URL:

• Click the "Find your workspaces" link on the Slack page
• Open your Slack application and look at the workspace name in the upper left corner
• Check your browser address bar when viewing Slack in a web browser

Authentication

After entering the workspace URL, Slack may prompt you to sign in if you are not already authenticated:

• Enter your Slack email address and password
• Complete any two-factor authentication if enabled for your Slack account
• Upon successful authentication, you proceed to the consent screen

If you are already signed in to the target workspace in your browser, you may skip directly to the consent screen.

OAuth Consent Screen

The OAuth consent screen is where you review and approve the permissions that Magentrix requires to interact with your Slack workspace. This screen is presented by Slack, not Magentrix, and displays detailed information about what access you are granting.

Consent Screen Elements

App Name: Displays "Magentrix" as the application requesting access.

Workspace Selector: Shows which Slack workspace you are authorizing. If you belong to multiple workspaces, a dropdown allows you to select the correct one. Verify this displays the intended workspace before proceeding.

Permissions Review Panel: Lists all permissions being requested, organized into two categories: information the app can view and actions the app can take.

Consent Controls: Provides Cancel and Allow buttons to abort or complete the authorization.

Understanding the "App is not approved by Slack" Notice

The consent screen displays a notice stating "App is not approved by Slack" with an explanation that apps are reviewed for quality before they are listed in the Slack Marketplace.

This notice appears because the Magentrix Slack App is not listed in the public Slack App Directory. This is expected and normal for the following reasons:

• The Magentrix Slack App is a privately distributed, multi-tenant application
• It is designed specifically for Magentrix portal integration rather than general Slack Marketplace distribution
• The app operates fully within Slack's security and permission framework
• This distribution model is standard for enterprise B2B integrations

Reviewing Requested Permissions

The consent screen displays permissions in two sections:

Information "Magentrix" can view:

• Content and info about you
• Content and info about channels and conversations
• Content and info about your workspace

Actions "Magentrix" can take:

• Perform actions as you
• Perform actions in channels and conversations
• Additional actions (expandable under "More permissions")

These permissions enable Magentrix to look up Slack channels and users for automation configuration, send messages to channels and direct messages, and display record information in formatted message cards.

Completing Authorization

After reviewing the permissions:

• Click Allow to grant the requested permissions and complete authorization
• Click Cancel to abort the process without creating a connection

If you click Allow, Slack processes the authorization and redirects you back to Magentrix.

Authorization Results

Successful Authorization

Upon successful authorization, the following occurs:

1. Slack issues access tokens for the Magentrix Slack App within your workspace
2. Slack redirects you back to the Magentrix Slack Settings page
3. The workspace appears in the Connected Workspaces table
4. Both a bot token and a user token connection are created automatically
5. The connections are immediately available for use in Slack Message automation tasks

Dual Token Creation

When you authorize a workspace, Magentrix automatically creates two connections:

Bot Token Connection: Enables posting messages to Slack channels where the bot is a member. Messages sent via the bot token appear as coming from the Magentrix app with its configured name and icon.

User Token Connection: Enables sending direct messages to individual Slack users. Messages sent via the user token appear as coming from the Magentrix user who completed the authorization.

Both connections appear as separate rows in the Connected Workspaces table, sharing the same Workspace Name and Workspace ID but with different Token Type values ("bot" and "user").

Failed or Cancelled Authorization

If authorization fails or is cancelled:

• No workspace connection is created in Magentrix
• The Connected Workspaces table remains unchanged
• The Slack Settings page continues to show existing connections (if any) or "No Slack Workspace connected yet"
• You can attempt authorization again by clicking Connect Workspace

Common reasons for authorization failure:

• Clicking Cancel on the Slack consent screen
• Closing the browser window before completing authorization
• Insufficient permissions in the Slack workspace to install apps
• Network connectivity issues during the OAuth redirect

Understanding the Connected Workspaces Table

After successful authorization, your workspace connections appear in the Connected Workspaces table. Understanding each column helps you manage connections effectively.

Connection Details

Workspace Name: The display name of your Slack workspace as configured in Slack settings. This helps you identify which workspace the connection belongs to when managing multiple workspace connections.

Workspace ID: Slack's unique technical identifier for the workspace (for example, "TCFC2DBB2"). This ID is used internally for message routing and remains constant even if the workspace name changes.

Slack User ID: The Slack user identifier associated with this connection. For bot tokens, this displays the bot's user ID. For user tokens, this displays the Slack user ID of the person who authorized the connection.

Token Type: Indicates whether the connection is a "bot" token or "user" token. This distinction is critical for understanding messaging capabilities:

• bot: Can post to channels where the bot is a member; cannot send direct messages to human users
• user: Can send direct messages to any user in the workspace; can also post to accessible channels

Active: A checkbox indicating the connection's current status. Active connections (checked) can be used for messaging. Inactive connections (unchecked) have been revoked or expired and cannot deliver messages.

Connection Date: The date and time when the authorization was completed. This helps track when connections were established and may indicate when reauthorization might be needed.

Owner: The Magentrix user who completed the authorization process. For user token connections, this user's Magentrix language preference affects how direct messages are translated.

App: Identifies which Slack app was used for the connection. Displays "Magentrix" with the app ID for connections using the Magentrix Slack App, or shows the Custom Slack App identifier for custom app connections.

Token Type Selection for Automation Tasks

When configuring Slack Message automation tasks, you must select which connection to use. The token type determines what messaging capabilities are available.

When to Use Bot Tokens

Select a bot token connection when:

• Posting messages to Slack channels (public or private)
• Messages should appear as coming from the Magentrix app rather than an individual
• You want consistent app branding on automated notifications
• The target is a team channel where multiple people should see the notification

When to Use User Tokens

Select a user token connection when:

• Sending direct messages to individual Slack users
• Private notifications are required for specific recipients
• The message should not be visible to other team members

Connecting Additional Workspaces

Organizations with multiple Slack workspaces can connect all relevant workspaces to a single Magentrix portal. Each workspace maintains independent connection credentials and can be targeted by different automation tasks.

To connect additional workspaces:

1. Navigate to Setup > Extend > Slack
2. Click Connect Workspace
3. Complete the authorization process for the new workspace
4. Repeat for each workspace that should receive automated notifications

There is no limit to the number of workspaces that can be connected to a single portal.

Use Cases for Multiple Workspaces

• Regional Teams: Connect separate workspaces for different geographic regions, routing notifications to the appropriate regional team
• Department Separation: Connect workspaces for different departments (Sales, Support, Operations) to deliver targeted notifications
• Partner Workspaces: Connect partner organization workspaces for partner-facing notifications (requires partner Slack admin cooperation)
• Environment Separation: Connect different workspaces for production versus testing notification scenarios

Bot Channel Membership

For the Magentrix bot to post messages to Slack channels, it must be a member of those channels. This requirement applies especially to private channels.

Public Channels

For public channels, the bot may be able to post messages without explicit invitation, depending on your Slack workspace settings. However, explicitly inviting the bot ensures reliable message delivery.

Private Channels

For private channels, you must explicitly invite the bot before configuring automation tasks:

1. Open the private channel in Slack
2. Click the channel name to view channel details
3. Click "Add people" or navigate to the Integrations tab
4. Search for and add the Magentrix bot to the channel
5. Verify the bot appears in the channel member list

Searching and Filtering Connections

The search bar above the Connected Workspaces table helps you locate specific connections:

• Enter a workspace name to filter connections for that workspace
• Enter an owner name to find connections authorized by a specific administrator
• Search is case-insensitive and filters results in real-time as you type
• Clear the search field to display all connections

Searching is particularly useful when managing many workspace connections or when multiple administrators have authorized connections.

Next Steps After Authorization

After successfully connecting a Slack workspace:

1. Invite Bot to Private Channels: If automations will target private channels, invite the Magentrix bot to those channels before configuring tasks
2. Plan Automation Tasks: Identify which record events should trigger Slack notifications and which channels or users should receive them
3. Create Slack Message Tasks: Add Slack Message tasks to automations on supported entities (Lead, Opportunity, Case, Account, Contact). See Creating Slack Message Tasks for Automations for configuration instructions
4. Test Message Delivery: Create or update test records to trigger automations and verify messages appear correctly in Slack
5. Monitor Connections: Periodically verify connections remain active in the Connected Workspaces table

Troubleshooting

Authorization Redirects to Wrong Workspace

If you are redirected to an unexpected workspace during authorization:

• You may be signed in to multiple Slack workspaces in your browser
• Verify the workspace displayed in the consent screen workspace selector
• Use the dropdown to select the correct workspace before clicking Allow
• Alternatively, sign out of other Slack workspaces before starting authorization

Insufficient Permissions Error

If Slack displays an error about insufficient permissions:

• You may not have app installation permissions in the target workspace
• Contact your Slack workspace administrator to request installation privileges
• Alternatively, ask a Slack administrator to complete the authorization on your behalf

Connection Not Appearing After Authorization

If the workspace does not appear in the Connected Workspaces table after authorization:

• Refresh the Slack Settings page in Magentrix
• Verify you completed the full authorization flow (clicked Allow on the consent screen)
• Check that you were redirected back to Magentrix after authorization
• Attempt the authorization process again if the connection is missing

Only One Token Type Created

If only a bot token or only a user token appears after authorization:

• This may indicate a partial authorization or permission restriction
• Check the Slack workspace app settings to verify installation status
• Attempt reauthorization to create both token types
• Contact Magentrix support if the issue persists

Workspace connection authorization establishes the foundation for all Slack messaging capabilities in your Magentrix portal. Properly configured connections ensure Slack Message automation tasks can reliably deliver record notifications to your team's collaboration environment.

Jump to Slack Integration Checklist

<< Configuring Slack Settings | Managing Slack Workspace Connections >>