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

# Bot Token

> Connect Parable to Slack using a bot token

export const platform_1 = "Slack"

export const limit_0 = "tier-based limits; typically 20-100 requests/minute per method"

export const platform_0 = "Slack"

export const role_0 = "Workspace Owner or Workspace Admin (must be allowed to install apps to the workspace)"

<Tabs>
  <Tab title="Setup">
    <Card title="What You'll Need" icon="key">
      | Credential | What it is                            |
      | ---------- | ------------------------------------- |
      | **Token**  | `xoxb-` prefixed bot token from Slack |
    </Card>

    ## Overview

    Connect Parable to Slack using a custom Slack App with bot permissions for secure workspace data access.

    <CardGroup cols={2}>
      <Card title="Users" icon="users">
        User profiles
      </Card>

      <Card title="Conversations" icon="comments">
        Public channels and private channels where the bot is a member; messages and threads in those channels only. No DMs or group DMs.
      </Card>
    </CardGroup>

    ## Prerequisites

    <Info>
      **Setup access in {platform_0}.** These steps require **{role_0}**, or a colleague with equivalent permissions who can create credentials for you.

      If that is not you, ask your {platform_0} administrator.
    </Info>

    ## Setup Guide

    <Steps>
      <Step title="Create Slack App">
        1. Go to <a href="https://api.slack.com/apps" target="_blank" rel="noopener noreferrer">Slack API Apps</a>
        2. Click **Create New App** → **From scratch**
        3. Name: `Parable Integration`
        4. Select your workspace
        5. Click **Create App**
      </Step>

      <Step title="Configure Bot Scopes">
        1. Go to **OAuth & Permissions** in the sidebar
        2. Scroll to **Bot Token Scopes**
        3. Add these scopes:

        | Scope              | Purpose                                         |
        | ------------------ | ----------------------------------------------- |
        | `channels:history` | Read public channel messages                    |
        | `channels:read`    | List public channels                            |
        | `groups:history`   | Read messages in private channels the bot is in |
        | `groups:read`      | List private channels the bot is a member of    |
        | `users:read`       | Read user profiles                              |
        | `users:read.email` | Read user email addresses                       |
        | `team:read`        | Read workspace info                             |
      </Step>

      <Step title="Install to Workspace">
        1. Scroll up to **OAuth Tokens for Your Workspace**
        2. Click **Install to Workspace**
        3. Review permissions and click **Allow**

        <Tip>
          Slack opens an approval screen in the same browser tab. After you click **Allow**, use the browser back button if needed, then copy the **Bot User OAuth Token** from **OAuth & Permissions** in Slack.
        </Tip>
      </Step>

      <Step title="Add App to Channels">
        Parable can only read messages from channels where **Parable Integration** is a member. This is required for **both public and private channels**.

        For each channel Parable should consume:

        1. Open the channel in Slack
        2. Add the app using one of these methods:
           * Type `/invite @Parable Integration` in the message box and send
           * Click the channel name → **Integrations** → **Add apps** → select **Parable Integration**

        <Warning>
          If you skip this step, those channels will be missing or empty in Parable after sync.
        </Warning>
      </Step>

      <Step title="Copy Bot Token">
        After installation, copy the **Bot User OAuth Token**

        It starts with `xoxb-`

        <Info>
          The token is persistently visible on the **OAuth & Permissions** page of your app at any time — return to <a href="https://api.slack.com/apps" target="_blank" rel="noopener noreferrer">api.slack.com/apps</a>, select the app, and copy it again if needed. The token only becomes invalid if you uninstall and reinstall the app, or explicitly revoke it.
        </Info>
      </Step>

      <Step title="Enter values in the form">
        1. **Connection name** (optional): A friendly label for this workspace in Parable.
        2. **Token**: Paste the **Bot User OAuth Token** (`xoxb-...`).
        3. Click **Save & test connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Reference">
    ## Verify Your Setup

    <CodeGroup>
      ```bash Test Authentication theme={null}
      curl -H "Authorization: Bearer xoxb-YOUR-TOKEN" \
        "https://slack.com/api/auth.test"
      ```

      ```bash List Users theme={null}
      curl -H "Authorization: Bearer xoxb-YOUR-TOKEN" \
        "https://slack.com/api/users.list?limit=5"
      ```
    </CodeGroup>

    <Check>
      If you received a `200 OK` response with valid data, your credentials are configured correctly. You can now proceed to configure this connector in Parable.
    </Check>

    <Tip>
      **Rate Limits:** {platform_1} enforces rate limits of **{limit_0}**.

      Parable handles rate limiting automatically with exponential backoff, but initial syncs of large datasets may take longer due to these limits.
    </Tip>

    ## Troubleshooting

    | Error               | Meaning                     | Solution                                        |
    | ------------------- | --------------------------- | ----------------------------------------------- |
    | `invalid_auth`      | Bad token                   | Verify token is correct and starts with `xoxb-` |
    | `missing_scope`     | Scope not granted           | Add required scope and reinstall app            |
    | `channel_not_found` | No access to channel        | Add **Parable Integration** to the channel      |
    | `not_in_channel`    | Bot is not a channel member | Add **Parable Integration** to the channel      |
    | `ratelimited`       | Rate limit hit              | Implement backoff using `Retry-After` header    |

    <Accordion title="Common Issues">
      ### Bot can't see channel messages

      **Parable Integration** must be added to each channel you want Parable to consume — this applies to both public and private channels. Use `/invite @Parable Integration` in the channel, or add the app from the channel's **Integrations** menu.

      ### Token regeneration

      You can regenerate tokens in the app settings under **OAuth & Permissions** by reinstalling the app.
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="Slack API" icon="book" href="https://api.slack.com/methods">
        API method reference
      </Card>

      <Card title="OAuth Scopes" icon="key" href="https://api.slack.com/scopes">
        Complete scope reference
      </Card>
    </CardGroup>
  </Tab>
</Tabs>