How to Create a Custom Slack App

Overview

By default, CRHQ satellites use a shared Slack app. This means your bot shows up as @CRHQ (or @Operator) in Slack.

If you want a custom name — like @Aria, @TeamBot, or @YourCompany — you can create your own Slack app and connect it through the CRHQ settings UI. No server access needed.

When to Use a Custom App

• You want a branded bot name that matches your company or product
• You don't want "CRHQ" visible to your team or clients
• You want to control the bot's icon, description, and @mention name
• You need to manage which workspaces can install the app

What You'll Need

• Access to api.slack.com/apps (Slack developer portal)
• A Slack workspace where you can create apps
• Admin access to your CRHQ satellite

At the end, you'll have three values to enter in CRHQ:

1. Client ID — identifies your app
2. Client Secret — authenticates OAuth
3. App Token — the xapp- token for Socket Mode

Step 1: Create the Slack App

Go to Slack API

Visit api.slack.com/apps and click Create New App. Choose From an app manifest for the fastest setup.

Select Your Workspace

Pick the workspace where you'll develop the app. You can distribute to other workspaces later.

Paste the Manifest

Copy and paste this manifest. Change "Your Bot Name" to whatever you want your bot to be called:

{
  "display_information": {
    "name": "Your Bot Name",
    "description": "AI assistant powered by CRHQ",
    "background_color": "#1a1a2e"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "Your Bot Name",
      "always_online": true
    }
  },
  "oauth_config": {
    "redirect_urls": [
      "https://crhq.ai/auth/slack/proxy-callback"
    ],
    "scopes": {
      "bot": [
        "app_mentions:read",
        "channels:read",
        "channels:history",
        "channels:join",
        "groups:read",
        "groups:history",
        "im:read",
        "im:history",
        "im:write",
        "mpim:read",
        "mpim:history",
        "chat:write",
        "chat:write.public",
        "chat:write.customize",
        "users:read",
        "users:read.email",
        "reactions:read",
        "reactions:write",
        "files:read",
        "files:write"
      ],
      "user": [
        "channels:read",
        "channels:history",
        "groups:read",
        "groups:history",
        "im:read",
        "im:history",
        "mpim:read",
        "mpim:history",
        "chat:write",
        "users:read",
        "search:read",
        "files:read"
      ]
    }
  },
  "settings": {
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.im"
      ]
    },
    "interactivity": {
      "is_enabled": false
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": true,
    "token_rotation_enabled": false
  }
}

Review and Create

Slack will show a summary of the app. Click Create to finish.

Step 2: Enable Socket Mode and Get Tokens

Generate the App Token

1. In your app's settings, go to Settings > Socket Mode in the left sidebar
2. Toggle Enable Socket Mode to ON
3. You'll be prompted to create an App-Level Token
4. Name it something like socket-mode and add the connections:write scope
5. Click Generate
6. Copy the xapp- token — this is your App Token

Find Client ID and Secret

Go to Settings > Basic Information and scroll to App Credentials:

• Client ID — looks like 1234567890.1234567890
• Client Secret — a long hex string

You now have all three values.

Step 3: Enter Credentials in CRHQ

Open the App Tab

Go to Settings > Connectors > Slack and select the App tab.

Enter Your Credentials

Fill in the three fields:

• Client ID — paste your Client ID
• Client Secret — paste your Client Secret
• App Token — paste the xapp- token

Click Save.

Verify

The App tab will show a green status banner: "Using Custom App" with your masked Client ID displayed.

From this point, all Slack connections (Bot and Personal) will use your custom app instead of the default CRHQ app.

Step 4: Connect the Bot

Now that your custom app is configured, install the bot:

1. Switch to the Bot tab
2. Click Install Bot to Workspace
3. Slack's authorization screen will show your app name — not CRHQ
4. Click Allow

Your bot is now live with your custom branding. Team members will @YourBotName to interact with it.

Enable Public Distribution

If you need to install the app in workspaces other than where it was created:

1. Go to Settings > Manage Distribution in your Slack app settings
2. Complete the checklist items
3. Click Activate Public Distribution

Switching Back to the Default App

To stop using your custom app and return to the default CRHQ app:

1. Go to Settings > Connectors > Slack > App tab
2. Click the Remove button on the status banner
3. Disconnect the bot in the Bot tab (it was connected with the old app)
4. Reconnect the bot — it will now use the default CRHQ app

Customizing Further

Change the Bot Icon

In your Slack app at api.slack.com:

1. Go to Basic Information > Display Information
2. Upload a custom icon (recommended: 512x512 PNG)

You can also set a per-message icon in CRHQ: Settings > Connectors > Slack > Bot tab > Icon URL.

Change the Bot Description

Update the short and long descriptions in Basic Information > Display Information. This text appears in Slack's app directory.

Troubleshooting

"invalid_team_for_non_distributed_app"

You're trying to install in a workspace other than where the app was created. Enable public distribution in Manage Distribution.

Bot doesn't respond after connecting

1. Verify Socket Mode is enabled in your app settings
2. Check Event Subscriptions include app_mention and message.im
3. Confirm the App Token in CRHQ is the xapp- token (not the bot token)

OAuth redirect fails

The manifest uses https://crhq.ai/auth/slack/proxy-callback as the redirect URL. This proxy routes the OAuth callback to your satellite. Make sure:

• Your satellite domain ends in .crhq.ai
• The redirect URL in your app settings exactly matches https://crhq.ai/auth/slack/proxy-callback

Custom app credentials not taking effect

After saving credentials in the App tab, you need to disconnect and reconnect the bot for the new app to take effect. The existing bot connection still uses the previous app's tokens.