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

# Slack bot

> Deploy Hadiq.io as a Slack bot so your team can ask questions and get AI answers without leaving Slack.

The Hadiq.io Slack bot lets users send messages or @mention the bot in any channel to get AI-powered answers drawn from your team's indexed knowledge. You can create multiple bots and map each one to a different AI Agent, so different channels or teams get responses tuned to their context.

## How it works

Each Slack bot you create in Hadiq.io corresponds to a Slack app installed in your workspace. When a user messages the bot directly or @mentions it in a channel, Hadiq.io receives the message, runs it through the configured Agent, and replies in the same thread or channel.

You control:

* **Which Agent answers** — each bot maps to one Hadiq.io Agent (persona), inheriting its instructions, knowledge, and actions.
* **Which channels it responds in** — configure per-channel behavior, or rely on the bot's default configuration.
* **How it responds** — standard citations, detailed quotes, ephemeral (private) replies, and more.

## Prerequisites

Before setting up the bot in Hadiq.io, you need to create a Slack app in your Slack workspace and collect three tokens:

| Token                   | Where to find it                                                                              |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| Bot Token (`xoxb-...`)  | **OAuth & Permissions** → **Bot User OAuth Token**                                            |
| App Token (`xapp-...`)  | **Basic Information** → **App-Level Tokens**                                                  |
| User Token (`xoxp-...`) | **OAuth & Permissions** → **User OAuth Token** — optional, enables access to private channels |

Your Slack app needs Socket Mode enabled and the following OAuth scopes:

**Bot token scopes:** `app_mentions:read`, `channels:history`, `channels:join`, `channels:read`, `chat:write`, `groups:history`, `groups:read`, `im:history`, `im:read`, `im:write`, `mpim:history`, `reactions:write`, `users:read`, `users:read.email`

<Note>
  Enable **Socket Mode** in your Slack app settings. Hadiq.io uses Socket Mode to receive events without requiring a public webhook URL.
</Note>

## Setup

<Steps>
  <Step title="Create a Slack app">
    Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app **From scratch**. Choose a name (e.g. "Hadiq.io") and select your workspace.

    Enable **Socket Mode** under **Settings → Socket Mode**, then generate an App-Level Token with the `connections:write` scope. Copy this token — it is your **App Token**.
  </Step>

  <Step title="Add OAuth scopes">
    Go to **OAuth & Permissions** and add the bot token scopes listed above under **Bot Token Scopes**.

    Optionally add the same scopes under **User Token Scopes** if you want the bot to access private channels on behalf of users.
  </Step>

  <Step title="Subscribe to events">
    Go to **Event Subscriptions** and enable events. Subscribe to the following **Bot Events**:

    * `app_mention`
    * `message.channels`
    * `message.groups`
    * `message.im`
    * `message.mpim`
  </Step>

  <Step title="Install the app to your workspace">
    Go to **OAuth & Permissions** and click **Install to Workspace**. Authorize the permissions.

    After installation, copy the **Bot User OAuth Token** (`xoxb-...`) from the same page.
  </Step>

  <Step title="Add the bot in Hadiq.io Admin">
    In Hadiq.io, go to **Admin → Bots** and click **New Slack Bot**.

    Fill in:

    * **Name** — a label for this bot (internal only, e.g. "Engineering Bot")
    * **Slack Bot Token** — your `xoxb-...` bot token
    * **Slack App Token** — your `xapp-...` app-level token
    * **Slack User Token** — optional `xoxp-...` user token for private channel access

    Click **Create**. Hadiq.io validates the tokens before saving.
  </Step>

  <Step title="Configure channel behavior">
    After creating the bot, you are taken to its configuration page. Here you can:

    * Edit the **Default Configuration** — this applies to all channels and DMs not explicitly configured.
    * Add **Channel-Specific Configurations** to customize behavior per channel.

    For each configuration (default or channel-specific), choose a **Knowledge Source**:

    | Option                 | Description                                                                       |
    | ---------------------- | --------------------------------------------------------------------------------- |
    | All Public Knowledge   | Answers using all publicly indexed connectors                                     |
    | Specific Document Sets | Answers using selected document sets only                                         |
    | Search Agent           | Uses a specific search-enabled Agent with its own documents and prompt            |
    | Non-Search Agent       | Uses an Agent that does not search documents (e.g. a coding or writing assistant) |

    <Tip>
      Map each channel to a dedicated Agent to give it a focused persona — for example, map `#support` to a Customer Support agent and `#engineering` to an Engineering agent.
    </Tip>
  </Step>

  <Step title="Tag the bot in Slack">
    Once the bot is installed and configured, your team can interact with it in two ways:

    * **Direct message** the bot
    * **@mention** it in any channel where it is configured to respond (e.g. `@Hadiq.io what is our SLA policy?`)

    Hadiq.io replies in the same thread with citations from your indexed knowledge.
  </Step>
</Steps>

## Channel configuration options

When editing a channel configuration, you have access to additional settings beyond the knowledge source:

**Search configuration** (when using a search-enabled knowledge source):

* **Answer type** — Standard (citations) or Detailed (quotes)
* **Only respond if citations found** — Skip responding when the model cannot find supporting documents

**General configuration:**

* **Respond to @hadiqBot only** — The bot ignores messages unless directly tagged
* **Only respond to questions** — Filter to messages containing a question mark
* **Respond to bot messages** — Allow the bot to reply to automated messages
* **Respond in a private (ephemeral) message** — Only the asking user sees the reply
* **Show "Continue in Web UI" button** — Add a link to continue the conversation in Hadiq.io's web interface
* **"Still need help?" button** — Show a follow-up button; optionally tag specific users or groups
* **Restrict to specific users or groups** — Limit who the bot responds to within a channel

## Multiple bots

You can create as many Slack bots as your workflows require. Each bot is its own Slack app with its own tokens. A common pattern is one bot per team or use case:

* `@SalesBot` → Sales Agent with CRM and proposal knowledge
* `@SupportBot` → Support Agent with documentation and runbooks
* `@EngineeringBot` → Engineering Agent with codebase and design docs

To add another bot, go to **Admin → Bots** and click **New Slack Bot** again.

<Warning>
  Disabling the **Default Configuration** for a bot means it will not respond in any channel unless that channel has an explicit configuration. It will also stop responding to DMs.
</Warning>

## Troubleshooting

If the bot is not responding, verify:

1. The bot is **Enabled** on its configuration page in Hadiq.io Admin.
2. The Slack tokens are valid — click **Update Tokens** to re-enter them.
3. The bot has been installed to your Slack workspace and added to the channel.
4. Socket Mode is enabled in the Slack app settings.
5. The channel has a configuration (or the default configuration is active).