Skip to main content
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.

​
Set it up

1

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.
2

Configure ChatCLI

3

Start the gateway

4

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.

​
Environment variables

​
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.
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.

​
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

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.
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.
The upload needs the files:write scope; the gateway falls back to text when the upload fails.

​
See also

Chat gateway

How messages run, voice, images, continuity and the other channels.

Proactive messaging

Let the agent post to Slack on its own with @send.