> ## Documentation Index
> Fetch the complete documentation index at: https://sofiedocs.usetransfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up the Slack integration

> Create the Sofie Slack app, connect a Slack workspace, and verify user linking, permissions, and message delivery.

The Slack integration lets users message or mention Sofie from Slack. It also supports live research using each user's Slack access and approved messages sent as that user.

Setup has two parts: you connect the organization app, then each user [links and authorizes their own Slack account](/integrations/slack).

## Before you start

You need:

* Access to Sofie **Organization Settings** > **Integrations**, with permission to edit integrations.
* Permission to create and install a Slack app in the intended Slack workspace.
* The public HTTPS domain your users use to open Sofie.
* Slack and Teams messaging integrations enabled for your Sofie deployment.

If the Slack card is missing, check availability with your Sofie administrator or TransferAI contact. If **Messaging destinations** shows **Setup incomplete**, review its remaining setup items.

## Create and connect the Slack app

<Steps>
  <Step title="Download Sofie's manifest">
    In **Organization Settings** > **Integrations**, find **Slack** and click **Set up Slack app**. Click **Download Slack manifest**.

    Use the manifest from the Sofie environment you are connecting. It includes the callback URLs, event subscriptions, interactivity settings, and bot and user permissions.
  </Step>

  <Step title="Create the Slack app">
    Click **Open Slack app settings**. Create an app **From a manifest**, choose the intended Slack workspace, and paste the downloaded JSON. Review the configuration and create the app.

    See [Slack's manifest setup guide](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/) for the current creation flow.
  </Step>

  <Step title="Save the app credentials in Sofie">
    In the Slack app's **Basic Information**, find its app credentials. Enter the matching **Client ID**, **Client secret**, and **Signing secret** in Sofie's Slack setup card.

    Click **Save Changes**. Leave an already saved secret field blank to keep its existing value.
  </Step>

  <Step title="Verify URLs and event delivery">
    In Slack app settings, check **OAuth & Permissions**, **Event Subscriptions**, and **Interactivity & Shortcuts** against the URLs below. Confirm that event subscriptions and interactivity are enabled and that Slack verifies the event request URL.
  </Step>

  <Step title="Connect the workspace">
    Return to Sofie and click **Connect Slack workspace**. Choose the correct Slack workspace, review the permissions, and complete authorization.

    Check that the workspace appears under **Workspace and tenant connections**.
  </Step>

  <Step title="Test with a user">
    Click **Test connection** for the installation. Have a test user message Sofie privately, complete the account link and Slack authorization, then send a small request.

    Add Sofie to a test channel. Mention **@Sofie**, then reply in the same thread without a second mention. Test an attachment and a message preview before broader rollout.
  </Step>
</Steps>

<Note>
  Store credential values in the organization settings fields. Do not paste them into chat, shared Workspaces, or training screenshots.
</Note>

## URLs to check

Replace `<your-sofie-domain>` with your public Sofie domain. The manifest includes both OAuth redirects.

| Slack setting | URL |
| - | - |
| Organization OAuth redirect | `https://<your-sofie-domain>/api/external-chat/slack/callback` |
| User OAuth redirect | `https://<your-sofie-domain>/api/external-chat/slack/user/callback` |
| Event request URL | `https://<your-sofie-domain>/api/external-chat/slack/events` |
| Interactivity request URL | `https://<your-sofie-domain>/api/external-chat/slack/events` |

The user redirect supports personal Slack authorization after identity linking. Interactivity delivers the **Approve & send** and **Cancel** button actions.

## Understand the permissions

The organization installation authorizes the Sofie bot to receive mentions and conversation messages, respond, read user information, and retrieve attached files.

Each user separately authorizes research across the Slack conversations and files they can access, plus sending messages as their Slack identity after review. Installing the bot does not authorize personal research for every user.

Research requested in a shared Slack channel is restricted to that channel. Users should message Sofie privately for research across other conversations.

## Update an existing installation

Download a fresh manifest and compare it with the existing Slack app's **App Manifest**. Preserve the matching Sofie domain and apply the current configuration. Slack supports updates through its [manifest editor](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/).

Check these settings in older apps:

* Bot subscriptions include `message.channels` and `message.groups` for follow-ups, plus `app_uninstalled` and `tokens_revoked` for installation changes.
* The bot has `files:read` to retrieve attached files.
* Both OAuth redirect URLs are present.
* User permissions match the current manifest, including `files:read`.
* Interactivity uses the Sofie event URL.

Reauthorize the workspace when bot permissions change. If the connection shows **Reauthorization required**, use **Reauthorize Slack**. Users whose cards show **Reconnect required** must also click **Reconnect Slack** on their own **Integrations** page.

## Allow automated posts

Conversation replies and automated bot posts have separate controls. A discovered channel starts inactive for outbound automation.

Use [Messaging destinations and connection health](/admin/integrations/messaging-destinations) to activate a channel, allow your automations, test delivery, and choose the per-message approval policy.

## Troubleshooting

<Accordion title="The app is configured but the workspace is not connected">
  Saving credentials prepares the app. Click **Connect Slack workspace** and complete Slack authorization to create the workspace connection.
</Accordion>

<Accordion title="Slack cannot verify the event request URL">
  Check that the public Sofie URL is reachable and matches the manifest. Confirm that you saved the signing secret from this Slack app in Sofie. Review **Setup incomplete** items with your Sofie administrator before retrying URL verification.
</Accordion>

<Accordion title="A user linked an account but cannot research Slack">
  Ask the user to finish personal Slack authorization. Confirm that the user callback URL and user permissions are present in the Slack app. A bot installation and a Sofie identity link alone do not provide personal research access.
</Accordion>

<Accordion title="Sofie stopped responding after an uninstall or revocation">
  Reconnect or reauthorize the workspace and test again. If the organization installation was disconnected or revoked, users must relink their accounts. Review and restore outbound destination permissions separately.
</Accordion>

## Related guides

* [Use Sofie with Slack](/integrations/slack)
* [Messaging destinations and connection health](/admin/integrations/messaging-destinations)
* [Integration administration](/admin/integration-administration)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.