Slack Bot

Kolleague uses your own Slack app. Once connected, team members can DM the Bot, @-mention it in a channel, or use /issue to create issues.

One Slack app maps to one Kolleague agent. To connect several agents, create a separate app for each.

Before you start

The connection must be completed by a workspace owner or admin, and ends with two credentials pasted into Kolleague:

• a Bot User OAuth Token, starting with xoxb-;
• an App-level Token, starting with xapp-.

1. Create the Slack app from a manifest

Open Slack API Apps, click Create New App → From a manifest, pick the Slack workspace, then paste the following under YAML:

display_information:
  name: Kolleague
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Kolleague
    always_online: true
  slash_commands:
    - command: /issue
      description: Create a Kolleague issue
      usage_hint: "[description]"
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - groups:history
      - im:history
      - mpim:history
      - chat:write
      - reactions:write
      - users:read
      - commands
settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
      - message.channels
      - message.groups
      - message.mpim
  interactivity:
    is_enabled: false
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false

Before creating, you can replace both occurrences of Kolleague with the agent's name. Do not remove scopes or events from the manifest, or DMs, channel mentions, replies, or /issue may stop working.

The Bot connects out to Slack over Socket Mode, so no public Request URL or OAuth Redirect URL is needed.

2. Get the two tokens

Bot token

1. In the Slack app, open Install App.
2. Click Install to Workspace and approve the permissions.
3. Copy the Bot User OAuth Token — it starts with xoxb-.

App-level token

1. Open Basic Information → App-Level Tokens.
2. Click Generate Token and Scopes.
3. Add the connections:write scope.
4. Generate and copy the token starting with xapp-.

3. Connect it to an agent

1. In Kolleague, open Agents and select the agent to connect to Slack.
2. Go to Integrations and click Connect Slack.
3. Paste the Bot token and the App-level token.
4. Click Connect.

Kolleague verifies that the two tokens come from the same app. Once connected, the page shows Connected to Slack.

First use

The first time a member DMs or @-mentions the Bot, they receive an account binding link. Sign in with the Kolleague account for that workspace, then return to Slack and send the message again.

The link is single-use and expires after 15 minutes. Once it expires, message the Bot again for a new one. Multiple Bots in the same Kolleague workspace can usually reuse an existing binding if they come from the same Slack workspace.

Only members of the current Kolleague workspace can use the Bot.

Hand work to the agent in Slack

Direct messages

Open the Bot from Apps in the Slack sidebar and message it directly — no @-mention needed.

Channels and group chats

Run /invite @your-bot to add the Bot to the channel first, then send @your-bot your request. Each thread forms its own session; for follow-ups, keep @-mentioning the Bot in the original thread.

The Bot only responds to channel messages that explicitly @-mention it. When it runs, it reads the thread's recent context within the scopes its permissions allow.

Create issues with /issue

In a channel or DM, type:

/issue Safari stays on the login page after a successful sign-in

This command needs no @-mention. Kolleague hands the description to the agent behind the current Bot, which writes up the title and body and creates the issue. Slack first shows an acknowledgment visible only to you; when the issue is created, you get a notification in your Kolleague inbox.

Manage connections

Open Settings → Integrations to view all connected Slack Bots. Workspace owners and admins can disconnect them.

After disconnecting, the Socket Mode connection stops and the Bot no longer receives new messages. Existing conversations and audit records are not deleted.

Troubleshooting

• Invalid token when connecting: check the prefixes and confirm both tokens come from the same app.
• App can't be verified: confirm the manifest includes users:read, then reinstall the app after updating permissions.
• No DM entry point: confirm app_home.messages_tab_enabled is true.
• No reply in a channel: confirm the Bot has been invited to the channel and the message @-mentions it.
• /issue doesn't exist: confirm the manifest includes the slash command and the commands scope, then reinstall the app.
• The Bot doesn't run: check whether the agent is archived and whether the runtime it uses is online.

Next steps

• Chat integrations — platform comparison, session isolation, and account binding mechanics.
• Chat — the conversation and execution model behind the Bot.
• Issues — the unit of work /issue creates.