Slack Bot

Drop the Vaquill legal AI into Slack with @mentions, slash commands, DMs, and in-thread context.

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.

1. 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.

2. 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

3. 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.

4. Register slash commands

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

5. 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.

6. 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

1. 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
   
2. 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
   
3. 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.

Related

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.