Configuring a custom Slack application

This guide provides IT and HR administrators instructions on creating and configuring a custom Slack application for integration with their organization's workspace.

Prerequisites

Before you begin, ensure that you have the following:

• Slack Workspace: A Slack workspace where you will install the application.
• Admin Access: Administrator rights for your Slack workspace.
• Account Access: Access credentials for the account the application will connect to. Ensure you have the necessary URL and user account credentials.
• AI assistant setup: The AI assistant bot should be enabled on the application. Select the Use this bot to interact with external bots and generate responses option to enable it.

Step 1: Create a Slack Application

1. Sign in to Slack and go to the Slack API.
2. Select Create New App, and from the methods, choose From Scratch to build your application from the ground up.
3. Enter your application's Name, for example, AskHR.
4. Select the Slack workspace where you want to install the application.
5. Select Create App.

Step 2: Configure branding

1. On the left-hand navigation menu, under Settings, select Basic Information and scroll down to the Display Information section.
2. Enter your brand details:
   • App name: Name of your bot application, for example, AskHR.
   • Short description: Describe your bot in one sentence, for example, “Answers your HR queries.”
   • App icon: Add an image representing your bot on the conversation body.
   • Background color: Background color of your bot icon while on the conversation body.
   • Long description: A description of your bot will be shown on your App Detail page. For example, “The AskHR bot can answer your questions on time-off, pay, and policies.”
3. Once done, select Save Changes.

Step 3: Configure OAuth & Permissions

1. On the left-hand navigation bar under Features, select OAuth & Permissions.
2. Scroll down to Redirect URLs and select Add New Redirect URL.
3. Copy this URL and paste it into the box:
   • https://applaud-custom-slack-api.applaudhcm.com/slack/oauth_redirect?clientId={SlackClientId}&clientSecret={SlackClientSecret}&signingSecret={SlackSigningSecret}
4. Replace the information in bold curly brackets {}, removing the brackets, with the information on the Basic Information page under App Credentials:
   • {SlackClientId} - Client ID: Copy the ID and paste it into the correct section of the URL.
   • {SlackClientSecret} - Select Show, copy the code, and paste it into the correct section of the URL.

   • {SlackSigningSecret} - Singing Secret: Select Show, copy the code, and paste it into the correct section of the URL.

     Copy the example URL into a notepad, and then copy your app credential codes into the URL. Then, you can copy the URL.

5. Select Add and then Save URLs.
6. Scroll down to Scopes, and under Bot Token scopes, select Add an OAuth Scope.
7. Scroll down and select all the scopes to which your app needs access to:
   • channels:history
   • channels:read
   • chat:write
   • im:history
   • users:read
   • users:read:email

Step 4: Configure Event Subscriptions

1. From the left-hand navigation menu, under Features, select Event Subscriptions.
2. On the Enable Events section, select the toggle to On.
3. The new section appears, and you can enter this URL in the Request URL box, which is the URL that Slack should use to notify when an event occurs:
   • https://applaud-custom-slack-api.applaudhcm.com/slack/events
4. Select to expand the Subscribe to bot events section and select Add Bot User Event.
5. Search for and select these user events:
   • App_home_opened
   • message.im
   • App_uninstalled
6. Select Save Changes

Step 5: Configure Interactivity & Shortcuts

1. From the left-hand navigation menu, under Features, select Interactivity & Shortcuts.
2. In the Interactivity section, select the toggle to On.
3. In the new section that appears, enter this URL, which Slack should use to send interactive payloads in the Request URL box:
   • https://applaud-custom-slack-api.applaudhcm.com/slack/interactions
4. Select Save Changes.

Step 6: Configure the App Home tab

1. From the left-hand navigation menu, under Features, select App Home and scroll down to the Show Tabs section.
2. Next to the Home Tab section, select the toggle to On.
3. Ensure that the Messages Tab section toggle is switched to On.
4. Select the Allow users to send Slash commands and messages from the messages tab option.

Step 7: Distribution of Application

1. From the left-hand navigation menu under Settings, select Manage Distribution.
2. Scroll down to the Share your app with other workspaces section and select to expand the Remove hard-coded information section.
3. Select the I've reviewed and removed any hard-coded information option.
4. Select Activate public distribution to generate a public installation link for the application.
   • The Applaud team will provide a shareable URL, for example, https://company-com.applaudcloud.com/slack/install.

Step 8: Install the Application

1. Like the previous step, copy this installation URL and paste it into a new browser tab, replacing the app credentials.
   • https://applaud-custom-slack-api.applaudhcm.com/slack/install?clientId={SlackClientId}&clientSecret={SlackClientSecret}&signingSecret={SlackSigningSecret}
2. Replace the information in bold curly brackets {}, removing the brackets, with the information on the Basic Information page under App Credentials:
   • {SlackClientId} - Client ID: Copy the ID and paste it into the correct section of the URL.
   • {SlackClientSecret} - Select Show, copy the code, and paste it into the correct section of the URL.
   • {SlackSigningSecret} - Singing Secret: Select Show, copy the code, and paste it into the correct section of the URL.
     Tip: Copy the example URL into a notepad, and then copy your app credential codes into the URL. Then, you can copy the URL.
3. This takes you to review the app's permissions, which you need to grant access. You might need to select the workspace where you want to install the app. Review the sections and then select Allow.

4. This opens your Slack workspace. If not, select the this link shown on the page.

   If you receive an “Opps, something went wrong!” error, try copying the link into a document and clicking the link. If you’re still having trouble, please raise a ticket with Applaud support.

5. The installed app appears under the Apps section in your Slack workspace.

Step 9: Connect the instance to the application

1. After installation, you should see the Home tab of the installed App. If not, on the workspace navigation menu, under Apps, select the app you just installed and select the Home tab.
2. Select Connect to Application and enter:
   • Application URL: For example, https://company-com.applaudcloud.com
   • API Key: Enter an API key generated by your Applaud tenant. See our knowledge base article, Restrict access to your Applaud platform using API and domain API keys.
3. Select Submit and Close.

Step 10: Connect the user account

• Remaining on the App’s Home tab, select Connect your account. If you are already signed in with your user credentials, Applaud loads, and you should be connected. The button on the Home page won’t change, so navigate away by clicking the Messages tab and then click back to the Home tab to see that the button has changed. 

Step 11: Test the the Application

• In the Messages tab, ensure that the application responds promptly without any errors to confirm that the application setup is completed and connected to the user account.

Step 12: Provide Access to Team Members

1. Inform relevant team members that the app has been installed. Share usage instructions.
2. The Custom Slack application is already connected to the application URL. However, each team member needs to connect to their respective user account with their Applaud credentials.

Additional instructions (If Needed)

Disconnect user account

• On the Slack sidebar, under the Apps section, find the Custom app, select the Home tab, and select Disconnect your account. This only disconnects the respective user but not all user accounts.

Connect to a different Application

• On the Slack sidebar, under the Apps section, find the Custom app, select Home, and select Disconnect Application.

Uninstallation

1. On the Slack sidebar, under the Apps section, find the Custom app, select About, and select Configuration.
2. Scroll down to the Remove App section and select Remove app.
3. Confirm the removal, and Slack will uninstall the app from your workspace.
4. If your team used the app, notify them of the uninstallation.

Organization-wide installation (Only for Slack Enterprise Grid subscription)

1. Navigate to the Org Settings in the Admin dashboard.
2. Select Apps and go to the Manage Apps section.
3. Use Org-Level App Management to install the app across all workspaces or select specific workspaces.
4. Set up any permissions or usage guidelines based on organizational policies.

On the Enterprise Grid subscription, the Custom Slack application can be installed at the organization level and added to any necessary workspaces.