Codumentor logo Codumentor

Slack Integration Plugin

The Slack Integration plugin connects Codumentor to a Slack workspace in both directions:

Overview

  1. Opens a Socket Mode WebSocket to Slack — no public URL or webhook receiver required.
  2. Maps each Slack thread to a single Codumentor conversation in plugin-owned SQLite (data/slack_integration.sqlite3). Subsequent replies in the same thread continue the same conversation.
  3. Subscribes to onResponsePersist to auto-post the agent's final response to the originating thread (only main-agent answers, never subagent intermediate output).
  4. Registers two agent-callable tools via onPromptAssemble.
  5. Runs a daily TTL sweep to age out stale event-dedup rows and 30-day-old thread mappings.

Requirements

The plugin needs the slack-bolt Python package (which pulls in slack-sdk):

pip install slack-bolt

Both are already declared in requirements.txt and setup.py. A standard pip install -e . (or whatever the project uses) picks them up.

You also need a Slack app with Socket Mode enabled. See Slack App Setup below.

Configuration

Basic Configuration

plugins:
  - module: codumentor.plugins.slack_integration
    class: SlackIntegrationPlugin
    args:
      enabled: true
      bot_token_env: SLACK_BOT_TOKEN     # env var holding the xoxb- token
      app_token_env: SLACK_APP_TOKEN     # env var holding the xapp- token
      service_user_id: slack-bot         # Codumentor user that owns Slack-originated conversations

Both tokens must be present in the environment when the API server starts. If either is missing, the plugin loads in degraded mode — no listener, no tools, no crash — and logs a warning.

Full Configuration

plugins:
  - module: codumentor.plugins.slack_integration
    class: SlackIntegrationPlugin
    priority: 50
    args:
      enabled: true
      bot_token_env: SLACK_BOT_TOKEN
      app_token_env: SLACK_APP_TOKEN
      service_user_id: slack-bot
      slash_command_name: codumentor              # Slack-side command is /codumentor
      enabled_triggers: [app_mention, im, slash_command]
      target_agents: main                         # which agent types get the tools
      auto_reply_to_thread: true                  # post final reply back to Slack

Configuration Parameters

ParameterTypeDefaultDescription
enabledbooltrueMaster on/off switch.
bot_token_envstringSLACK_BOT_TOKENEnvironment variable holding the bot user OAuth token (xoxb-...).
app_token_envstringSLACK_APP_TOKENEnvironment variable holding the app-level token (xapp-...) with connections:write scope, used for Socket Mode.
service_user_idstringslack-botCodumentor user that owns Slack-originated conversations. Must be a real user in your auth provider (with auth.provider: none, any string is accepted on first use).
slash_command_namestringcodumentorSlash-command name (without the leading /). Must match the command configured in the Slack app.
enabled_triggerslist[app_mention, im, slash_command]Which Slack events start an agent turn. Allowed values: app_mention, im, slash_command.
target_agentsstringmainWhich agent types receive the Slack tools. One of main, subagent, all.
auto_reply_to_threadbooltrueWhen true, the agent's final response is automatically posted back into the Slack thread that triggered the turn. Set to false if you want the agent to decide via slack_send_message.

Token Handling

Tokens are read from the environment, never from the YAML file. The plugin records only the env-var names (bot_token_env, app_token_env) — the resolved secrets are kept in memory and never logged. If a token rotates, restart the Codumentor API server with the new value in the environment.

Tools

slack_send_message

Post a message to a Slack channel or thread.

ParameterRequiredDescription
channelYesChannel id (C…/D…/G…), #channel-name, or user id (U…) for a DM.
textYesMessage text. Slack mrkdwn is supported.
thread_tsNoIf supplied, the message is posted as a threaded reply under the message at that ts.

Returns the channel id and ts of the posted message in metadata.

slack_add_reaction

Add an emoji reaction to an existing Slack message.

ParameterRequiredDescription
channelYesChannel id where the message lives.
tsYesTimestamp (ts) of the target message.
emojiYesEmoji name without colons, e.g. thumbsup, eyes.

already_reacted errors are treated as a successful no-op so the agent can call the tool idempotently.

Inbound Triggers

app_mention

When someone mentions the bot in a channel (@codumentor what files are…), the plugin starts an agent turn whose conversation is bound to that Slack thread. Subsequent mentions or replies in the same thread continue the same conversation.

im (direct messages)

When someone DMs the bot, each DM thread is a separate Codumentor conversation. The bot's own messages are ignored so the auto-reply doesn't ping-pong.

slash_command

/codumentor <prompt> posts an in-channel acknowledgement (/codumentor … _thinking…_) and starts an agent turn whose reply is threaded under the ack. The slash-command name is configurable.

Slack App Setup

  1. Create a new Slack app at (from scratch).
  2. Socket Mode → Enable Socket Mode → generate an app-level token with the connections:write scope. This is the xapp-... token (SLACK_APP_TOKEN).
  3. OAuth & Permissions → add bot scopes: - app_mentions:read - chat:write - im:history, im:read, im:write (for DM trigger) - commands (for slash command) - reactions:write (for the slack_add_reaction tool)
  4. Event Subscriptions → enable events, subscribe the bot to app_mention and message.im.
  5. Slash Commands → create /codumentor (or whatever you set slash_command_name to). The request URL is not used by Socket Mode but Slack still requires a placeholder — any URL is fine.
  6. Install to Workspace → grants the xoxb-... bot token (SLACK_BOT_TOKEN).
  7. Invite the bot to any channel where you want it to respond.

State & Storage

Plugin-private SQLite at data/slack_integration.sqlite3:

A background TTL task runs once every 24 hours and purges:

Behavior Notes

Limitations

Manual Verification

See src/codumentor/plugins/slack_integration/VERIFY.md in the repo for an end-to-end manual verification checklist (Slack app creation, token wiring, the four trigger flows, degraded mode, and restart durability).