Slack

This guide walks an operator through enabling the @Faheem Code Slack integration on a self-hosted Faheem Code Enterprise (FCE) installation — both the Replicated VM-based install (see the Quick Start) and standalone Helm (Kubernetes Installation).

Once enabled, end users can mention @faheem-code in any Slack channel or thread to start and follow up on conversations from Slack, exactly like they can on Faheem Code Cloud.

Info

If you are looking for the Faheem Code Cloud Slack integration (no self-hosting involved), see Slack Integration instead — that page uses the Faheem Code-managed Slack App and skips the steps below.

Overview

Unlike Faheem Code Cloud, a self-hosted install needs its own Slack App so that Slack webhooks land on your domain rather than app.faheemcode.ai. The configuration involves four phases:

1. Create a Slack App for your install (one-time, by a Slack workspace admin).
2. Configure FCE with the Slack App's credentials (one-time, by the FCE operator).
3. Install the Slack App into your workspace (one-time, by a Slack workspace admin).
4. Link each user's account in Faheem Code ↔ Slack (per-user, self-service).

Verify prerequisites

Create the Slack app

Configure Faheem Code Enterprise

Install the Slack app into your workspace

Have users link their Slack accounts

Prerequisites

Before you start, confirm:

• FCE is already installed and reachable. You can sign in to Faheem Code Enterprise at https://app.<your-base-domain> (e.g. https://app.mycompany.com).
• Inbound HTTPS from the public internet terminates at your FCE ingress on https://app.<your-base-domain>/slack/*. Slack delivers webhooks from public IPs, so fully air-gapped installs are not supported by this integration today (Slack Socket Mode is disabled).
• Valid TLS certificate on app.<your-base-domain>. Slack will reject webhook URLs with untrusted certificates.
• A Slack workspace admin/owner is available to install the app and generate a short-lived Slack App Configuration Token.
• A workstation with uv installed and outbound network access to slack.com (only needed for the optional helper script in Step 2).

Note

Replace <your-base-domain> throughout this guide with the same domain you used during installation (the value behind KOTS_HOSTNAME or the ingress.host Helm value).

Step 1: create the Slack app

You can mint the Slack App either with the helper script in Faheem Code-Cloud (recommended) or by pasting the manifest into Slack's UI. Either path produces the same app.

Option A: helper script (recommended)

1. Generate a Slack App Configuration Token:

   1. Sign in to https://api.slack.com/apps as a workspace admin/owner.
   2. In Your App Configuration Tokens, click Generate Token.
   3. Select your workspace and click Generate.
   4. Copy the access token (starts with xoxe.xoxp-). Treat it like a password — it is short-lived but is sufficient to create apps in your workspace.

2. Clone Faheem Code-Cloud and run the script:

   git clone https://github.com/alsairy/faheem-code-cloud.git
   cd Faheem Code-Cloud
   
   export SLACK_CONFIG_TOKEN=xoxe.xoxp-...
   ./scripts/create_slack_app/create_slack_app.py \
     --base-domain <your-base-domain>

   Tip

   Pass --dry-run to print what would be created without calling Slack. Pass --app-name "Faheem Code (Staging)" to differentiate multiple installs in the same workspace.

3. The script prints three values. Save them now — Slack will let you retrieve them again from the app's "Basic Information" page, but the script does not store them anywhere:

   Slack Client ID:        ...
   Slack Client Secret:    ...
   Slack Signing Secret:   ...

The script registers the following URLs on the new Slack App (all rooted at https://app.<your-base-domain>):

Slack setting	URL
OAuth Redirect URL	/slack/install-callback
Event Subscriptions Request URL	/slack/on-event
Interactivity Request URL	/slack/on-form-interaction
Options Load URL	/slack/on-options-load

…and requests these bot scopes (no user scopes):

app_mentions:read, chat:write, users:read, channels:history, groups:history, mpim:history, im:history.

Socket Mode, Org Deploy, and Token Rotation are intentionally disabled to match what the FCE backend expects today.

Option B: paste the manifest into Slack's UI

If you can't run the script (e.g. your workstation has no outbound Slack access), open https://api.slack.com/apps → Create New App → From an app manifest, choose your workspace, and paste the YAML below. Replace <your-base-domain> first.

display_information:
  name: Faheem Code
features:
  bot_user:
    display_name: Faheem Code
    always_online: false
oauth_config:
  redirect_urls:
    - https://app.<your-base-domain>/slack/install-callback
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - users:read
      - channels:history
      - groups:history
      - mpim:history
      - im:history
settings:
  event_subscriptions:
    request_url: https://app.<your-base-domain>/slack/on-event
    bot_events:
      - app_mention
  interactivity:
    is_enabled: true
    request_url: https://app.<your-base-domain>/slack/on-form-interaction
    message_menu_options_url: https://app.<your-base-domain>/slack/on-options-load
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

After creating the app, copy Client ID, Client Secret, and Signing Secret from the app's Basic Information page.

Warning

When Slack verifies your Event Subscriptions Request URL, your FCE install must already be reachable at https://app.<your-base-domain>/slack/on-event. If you create the Slack App before FCE is running, Slack will mark the URL as unverified and you'll need to click "Retry" after finishing Step 3.

Step 2: configure Faheem Code Enterprise

Pick the path that matches how FCE is deployed.

1. Open the Replicated admin console at https://<admin-console-host>:30000 and sign in.

2. Navigate to Config → Enable Slack (or search "Slack" in the config side panel).

3. Set the following values:

   Field	Value
   Enable Slack Integration	✅ on
   Slack Client ID	from Step 1
   Slack Client Secret	from Step 1
   Slack Signing Secret	from Step 1

4. Click Save config and then Deploy the new version.

5. Wait for the deployment to reach Ready — Replicated will roll the integrations pod with the new secrets and environment variables.

Behind the scenes this:

• Creates a Kubernetes Secret/slack-auth holding the client and signing secrets.
• Sets slack.enabled=true, slack.clientId=<client-id>, and ENABLE_V1_SLACK_RESOLVER=true on the integrations service.
• Exposes /slack/* on the integrations ingress on port 3000.

Set the Slack values directly on the faheemcode and faheem-code-secrets charts.

In your values.yaml for the faheemcode chart:

slack:
  enabled: true
  clientId: "<your-slack-client-id>"

env:
  ENABLE_V1_SLACK_RESOLVER: "true"

In your values.yaml for the faheem-code-secrets chart:

config:
  slack_client_id: "<your-slack-client-id>"
  slack_client_secret: "<your-slack-client-secret>"
  slack_signing_secret: "<your-slack-signing-secret>"

Then redeploy:

helm upgrade --install faheem-code-secrets ./charts/faheem-code-secrets \
  -f values-secrets.yaml -n faheemcode

helm upgrade --install faheemcode ./charts/faheemcode \
  -f values.yaml -n faheemcode

Tip

If you manage the secret yourself, you can skip the faheem-code-secrets chart and create a Secret/slack-auth directly with keys client-id, client-secret, and signing-secret. The deployment reads client-secret and signing-secret from that secret, and reads client-id from the slack.clientId Helm value.

Confirm the integrations pod restarted with the new environment:

kubectl -n faheemcode set env deployment/faheem-code-integrations --list \
  | grep '^SLACK_'

You should see SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_SIGNING_SECRET, and SLACK_WEBHOOKS_ENABLED=true.

Step 3: install the Slack app into your workspace

With FCE configured, point your browser at:

https://app.<your-base-domain>/slack/install

This redirects through Slack's OAuth v2 flow and then through Faheem Code' Keycloak login. A workspace admin/owner should complete this step first — they will be granting the Faheem Code bot permission to read mentions and post messages in your workspace.

After approval you'll see Faheem Code Authentication Successful. Slack will also mark the Event Subscriptions Request URL as verified.

Note

If Slack reports missing_scope after install, the most likely cause is that the manifest was edited to drop one of the *:history scopes. Re-run Step 1 (or fix the scopes in the Slack App OAuth & Permissions page) and then re-install via the same URL.

Step 4: have users link their Slack accounts

@Faheem Code will only respond to users whose Slack identity has been linked to an Faheem Code user. Every user — including the admin who installed the app — needs to do this once. They have two options:

• From Faheem Code: sign in at https://app.<your-base-domain>, open Settings → Integrations, and click Install Faheem Code Slack App.
• From Slack: the first time they mention @faheem-code, the bot will reply with a one-time login link that completes the same flow.

Either path produces the same record in the slack_users table, mapping the Slack user ID to a Keycloak (Faheem Code) user. Once linked, any conversation started from Slack runs as that Faheem Code user — using their LLM keys, provider tokens, and organization.

Using the integration

Day-to-day usage is identical to Faheem Code Cloud — see Working With the Slack App for screenshots and the "mention @faheem-code in a thread" follow-up flow.

What context the agent receives

When @faheem-code is mentioned, the bot does two things before starting (or continuing) an Faheem Code conversation:

1. It strips the <@BOT_ID> mention out of the triggering message and uses the remainder as the agent's initial user prompt.
2. It fetches surrounding Slack history via the Slack Web API and appends those messages to the agent's system prompt as additional context.

Channel vs. thread — different sources, never mixed. The bot branches on whether the triggering Slack event has a thread_ts:

Where @faheem-code is mentioned	What the bot fetches	API method used
Inside a thread	Only that thread's replies (up to 21 — the trigger plus 20 prior)	conversations.replies
At the top level of a channel	The channel's recent message stream (up to 21 — the trigger plus 20 prior)	conversations.history

A top-level mention will not surface any thread the bot is not part of, and an in-thread mention will not surface broader channel discussion outside the thread. Where you mention the bot directly controls which Slack messages it can see.

New conversation vs. follow-up.

• A top-level mention always starts a brand-new Faheem Code conversation.
• An in-thread mention where the thread already has an Faheem Code conversation tied to it (matched on (channel_id, thread_ts)) appends a message to that conversation instead. See "Thread ownership" below for who is allowed to do this.
• On a follow-up, only the single triggering reply is forwarded — the agent's running memory is expected to carry the rest. Follow-ups are noticeably leaner than the initial mention.

What is dropped. Only the text field of each surrounding message is forwarded. The integration does not pass message authors / display names, timestamps, file or image attachments, reactions, edits, permalinks, or Slack canvases. There is also no summarization or condensation today — once the 21-message window is full, older messages are simply not included.

Tip

Practical guidance for end users:

• For broad channel context, mention @faheem-code at the channel's top level.
• For focused work on a specific discussion, mention it inside the relevant thread.
• Do not expect attached files, images, or canvases to be visible to the agent — only message text is forwarded. If a screenshot or document is important, describe its contents in the message you send.

Self-hosted specifics

• Repo selection. When a user starts a new conversation without an obvious repo in the message, Faheem Code posts an ephemeral repo picker. The picker calls back to /slack/on-options-load on your domain and lists repositories the user can access through their linked Git provider.
• Thread ownership. Only the user who started a thread conversation can @faheem-code in follow-up replies — other workspace members mentioning the bot in the same thread will get an "not authorized to send messages to this conversation" response. This is intentional until per-org access lands.
• Conversation links. The bot's "I'm on it!" reply links to https://app.<your-base-domain>/conversations/<id>. Users must be signed in to FCE to view it.

Limitations

• No Slack Socket Mode. Your FCE install must be reachable from the public internet on https://app.<your-base-domain>/slack/*. Air-gapped installs cannot use this integration today.
• No token rotation. The bot uses a long-lived xoxb- token issued at install time. If you regenerate the Slack App's credentials, re-run Steps 2 and 3.
• Single Slack App per install. The FCE backend assumes one Slack App per deployment. To support multiple workspaces, install the same Slack App into each workspace via Step 3 — do not create separate apps.
• Slack Connect / externally shared channels are not supported for posting from the bot.

Troubleshooting

Slack reports 'your URL didn't respond with the value of the challenge parameter'

Slack could not reach https://app.<your-base-domain>/slack/on-event from the public internet, or the TLS certificate isn't trusted. Verify from a machine outside your network:

curl -i https://app.<your-base-domain>/slack/on-event

You should get an HTTP response (a 403 is expected and fine — it means the route exists). If the request times out or the certificate is rejected, fix DNS / firewall / TLS before clicking Retry in Slack's Event Subscriptions panel.

`@faheem-code` mentions are ignored

1. Check that SLACK_WEBHOOKS_ENABLED=true is set on the integrations pod. If it is missing, your FCE deployment did not re-roll after Step 2 — redeploy.
2. Tail the integrations pod logs and mention @faheem-code again. You should see a slack_on_event log line. If you don't, Slack isn't reaching your install.
3. If you see slack_on_event followed by slack_is_duplicate, Slack is retrying an old delivery — wait 60 seconds and try a fresh message.

Users get a login link every time they mention @faheem-code

The user's Slack ID is not linked to an Faheem Code user. Have them complete Step 4 once. If they have already linked but still see the login prompt, check that their Keycloak user is active and that the slack_users row exists:

kubectl -n faheemcode exec -it deployment/faheem-code-postgres -- \
  psql -U postgres -d faheemcode -c \
  "SELECT slack_user_id, keycloak_user_id FROM slack_users;"

`missing_scope` error in pod logs

The Slack App is missing one of the bot scopes listed in Step 1. Open the app's OAuth & Permissions page in Slack, add the missing scope, then re-install via https://app.<your-base-domain>/slack/install. Users do not need to re-link.

Re-installing after rotating Slack credentials

1. Regenerate the Slack App's Client Secret / Signing Secret on Slack's app config page.
2. Update them in Step 2 (Replicated admin console or the Helm secret).
3. Redeploy FCE so the integrations pod picks up the new values.
4. Existing user account links remain valid — no need to re-run Step 4.

Reference

• Helper script: scripts/create_slack_app/ in Faheem Code-Cloud
• Replicated config group: replicated/config.yaml (slack_configuration)
• Helm chart values: charts/faheemcode/values.yaml (slack.*)
• Cloud-hosted Slack flow (for end-user UX reference): Slack Integration