Creating a Custom Slack App

A Custom Slack App allows organizations to connect their own privately owned Slack application to Magentrix instead of using the shared Magentrix Slack App. This approach provides full control over app branding, permission scopes, security policies, and application lifecycle management. Once configured, a Custom Slack App functions identically to the Magentrix Slack App for sending automated notifications, but the organization maintains complete ownership and governance of the application.

This page provides step-by-step instructions for creating a Custom Slack App in Slack's developer portal, registering it as a Connected App in Magentrix, and authorizing workspace connections using the custom app.

When to Use a Custom Slack App

Most organizations should use the Magentrix Slack App, which provides full functionality with no custom configuration required. Consider a Custom Slack App only when specific organizational requirements justify the additional setup and maintenance effort.

Reasons to Use a Custom Slack App

• Organizational Policy: Company security policies require ownership of all third-party application integrations
• Custom Branding: Notifications should display your organization's app name and icon rather than "Magentrix"
• Permission Control: You need to restrict or expand the default permission scopes for compliance reasons
• Audit Requirements: Your organization requires direct access to application logs and credentials for audit purposes
• Enterprise Governance: Centralized IT governance requires all Slack apps to be registered under organizational control

Reasons to Use the Magentrix Slack App

• Quick Setup: No custom app creation or configuration required
• Managed Updates: Magentrix maintains compatibility with Slack platform changes
• Reduced Maintenance: No ongoing app management responsibilities
• Standard Configuration: Pre-configured with all required permission scopes

Prerequisites

Before creating a Custom Slack App, ensure the following requirements are met:

• Slack Workspace Access: You must have access to create apps in a Slack workspace. This typically requires workspace administrator privileges or membership in the workspace's developer program.
• Slack API Access: You need access to the Slack API portal at https://api.slack.com/apps
• Magentrix Administrator Access: You must have Administrator System Role permissions in Magentrix to configure Connected Apps and Slack settings
• Slack Integration Enabled: Slack Integration must be enabled in Setup > Extend > Slack
• Portal URL: You need your Magentrix portal URL for configuring OAuth redirect settings

Overview of the Setup Process

Creating and connecting a Custom Slack App involves five main steps:

1. Create the Slack App: Create a new app in Slack's developer portal using a manifest file
2. Configure App Display: Customize the app's name, icon, and bot presence settings
3. Retrieve OAuth Credentials: Obtain the Client ID and Client Secret from Slack
4. Register in Magentrix: Add the Custom Slack App as a Connected App in Magentrix
5. Authorize the Workspace: Complete the OAuth flow to connect your Slack workspace

Each step is detailed in the sections below.

Step 1: Create the Slack App from a Manifest

Slack's manifest system allows you to create an app with pre-configured settings, including all required permission scopes for Magentrix integration.

Accessing the Slack API Portal

1. Open your web browser and navigate to https://api.slack.com/apps
2. Sign in with your Slack account if prompted
3. Click the Create New App button

Selecting the Creation Method

In the "Create an app" dialog, two options appear:

• From a manifest: Create an app using a JSON or YAML configuration file (recommended)
• From scratch: Manually configure all app settings individually

Select From a manifest to use the pre-configured settings optimized for Magentrix integration.

Selecting a Workspace

After selecting "From a manifest," choose the Slack workspace where the app will be developed:

1. Use the dropdown to select your target workspace
2. Click Next to proceed

Entering the Manifest

The manifest editor accepts JSON or YAML format. Copy the following JSON manifest and paste it into the editor, replacing the TODO placeholder values with your specific information:

{
  "display_information": {
    "name": "TODO: REPLACE_WITH_APP_NAME",
    "description": "TODO: REPLACE_WITH_APP_DESCRIPTION",
    "background_color": "TODO: REPLACE_WITH_HEX_COLOR"
  },
  "features": {
    "bot_user": {
      "display_name": "TODO: REPLACE_WITH_BOT_NAME",
      "always_online": true
    }
  },
  "oauth_config": {
    "redirect_urls": [
      "TODO: https://[YOUR PORTAL URL]/sys/slackconnection/authorize"
    ],
    "scopes": {
      "user": [
        "channels:read",
        "channels:write",
        "chat:write",
        "groups:read",
        "im:read",
        "mpim:read",
        "users:read",
        "users:read.email"
      ],
      "bot": [
        "users:read",
        "users:write"
      ]
    }
  },
  "settings": {
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false
  }
}

Manifest Field Reference

display_information.name: The name of your Slack app as it appears to users. Choose a name that identifies the app's purpose, such as "Acme Portal Notifications" or "Partner Portal Integration." The name must include relevant identification so users recognize the source of automated messages.

display_information.description: A brief description of the app's purpose. This appears in Slack's app directory and installation screens. Example: "Connects the Acme partner portal to deliver automated record notifications."

display_information.background_color: A hex color code for the app's branding. Use your organization's brand color, such as "#4d207f" for purple or "#2eb886" for green. Include the hash symbol.

features.bot_user.display_name: The name displayed when the bot posts messages to channels. Choose a recognizable name such as "Acme Portal Bot" or "Partner Notifications." This name appears as the sender of automated messages.

oauth_config.redirect_urls: The callback URL where Slack redirects after authorization. Replace [YOUR PORTAL URL] with your actual Magentrix portal domain. For example: https://partners.acmecorp.com/sys/slackconnection/authorize

Creating the App

After entering the manifest with your customized values:

1. Click Next to proceed to the review screen
2. Review the parsed configuration to verify your settings
3. Click Create to create the app

Slack creates the app and redirects you to the app's configuration page.

Step 2: Configure App Display and Presence

After creating the app, configure additional display settings that affect how the app appears to Slack users.

Uploading an App Icon

The manifest does not include the app icon, which must be uploaded manually:

1. In your app's configuration page, navigate to Settings > Basic Information
2. Scroll to the Display Information section
3. Click on the App Icon & Preview area
4. Upload your app icon image

Icon Requirements:

• Recommended size: 512 x 512 pixels
• Supported formats: PNG, JPG, GIF
• The icon appears next to messages posted by your app

Reviewing Display Settings

The following settings were configured via the manifest but can be reviewed or modified:

• App Name: The primary name of your application
• Short Description: Brief explanation of the app's purpose
• Background Color: Branding color used in various Slack interfaces

Configuring Bot Presence

To review or modify bot settings:

1. Navigate to Features > App Home
2. Locate the "Your App's Presence in Slack" section
3. Click Edit to modify bot settings if needed

Bot Settings:

• Display Name (Bot Name): The name shown when the bot posts messages. Names must be shorter than 80 characters and cannot use punctuation other than apostrophes and periods.
• Default Username: The username used to reference the bot in Slack. Usernames must be all lowercase, 21 characters or fewer, and can only contain letters, numbers, periods, hyphens, and underscores.
• Always Show My Bot as Online: When enabled, the bot appears with a green online indicator at all times.

Step 3: Retrieve OAuth Credentials

Magentrix requires the app's Client ID and Client Secret to establish OAuth connections. These credentials authenticate your Custom Slack App during the authorization flow.

Locating App Credentials

1. In your app's configuration page, navigate to Settings > Basic Information
2. Scroll to the App Credentials section
3. Locate the following values:
   • App ID: A unique identifier for your app (for reference only)
   • Client ID: The public identifier used during OAuth (you will need this)
   • Client Secret: The private key used during OAuth (you will need this)

Copying Credentials

Copy the Client ID and Client Secret values exactly as displayed. You will enter these values in Magentrix in the next step.

Regenerating the Client Secret

If you need to regenerate the Client Secret (for example, if it was accidentally exposed):

1. Click the Regenerate button next to the Client Secret
2. Confirm the regeneration when prompted
3. Update the Client Secret in Magentrix Connected Apps configuration
4. Note that existing connections using the old secret will stop working until updated

Step 4: Register the Custom Slack App in Magentrix

Before authorizing workspace connections, register your Custom Slack App as a Connected App in Magentrix. This registration stores the OAuth credentials and makes the app available for Slack workspace authorization.

Accessing Connected Apps

1. Navigate to the Setup Home page in Magentrix
2. Click Extend in the left navigation menu
3. Click Connected Apps

Creating a New Connected App

1. Click New to create a new Connected App
2. Select API Provider as the integration type
3. Click Next
4. Select OAuth as the authentication type
5. Click Next

Configuring the Connected App

Enter the following information in the Authorization Detail section:

Name (Required): Enter a descriptive name for the Connected App. The name must include "Slack" to identify it as a Slack integration. Examples: "External Slack App," "Acme Custom Slack," or "Partner Portal Slack Integration."

Service URL (Required): Enter the OAuth callback URL for Slack connections. Use the following format, replacing [YOUR PORTAL URL] with your actual portal domain:

https://[YOUR PORTAL URL]/sys/slackconnection/authorize

This URL must match the redirect URL configured in your Slack app manifest.

Consumer Key (Required): Paste the Client ID copied from your Slack app's Basic Information page.

Consumer Secret: Paste the Client Secret copied from your Slack app's Basic Information page.

Refresh Token: Leave this field empty. Slack manages token refresh through its OAuth implementation.

Saving the Connected App

After entering all required information:

1. Review the configuration for accuracy
2. Verify the Service URL matches your Slack app's redirect URL exactly
3. Click Save to create the Connected App

The Connected App is now registered and available for Slack workspace authorization.

Step 5: Authorize Your Slack Workspace

With the Custom Slack App registered as a Connected App, you can now authorize workspace connections using your custom app.

Initiating Authorization

1. Navigate to Setup > Extend > Slack
2. Verify Slack Integration is enabled (status shows "Connected")
3. Click Connect Workspace
4. In the authorization dialog, select Custom Slack App
5. A dropdown appears listing available Custom Slack Apps
6. Select your Custom Slack App from the dropdown
7. Click Authorize

Completing the OAuth Flow

After clicking Authorize, you are redirected to Slack:

1. Select the workspace you want to connect (if prompted)
2. Review the permissions requested by your Custom Slack App
3. Click Allow to grant the permissions
4. Slack redirects you back to Magentrix

Verifying the Connection

Upon successful authorization:

• The workspace appears in the Connected Workspaces table
• Both bot and user token connections are created automatically
• The App column displays your Custom Slack App identifier instead of "Magentrix"
• The connections are immediately available for Slack Message automation tasks

Using Custom Slack App Connections

Once connected, Custom Slack App connections function identically to Magentrix Slack App connections.

In Automation Tasks

When configuring Slack Message tasks:

• Custom Slack App connections appear in the Slack Connection dropdown
• Select the appropriate connection based on token type (bot or user) and workspace
• All Record Card features, field selections, and message formatting work normally
• Multi-language translation functions according to standard behavior

Message Appearance

Messages sent via Custom Slack App connections display:

• Your custom app name as the sender
• Your custom app icon next to messages
• Your configured bot display name for channel messages

This branding differentiation is the primary visible difference from using the Magentrix Slack App.

Managing Custom Slack App Connections

Custom Slack App connections follow the same management procedures as Magentrix Slack App connections:

• Viewing: Connections appear in the Connected Workspaces table with the Custom App identifier
• Revoking: Use the Actions menu to revoke connections that are no longer needed
• Deleting: Delete revoked connections to remove them from the table
• Reauthorizing: Click Connect Workspace and select your Custom Slack App to create new connections

For detailed connection management procedures, see Managing Slack Workspace Connections.

Maintaining Your Custom Slack App

Unlike the managed Magentrix Slack App, Custom Slack Apps require ongoing maintenance by your organization.

Monitoring App Status

Periodically check your app's status in the Slack API portal:

• Verify the app remains installed in target workspaces
• Review any warning messages or required actions from Slack
• Check for deprecation notices affecting permission scopes

Updating Permission Scopes

If Slack introduces new features or deprecates existing scopes:

1. Review Slack's developer announcements for changes
2. Update your app's manifest or OAuth configuration as needed
3. Reauthorize workspace connections if scope changes require new consent

Credential Rotation

Some organizations require periodic credential rotation:

1. Generate a new Client Secret in Slack's app configuration
2. Update the Consumer Secret in Magentrix Connected Apps
3. Test authorization to verify the new credentials work
4. Note that existing connections continue working; only new authorizations use updated credentials

App Ownership Transfer

If the app owner leaves the organization:

• Transfer app ownership within Slack before the owner loses workspace access
• Update Magentrix Connected Apps if credentials change during transfer
• Document new ownership for future maintenance

Troubleshooting

Custom Slack App Not Appearing in Dropdown

If your Custom Slack App does not appear in the authorization dropdown:

• Verify the Connected App was saved successfully in Magentrix
• Confirm the Connected App name includes "Slack"
• Check that the Service URL is correctly formatted
• Refresh the Slack Settings page and try again

Authorization Fails with Redirect Error

If authorization fails with a redirect or callback error:

• Verify the Service URL in Magentrix Connected Apps matches the redirect URL in your Slack app manifest exactly
• Check for typos in the portal URL
• Ensure the URL uses HTTPS
• Confirm the redirect URL is saved in both Slack and Magentrix

Authorization Fails with Invalid Client Error

If authorization fails with an invalid client or credentials error:

• Verify the Consumer Key (Client ID) is copied correctly without extra spaces
• Verify the Consumer Secret is copied correctly
• Check that the Client Secret has not been regenerated since configuration
• Re-copy credentials from Slack and update the Connected App

Bot Not Posting to Channels

If the Custom Slack App bot cannot post to channels:

• Verify the app's manifest includes the required bot scopes
• Confirm the bot has been invited to private channels
• Check that the workspace connection is active
• Review the app's installation status in Slack workspace settings

Permission Scope Errors

If Slack reports missing or invalid scopes:

• Review the manifest to ensure all required scopes are included
• Compare your manifest against the reference manifest in this documentation
• Update the app configuration in Slack if scopes are missing
• Reauthorize workspace connections after scope changes

Permission Scopes in the Manifest

The manifest includes specific permission scopes required for Magentrix integration. Understanding these scopes helps you make informed decisions about app permissions.

User Scopes

• channels:read: View basic information about public channels
• channels:write: Manage public channel membership and settings
• chat:write: Send messages on behalf of the user
• groups:read: View basic information about private channels
• im:read: View basic information about direct messages
• mpim:read: View basic information about group direct messages
• users:read: View users and their basic information
• users:read.email: View email addresses of users

Bot Scopes

• users:read: View users and their basic information
• users:write: Modify user profile settings

Jump to Slack Integration Checklist

<< Managing Slack Workspace Connections | Slack Permission Scopes Reference >>