Slack Bot

Bring Vaquill’s legal research engine into any Slack workspace. The bot responds to @mentions, direct messages, and slash commands, replies in-thread with cited case law and statutes, and supports follow-up questions without re-mentioning the bot. Source code lives at github.com/Vaquill-AI/integrations/slack-bot.

Features

@mention, DM, and /vaquill slash command surfaces
Per-thread conversation memory with configurable timeout
Cited sources block (case name, citation, court) and Helpful / Not Helpful feedback buttons
Starter-question buttons when the bot is mentioned without a query
Per-user and per-channel rate limits (in-memory or Redis-backed)
User and channel allowlists / blocklists

Prerequisites

Python 3.10+ (or Docker)
Slack workspace where you can install custom apps
Vaquill API key from app.vaquill.ai/settings (starts with vq_key_). See Authentication.
Optional: Redis for distributed rate limiting across multiple bot instances

Platform setup

You need a Slack app with bot scopes, event subscriptions, two slash commands, and either Socket Mode or HTTP mode enabled.

Create the Slack app

Open api.slack.com/apps, click Create New App, choose From scratch, name it (e.g. “Vaquill Legal AI”), and select your workspace.

Add bot token scopes

Under OAuth & Permissions > Bot Token Scopes, add every scope in the table below. Missing scopes cause silent failures.

Scope	Why
`app_mentions:read`	Detect `@mentions` of the bot
`channels:history`	Read public channel messages the bot sees
`channels:read`	Look up basic channel info
`chat:write`	Send messages and threaded replies
`commands`	Register `/vaquill` and `/vaquill-help`
`groups:history`	Read private channel messages
`groups:read`	Look up private channel info
`im:history`	Read direct messages
`im:read`	Look up DM info
`im:write`	Open DM conversations
`users:read`	Filter out bot-to-bot messages

Subscribe to events

Under Event Subscriptions, toggle Enable Events on and subscribe to: app_mention, message.im, and optionally message.channels. For HTTP mode, set the Request URL to https://your-domain.com/slack/events. Skip the URL for Socket Mode.

Create /vaquill and /vaquill-help under Slash Commands. Use https://your-domain.com/slack/events as the Request URL for HTTP mode.

Enable Socket Mode (recommended for dev)

Under Socket Mode, toggle it on. When prompted, create an App-Level Token with the connections:write scope. Copy the token (starts with xapp-) - this is your SLACK_APP_TOKEN. Skip this step if you want HTTP mode.

Install to workspace and copy credentials

Under OAuth & Permissions, click Install to Workspace. Copy the Bot User OAuth Token (starts with xoxb-) as SLACK_BOT_TOKEN. Under Basic Information > App Credentials, copy the Signing Secret as SLACK_SIGNING_SECRET.

Socket Mode vs HTTP Mode

The bot auto-detects mode: if SLACK_APP_TOKEN is set, it uses Socket Mode. Otherwise it starts an HTTP server on PORT (default 3000).

	Socket Mode	HTTP Mode
Transport	Outbound WebSocket from bot to Slack	Slack POSTs to your server
Public URL needed?	No	Yes (HTTPS required)
Best for	Local dev, firewalled environments	Production, cloud deployments
Extra token	`SLACK_APP_TOKEN` (`xapp-...`)	None
Setup work	Toggle Socket Mode in app settings	Set Request URLs on Events, Commands, Interactivity

Use Socket Mode locally to skip ngrok entirely. Switch to HTTP mode in production by removing SLACK_APP_TOKEN from the environment.

Quickstart

Clone and install

git clone https://github.com/Vaquill-AI/integrations.git
cd integrations/slack-bot
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configure environment

cp .env.example .env

Set the minimum required values:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_APP_TOKEN=xapp-your-app-token      # enables Socket Mode
VAQUILL_API_KEY=vq_key_your-api-key
VAQUILL_COUNTRY_CODE=US

Run

python bot.py

Look for Bot initialised with user ID: U0XXXXXXX. In Slack, invite the bot to a channel with /invite @Vaquill, then try:

@Vaquill What is qualified immunity under 42 USC 1983?

Configuration

The top env vars. See the repo’s .env.example for the full reference.

Variable	Required	Default	Description
`SLACK_BOT_TOKEN`	Yes	-	Bot User OAuth Token (`xoxb-...`)
`SLACK_SIGNING_SECRET`	Yes	-	App signing secret from Basic Information
`SLACK_APP_TOKEN`	No	-	App-level token (`xapp-...`); presence enables Socket Mode
`VAQUILL_API_KEY`	Yes	-	Vaquill API key (`vq_key_...`)
`VAQUILL_API_URL`	No	`https://api.vaquill.ai/api/v1`	API base URL
`VAQUILL_MODE`	No	`standard`	RAG tier: `standard` or `deep`
`VAQUILL_COUNTRY_CODE`	No	-	Jurisdiction filter, e.g. `US`
`REDIS_URL`	No	-	Enables distributed rate limiting
`RATE_LIMIT_PER_USER`	No	`20`	Max requests per user per minute
`RATE_LIMIT_PER_CHANNEL`	No	`100`	Max requests per channel per hour
`PORT`	No	`3000`	HTTP server port (HTTP mode only)

Commands

Command	Usage	Description
`/vaquill`	`/vaquill <question>`	Ask a legal question, answer posted in channel
`/vaquill-help`	`/vaquill-help`	Show usage instructions and tips
`@Vaquill <question>`	In any channel the bot is in	Mention the bot to ask a question
DM	Direct message the bot	No `@mention` needed

Slack requires a response within 3 seconds. The bot sends a “Thinking…” placeholder immediately and edits it once the Vaquill API replies.

Deployment

Docker Compose (recommended)

The repo ships a docker-compose.yml that bundles the bot with Redis for rate limiting.

cp .env.example .env
# edit .env
docker compose up -d
docker compose logs -f bot

Standalone Docker

docker build -t vaquill-slack-bot .
docker run -d --name vaquill-slack-bot \
  -e SLACK_BOT_TOKEN="xoxb-..." \
  -e SLACK_SIGNING_SECRET="..." \
  -e SLACK_APP_TOKEN="xapp-..." \
  -e VAQUILL_API_KEY="vq_key_..." \
  -p 3000:3000 \
  vaquill-slack-bot

Cloud hosts

Railway

Push the repo, set env vars in the Railway dashboard. Railway provisions an HTTPS domain you can paste into Slack’s Request URLs.

Render

Web Service. Build: pip install -r requirements.txt. Start: python bot.py. Free tier sleeps after 15 minutes - slash commands may time out on cold starts.

Fly.io

fly launch, then fly secrets set ... for each env var, then fly deploy.

VPS + nginx

Reverse-proxy port 3000 behind TLS (Let’s Encrypt or Cloudflare). Use Socket Mode to skip the proxy entirely.

For production, run in HTTP mode (drop SLACK_APP_TOKEN) behind HTTPS and update Event Subscriptions, Slash Commands, and Interactivity Request URLs to https://your-domain.com/slack/events.

Troubleshooting

Scope changes only take effect after reinstalling the app to your workspace. If you see missing_scope errors, add the scope and reinstall.

Symptom	Fix
Bot does not respond to `@mentions`	Invite the bot to the channel (`/invite @Vaquill`). Verify `app_mention` is subscribed. Check tokens.
Bot does not respond to DMs	Add `im:history`, `im:read`, `im:write` scopes and reinstall. Subscribe to `message.im`.
”This app responded with an error” on slash commands	Cold-start timeout. Use Socket Mode or a host that keeps the process warm.
401 from Vaquill API	`VAQUILL_API_KEY` is invalid or expired. Generate a new one from your dashboard.
Bot replies to its own messages	Confirm `IGNORE_BOT_MESSAGES=true` (default) and that the user ID is logged at startup.

Discord

Same engine, prefix-command UX.

Microsoft Teams

Adaptive Cards on Azure Bot Framework.

Chatbots overview

Compare all six platforms.

Authentication

How Vaquill API keys work.

Overview

MCP Servers

Chatbots

Widgets

Browser

Automation

Features

Prerequisites

Platform setup

Socket Mode vs HTTP Mode

Quickstart

Configuration

Commands

Deployment

Docker Compose (recommended)

Standalone Docker

Cloud hosts

Railway

Render

Fly.io

VPS + nginx

Troubleshooting

Discord

Microsoft Teams

Chatbots overview

Authentication

​Features

​Prerequisites

​Platform setup

​Socket Mode vs HTTP Mode

​Quickstart

​Configuration

​Commands

​Deployment

​Docker Compose (recommended)

​Standalone Docker

​Cloud hosts

Railway

Render

Fly.io

VPS + nginx

​Troubleshooting

​Related

Discord

Microsoft Teams

Chatbots overview

Authentication

Features

Prerequisites

Platform setup

Socket Mode vs HTTP Mode

Quickstart

Configuration

Commands

Deployment

Docker Compose (recommended)

Standalone Docker

Cloud hosts

Troubleshooting

Related