Codumentor logo Codumentor

Slack Integration Plugin

Connects Codumentor to a Slack workspace in both directions:

Uses Slack Socket Mode, so you do not need a public URL or webhook receiver.

Requirements

A Slack app with Socket Mode enabled (see Slack App Setup). The slack-bolt package is already a Codumentor dependency.

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

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. Unknown values are dropped.
target_agentsstringmainWhich agent types receive the Slack tools. One of main, subagent, all.
auto_reply_to_threadbooltrueWhen true, the agent's final response is posted back into the Slack thread that triggered the turn. Set to false if you want the agent to decide via slack_send_message.

Tokens are read from the environment, never from the YAML file. Only the env-var names are recorded. If a token rotates, restart the 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.

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.

Calling this on a message that already has that reaction is treated as success, so the agent can retry safely.

Inbound triggers

app_mention

When someone mentions the bot in a channel (@codumentor what files are…), an agent turn starts whose conversation is bound to that Slack thread. Later 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 does not 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.

Behavior

Limitations