Slack

Connect Comis to Slack with step-by-step setup

Connect your Comis agent to Slack workspaces. Slack supports threads, reactions, buttons, rich formatting (mrkdwn), file attachments up to 1 GB, and live-streaming responses. Choose between Socket Mode (simpler, no public URL needed — uses a WebSocket from @slack/bolt) or HTTP Mode (for production behind a reverse proxy with HMAC-SHA256 signed event subscriptions).

You don’t need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.

Prerequisites

• Comis installed and running (Quickstart)

• A Slack workspace where you have permission to install apps

Slack offers two connection modes: Socket Mode (recommended for getting started) and HTTP Mode (for production). Each requires different credentials. Choose one before starting setup.

Setup

1. Create a Slack App

   Go to the Slack API portal and sign in.

   Click Create New App and choose From scratch. Give your app a name (e.g. “Comis Agent”) and select the workspace you want to install it in.

2. Configure bot permissions

   In the left sidebar, go to OAuth & Permissions.

   Scroll down to Bot Token Scopes and add the following scopes:

   • chat:write — Send messages
   • channels:history — Read public channel messages
   • groups:history — Read private channel messages
   • im:history — Read direct messages
   • mpim:history — Read group direct messages
   • reactions:read — View reactions
   • reactions:write — Add reactions
   • files:read — Access shared files
   • files:write — Upload files
   • users:read — Look up user information
3. Choose your connection mode

   Socket Mode (Recommended)

   Socket Mode uses a WebSocket connection — no public URL or reverse proxy needed.

   1. In the left sidebar, go to Settings then Socket Mode
   2. Toggle Enable Socket Mode on
   3. Click Generate to create an App-Level Token
   4. Give it a name (e.g. “comis-socket”) and add the connections:write scope
   5. Copy the token starting with xapp- — you will need it later

   Then set up event subscriptions:

   1. In the left sidebar, go to Event Subscriptions
   2. Toggle Enable Events on
   3. Under Subscribe to bot events, add:
      • message.channels
      • message.groups
      • message.im
      • message.mpim
      • app_mention
   4. Click Save Changes

   HTTP Mode

   HTTP Mode receives events via HTTP webhooks. Your Comis instance must be reachable from the internet.

   1. In the left sidebar, go to Settings then Basic Information
   2. Under App Credentials, copy the Signing Secret

   Then set up event subscriptions:

   1. In the left sidebar, go to Event Subscriptions
   2. Toggle Enable Events on
   3. Set the Request URL to https://your-domain:port/webhooks/slack
   4. Slack will send a verification challenge — your Comis gateway handles this automatically once running
   5. Under Subscribe to bot events, add:
      • message.channels
      • message.groups
      • message.im
      • message.mpim
      • app_mention
   6. Click Save Changes
4. Install to workspace

   In the left sidebar, go to Install App and click Install to Workspace.

   Authorize the app when prompted. After installation, copy the Bot User OAuth Token starting with xoxb-.

5. Configure Comis

   Add the Slack channel to your Comis configuration file (~/.comis/config.yaml):

   Socket Mode

   channels:
     slack:
       enabled: true
       botToken: "${SLACK_BOT_TOKEN}"
       appToken: "${SLACK_APP_TOKEN}"
       mode: "socket"
   

   Set the environment variables in your ~/.comis/.env file:

   SLACK_BOT_TOKEN=xoxb-your-bot-token
   SLACK_APP_TOKEN=xapp-your-app-token
   

   HTTP Mode

   channels:
     slack:
       enabled: true
       botToken: "${SLACK_BOT_TOKEN}"
       signingSecret: "${SLACK_SIGNING_SECRET}"
       mode: "http"
   

   Set the environment variables in your ~/.comis/.env file:

   SLACK_BOT_TOKEN=xoxb-your-bot-token
   SLACK_SIGNING_SECRET=your-signing-secret
   

   Never store API keys, tokens, or passwords directly in config.yaml. Use the .env file or Secret Manager for credential management.

6. Restart and verify

   Restart the Comis daemon to pick up the new configuration:

   comis daemon stop && comis daemon start
   

   Check the logs for a successful connection:

   comis daemon logs
   

   Look for a line containing “Slack adapter connected” or “channel-slack activated”. If you see this, your bot is online.

   Go to your Slack workspace. The bot must be invited to a channel before it can see messages there — type /invite @your-bot-name in any channel. Send a message to confirm it responds.

Configuration

These options go under channels.slack in your config.yaml:

Option	Type	Default	What it does
enabled	boolean	false	Turns on the Slack adapter
botToken	string / SecretRef	(required)	Bot User OAuth Token (xoxb-...) from the Install App page
mode	"socket" or "http"	(required)	Connection mode — Socket Mode or HTTP Mode
appToken	string / SecretRef	(Socket Mode only)	App-Level Token (xapp-...) for Socket Mode
signingSecret	string / SecretRef	(HTTP Mode only)	Signing Secret for HTTP request verification
allowFrom	string[]	[] (all)	Restrict to specific Slack user IDs. Empty means all users can talk to the bot.
mediaProcessing.transcribeAudio	boolean	true	Transcribe voice messages to text before passing to the agent
mediaProcessing.analyzeImages	boolean	true	Describe images sent to the bot using AI vision
mediaProcessing.describeVideos	boolean	true	Extract descriptions from video content
mediaProcessing.extractDocuments	boolean	true	Extract text from PDFs, DOCX, and other documents
mediaProcessing.understandLinks	boolean	true	Fetch and summarize URLs included in messages

What your agent can do

Once connected to Slack, your agent can:

• Send, edit, and delete messages in any channel it has been invited to
• React to messages with emoji shortnames (thumbsup, eyes, etc.)
• Reply in threads (Slack reply chains via thread_ts)
• Send files and images (up to 1 GB per attachment)
• Create interactive buttons for user choices
• Send Block Kit sections, contexts, and image blocks for rich formatting
• Use mrkdwn formatting (bold *text*, italic _text_, strikethrough ~text~, code, links, lists)
• Stream responses with live editing (updates every 400 ms)
• Mention users and channels (<@userId>, <#channelId>)
• Fetch message history for conversation context (conversations.history)
• Pin/unpin messages, set channel topic and purpose, archive or unarchive channels, create new channels, invite or kick members, list members, and add channel bookmarks via platform actions

Slack does not natively support typing indicators, native polls, or message effects (Comis skips them automatically for Slack).

Platform limits

Limit	Value	What Comis does about it
Message length	4,000 characters	Automatically splits long responses into multiple messages at paragraph boundaries
Attachment size	1,000 MB	Generous limit, rarely hit in practice

Complete walkthrough: from zero to first reply

This walks through Socket Mode — the easiest way to get started.

1. Create the Slack app

   Open api.slack.com/apps, click Create New App -> From scratch. Name it MyTeamBot and pick your workspace.

2. Add bot scopes

   Under OAuth & Permissions, add the bot scopes from Step 2 above (chat:write, channels:history, groups:history, im:history, mpim:history, reactions:read, reactions:write, files:read, files:write, users:read).

3. Enable Socket Mode and event subscriptions

   Under Settings -> Socket Mode, toggle Socket Mode on, click Generate, name the token myteambot-socket, and copy the xapp-... token.

   Under Event Subscriptions, toggle events on and subscribe to message.channels, message.groups, message.im, message.mpim, and app_mention.

4. Install to workspace

   Under Install App, click Install to Workspace and accept. Copy the Bot User OAuth Token (xoxb-...).

5. Wire it into Comis

   Add to ~/.comis/.env:

   SLACK_BOT_TOKEN=xoxb-your-bot-token
   SLACK_APP_TOKEN=xapp-your-app-token
   

   Add to ~/.comis/config.yaml:

   channels:
     slack:
       enabled: true
       botToken: "${SLACK_BOT_TOKEN}"
       appToken: "${SLACK_APP_TOKEN}"
       mode: "socket"
   
6. Restart, invite, and chat

   comis daemon stop && comis daemon start
   comis daemon logs
   

   Look for Slack adapter connected. In a Slack channel, type /invite @MyTeamBot, then send a message. The agent replies and edits its message every 400 ms while the response streams in.

Troubleshooting

Socket Mode requires appToken

What happened: You configured mode: "socket" but did not provide an app-level token.

How to fix it: Go to the Slack API portal, select your app, navigate to Settings then Socket Mode, and generate an App-Level Token with connections:write scope. Copy the xapp-... token into your .env file.

HTTP Mode requires signingSecret

What happened: You configured mode: "http" but did not provide a signing secret.

How to fix it: Go to the Slack API portal, select your app, navigate to Basic Information under App Credentials, and copy the Signing Secret into your .env file.

Bot doesn't respond in channels

What happened: The bot has not been invited to the channel. Slack bots can only see messages in channels they have been explicitly added to.

How to fix it: In the Slack channel where you want the bot, type /invite @your-bot-name and press Enter. The bot will start receiving messages in that channel immediately.

Delivery Infrastructure

How streaming, typing indicators, and retry logic work under the hood.

Multiple users & teams

Run one install for a whole team - private per person, isolated per agent.

All Channels

Compare all 9 supported platforms side by side.

Agent Configuration

Set up your agent’s personality, tools, and behavior.

Secret Management

Learn how to manage API keys and tokens securely.