Tornevall Networks

← Back to docs

Slack AI Bot usage and pilot testing

Slack AI Bot usage and pilot testing

Overview

Tornevall Networks Tools is a Slack AI assistant backed by ToolsAPI. This document is intended for pilot workspaces, workspace administrators, testers, and Slack Marketplace reviewers who need to install and exercise the app before Marketplace submission.

Public product information is available at https://tools.tornevall.net/slack-ai-bot and support information at https://tools.tornevall.net/slack-ai-bot/support.

The Direct Install URL is:

https://tools.tornevall.net/slack-bot/install/marketplace

The OAuth callback URL is:

https://tools.tornevall.net/oauth/slack/callback

The Slack Events Request URL is:

https://tools.tornevall.net/api/slack-bot/events

The Direct Install URL starts the normal Tools-controlled OAuth flow. Pilot users still need the Tools access required by the installation flow; the URL is not an access-control bypass.

Who should use this app

The pilot is suitable for Slack workspaces that want to test AI-assisted replies in direct messages, mentions, Slack Assistant threads, and supported image/file workflows. Workspace owners or app managers should be involved when the workspace requires app approval.

Slack requires Marketplace candidates to have at least five installs on active workspaces before submission. An active workspace is one used within the previous 28 days. Slack's install count can lag behind completed pilot installs and may take up to 24 hours to update, so do not treat an immediately unchanged count as proof that installation failed.

Installation

Before the app is listed in the Slack Marketplace, pilot workspaces can install it through the Direct Install URL above.

  1. Sign in to Tools when prompted and complete any required Slack Bot access approval.
  2. Open the Direct Install URL.
  3. Review the permissions Slack displays for Tornevall Networks Tools.
  4. Choose the target workspace and approve the installation. If the workspace uses app approval, a workspace owner or app manager may need to approve the request first.
  5. Return to Tools after Slack completes OAuth and verify that the workspace is shown as installed.

Whenever the app's required Slack scopes change, reinstall or re-authorize the app through the Direct Install URL so the workspace grants the current scope set. Existing tokens do not automatically gain newly requested permissions.

Required Slack permissions

The current bot permission set is:

  • app_mentions:read - receive direct app mentions.
  • assistant:write - participate in Slack Assistant threads.
  • chat:write - post replies and App Home message content.
  • reactions:write - acknowledge accepted requests with reactions.
  • channels:history - read relevant public-channel context.
  • channels:read - discover/read public-channel metadata used by supported workflows.
  • groups:history - read relevant private-channel context where the app is present.
  • groups:read - discover/read private-channel metadata available to the installation.
  • im:history - read direct-message context.
  • im:read - discover/read direct-message conversations.
  • mpim:history - read supported multi-person direct-message history.
  • files:read - fetch Slack-hosted files/images when needed for a requested workflow.
  • files:write - deliver generated or processed files back to Slack.
  • incoming-webhook - support Slack webhook installation capability where configured.
  • links:read - receive supported shared-link information.

Slack permissions are shown during installation. If Tools diagnostics reports missing scopes, reinstall through the Direct Install URL.

App Home uses the Messages tab. Posting there requires chat:write, while App Home opening behavior requires the app_home_opened event subscription.

Event subscriptions

Configure Slack Event Subscriptions with this Request URL:

https://tools.tornevall.net/api/slack-bot/events

The pilot/Marketplace event subscription set should include:

  • app_mention
  • app_home_opened
  • message.im
  • message.channels
  • message.groups
  • assistant_thread_started
  • assistant_thread_context_changed
  • link_shared

Scopes and Event Subscriptions are separate Slack configuration contracts. Reinstalling the app updates granted scopes but does not prove that the Events Request URL and bot-event subscriptions have been saved correctly in Slack.

How to test the app

Use at least the following checks in each pilot workspace:

  1. Send the app a direct message with a simple question and confirm that it acknowledges and replies.
  2. Mention the app in a channel where it is installed, for example @Tornevall Networks Tools, and confirm that the reply appears in the expected conversation or thread.
  3. Continue a thread after the bot has participated and confirm that supported follow-up behavior stays in that thread.
  4. Start or continue a Slack Assistant/App Agent style thread supported by the workspace and confirm that the reply preserves thread context.
  5. If image/file workflows are enabled for the workspace, attach a supported image or file and ask a question that requires it. Confirm that the attachment is used only for that requested workflow.
  6. Open App Home and confirm that its Messages experience loads without permission errors.
  7. Review Tools delivery diagnostics and confirm that recent supported events are reaching Tools.

For Marketplace pilot work, repeat these checks on multiple active workspaces rather than counting installs alone.

Expected behavior

The app can respond to:

  • Direct messages.
  • Direct app mentions.
  • Slack Assistant/App Agent threads supported by the installed app experience.
  • Supported channel-thread follow-ups after the bot has already participated.
  • Supported image/file workflows when enabled by workspace settings and permitted by the installed scopes.

Accepted messages may receive an acknowledgement reaction before the AI response is produced. Replies should remain in the originating Slack conversation/thread. The app does not need to answer every ordinary channel message; spontaneous channel behavior is workspace-controlled and intentionally conservative.

Workspace configuration

Workspace owners can use the Tools Slack Bot configuration page to control the behavior available to their installation. Depending on the current workspace settings, configuration can include direct-message replies, mention replies, bounded conversation context, supported image handling, and opt-in spontaneous replies for specifically allowed channels.

Configuration is workspace-scoped. Installing the app in one Slack workspace does not transfer another workspace's settings or Slack credentials.

When testing a problem, compare the workspace's granted scopes and delivery diagnostics with the expected permission and event lists in this document.

Data handling and privacy

Slack message content is used only to process user-requested replies and the bounded conversation context needed for those replies. Tools does not use Slack data to train language models.

Slack bot access and refresh tokens are stored encrypted. They are treated as workspace credentials and are not shown in public documentation, diagnostics, or normal user interfaces.

Slack-hosted image/file attachments are fetched only when needed for the workflow requested by the user. Supported images can be supplied transiently to the AI request when necessary, but Tools does not build a permanent Slack-message or attachment archive as a side effect of the bot.

For broader service/privacy information, see the public privacy documentation and sub-processor register in Tools documentation.

Requests to delete Slack-related data can be sent to support@tornevall.net.

Troubleshooting

If the bot does not respond:

  1. Check Slack Event Subscriptions and confirm that the Request URL is accepted and the required bot events are saved.
  2. Check that the workspace installation has the current bot scopes. Reinstall through https://tools.tornevall.net/slack-bot/install/marketplace after scope changes or when scopes are missing.
  3. Review Tools delivery diagnostics for the workspace. Confirm that recent supported events are reaching Tools and check for missing-scope or delivery warnings.
  4. Confirm that the app is present in the channel/conversation being tested and that workspace app-approval policy is not blocking an update.
  5. For App Home problems, confirm both chat:write and the app_home_opened event.
  6. For image/file problems, confirm files:read and, when file delivery is expected, files:write.

If OAuth completes but the app still behaves as though old permissions are active, perform the reinstall through the Direct Install URL rather than relying on the previous installation.

Uninstalling the app

Workspace owners or app managers can remove Tornevall Networks Tools using Slack's installed-app management interface. Slack workspace policies determine who is allowed to uninstall an app.

After uninstalling, the Slack workspace can no longer use the stored OAuth installation to send or receive app traffic. For deletion of associated Tools-side Slack data, contact support@tornevall.net.

Support

Public support information:

https://tools.tornevall.net/slack-ai-bot/support

Email:

support@tornevall.net

When reporting a pilot issue, include the workspace name, approximate time of the test, the type of interaction used (DM, mention, Assistant thread, file/image, or App Home), and any safe diagnostic/error identifier shown by Tools. Do not send Slack bot tokens, refresh tokens, signing secrets, or other credentials.