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

# Slack

> Talk to ChatCLI from Slack through the Events API: a signed HTTP endpoint the gateway serves, voice and image messages in, and image replies.

Slack delivers events to an HTTP endpoint, so the gateway runs a small server for it and Slack must be able to reach it over HTTPS (a public host, a tunnel or a reverse proxy in front of `CHATCLI_SLACK_ADDR`). Every request is checked against the app's **signing secret**.

| | Slack |
| - | - |
| Transport | Events API: Slack posts events to an HTTP server the gateway runs |
| Who can talk to the bot | Anyone who can post where the app receives `message` events; there is no user allow-list |
| Voice notes in | Yes, an audio file in the message |
| Voice replies | No (text only) |
| Images in | Yes |
| Images out | Yes |
| "Working on it" signal | One short text notice if the reply takes more than about 2 seconds |

## Set it up

<Steps>
  <Step title="Create the Slack app">
    In your Slack workspace's app settings, create an app and give its bot the scopes it needs: `chat:write` to answer, `files:read` to download voice and image files, `files:write` for image replies, and the history scopes for the conversations it should read (for example `channels:history` and `im:history`). Install the app to the workspace and copy the **Bot User OAuth Token** (`xoxb-…`) and, from Basic Information, the **Signing Secret**.
  </Step>

  <Step title="Configure ChatCLI">
    ```bash theme={"system"}
    export CHATCLI_SLACK_BOT_TOKEN="xoxb-..."
    export CHATCLI_SLACK_SIGNING_SECRET="..."
    export CHATCLI_SLACK_ADDR=":8081"              # where the events server listens
    # export CHATCLI_SLACK_PATH="/slack/events"    # the default
    ```
  </Step>

  <Step title="Start the gateway">
    ```text theme={"system"}
    /gateway start
    /gateway status     # slack should be listed
    ```
  </Step>

  <Step title="Point Slack at the endpoint">
    Turn on **Event Subscriptions** and set the Request URL to the public HTTPS address that reaches `CHATCLI_SLACK_ADDR` and `CHATCLI_SLACK_PATH`, for example `https://bot.example.com/slack/events`. Slack verifies the URL right away, so the gateway must already be running. Subscribe the bot to the `message` events of the conversations it should handle (for example `message.channels` and `message.im`), save, and invite the bot to a channel or send it a direct message.
  </Step>
</Steps>

## Environment variables

| Variable | Required | Default | What it does |
| - | - | - | - |
| `CHATCLI_SLACK_BOT_TOKEN` | yes | — | The bot token (`xoxb-…`). |
| `CHATCLI_SLACK_ADDR` | yes | — | Address the events server binds, for example `:8081`. The adapter starts only when the token and the address are both set. |
| `CHATCLI_SLACK_SIGNING_SECRET` | yes, in practice | — | Verifies every request. Without it every event is refused with `401`, including Slack's URL verification, and a warning is logged at start. |
| `CHATCLI_SLACK_PATH` | no | `/slack/events` | Path of the events endpoint. |
| `CHATCLI_SLACK_HOME_CHANNEL` | no | — | Default channel ID for [proactive messages](/gateway/proactive-messaging) sent with `@send slack`. |

## Who can reach the bot

Each request must carry a valid `X-Slack-Signature` (HMAC-SHA256 of the request with the signing secret) and a timestamp no more than five minutes old; anything else gets `401`. Messages posted by bots are ignored, so the gateway never answers itself.

<Warning>
  There is no per-user allow-list on Slack: anyone who can post in a conversation the app listens to can run the agent, with its tools and shell. Limit the app to the channels and people who should use it.
</Warning>

## Messages

* **Text**: `message` events. Mentions arrive the same way, since a mention is a message; separate `app_mention` events are not used.
* **Voice**: the first audio file in a message is downloaded with the bot token and transcribed before the agent runs.
* **Images**: the first image file in a message reaches the model.
* **Image replies** are uploaded with Slack's file upload API, with the reply text as the comment; on any failure the text is sent alone.
* **Replies are posted in the conversation**, not in a thread.
* A message that carries only other kinds of files (a PDF, a zip) is ignored.

## Limits

* A reply is cut at **3500 characters** and ends with `…`.
* Slack's errors (for example `not_in_channel` when the bot was not invited) are logged as failed sends in `~/.chatcli/gateway.log`.
* Slack retries an event it did not see acknowledged in time; a retried event is processed again.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Slack says the Request URL did not respond">
    The gateway must be running and reachable at the URL, and `CHATCLI_SLACK_SIGNING_SECRET` must be set: without it the verification request is refused with `401`. Check `~/.chatcli/gateway.log` for the warning about the missing secret.
  </Accordion>

  <Accordion title="The bot sees nothing in a channel">
    Invite the bot to the channel and make sure the app is subscribed to that conversation type's `message` event and has the matching history scope.
  </Accordion>

  <Accordion title="Image replies arrive as text only">
    The upload needs the `files:write` scope; the gateway falls back to text when the upload fails.
  </Accordion>
</AccordionGroup>

## See also

<CardGroup cols={2}>
  <Card title="Chat gateway" icon="comments" href="/gateway/chat-gateway">
    How messages run, voice, images, continuity and the other channels.
  </Card>

  <Card title="Proactive messaging" icon="paper-plane" href="/gateway/proactive-messaging">
    Let the agent post to Slack on its own with `@send`.
  </Card>
</CardGroup>


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